docs: complete the hero samples; own the TypedActivity portability boundary

README.md

@@ -18,14 +18,23 @@ import { Effect, Schema } from "effect";
 import * as Workflow from "effect/unstable/workflow/Workflow";
 import * as DurableClock from "effect/unstable/workflow/DurableClock";
 import * as DurableDeferred from "effect/unstable/workflow/DurableDeferred";
+import * as TypedActivity from "@springbird/effect-temporal/typed-activity";
+import { callActivity, workflowBundle } from "@springbird/effect-temporal/engine-sandbox";
 import { WorkflowClient } from "@springbird/effect-temporal/client";
 
-// Define once — shared by the workflow bundle and every client.
+// Define once — shared by the workflow bundle, the worker, and every client.
 const OrderFlow = Workflow.make("orderFlow", {
   payload: { orderId: Schema.String },
   idempotencyKey: ({ orderId }) => orderId,
   success: Schema.String,
 });
+const Charge = TypedActivity.make("charge", {
+  payload: { orderId: Schema.String },
+  success: Schema.String,
+});
+const ManagerApproval = DurableDeferred.make("manager-approval", {
+  success: Schema.String,
+});
 
 // The body is an Effect, running durably inside
 // the Temporal sandbox — the same authoring Effect's other engines use:

docs/guide/activities.md

@@ -11,6 +11,19 @@ Both run under the same per-call cancellation scope. If you find yourself
 building a typed error channel on top of a raw call, that's the sign you
 wanted a `TypedActivity`.
 
+::: info Portability note
+Unlike workflow definitions — which are pure upstream API and run on any
+engine — `TypedActivity` and `callActivity` are this package's own, and a
+workflow using them is Temporal-shaped. That is a deliberate consequence of
+Temporal's execution model: upstream `Activity.make` carries its
+implementation as a **closure** over workflow state, which other engines can
+run in-process, but Temporal executes activities on a separate worker that a
+closure cannot reach. `TypedActivity` is the serializable projection that
+boundary forces: a name plus schemas, implemented on the worker. Upstream
+`Activity.make` still works here as an in-sandbox typed seam (see below) —
+it just isn't where I/O can live under Temporal.
+:::
+
 ## Typed activities
 
 Declare once; the definition is temporal-free and loads in the sandbox bundle, the worker, and clients alike.

docs/index.md

@@ -35,6 +35,7 @@ import * as Workflow from "effect/unstable/workflow/Workflow";
 import * as DurableClock from "effect/unstable/workflow/DurableClock";
 import * as DurableDeferred from "effect/unstable/workflow/DurableDeferred";
 import * as TypedActivity from "@springbird/effect-temporal/typed-activity";
+import { callActivity, workflowBundle } from "@springbird/effect-temporal/engine-sandbox";
 import { WorkflowClient } from "@springbird/effect-temporal/client";
 
 // 1. Define once: shared by the workflow bundle, the worker, and every client.