@vercel/factory 0.0.14 → 0.0.16

package/docs/getting-started.md

@@ -0,0 +1,104 @@
+# Getting started with `@vercel/factory`
+
+This guide isolates Factory's durable Task state with process-local storage. It calls no model,
+Eve agent, provider, sandbox, HTTP endpoint, or planner, so it is safe to run as a local smoke
+test. For the primary agent path, continue with
+[Run an Eve agent as a Factory Task](recipes/eve-agent.md).
+
+## Requirements
+
+- Node.js 24 or newer
+- An ESM project (`"type": "module"` in `package.json`) or an `.mts` file
+- `@vercel/factory` and its required `eve` and `zod` peers
+
+Install them with your package manager:
+
+```sh
+pnpm add @vercel/factory eve zod
+```
+
+Optional storage, sandbox, and harness integrations have additional peer dependencies. Install
+those only when you import the corresponding capability path; the package manifest declares their
+supported ranges.
+
+## Run a local task
+
+Save this as `factory-quickstart.mts`. The example uses only public capability entry points from
+the installed package.
+
+<!-- runnable-example:start -->
+
+```ts
+import { repositoryIdSchema, repositoryScope } from "@vercel/factory";
+import { createInMemoryDriver, createStores } from "@vercel/factory/storage";
+import { taskWork } from "@vercel/factory/workflows";
+
+const repositoryId = repositoryIdSchema.parse("repo_example");
+const stores = createStores({ driver: createInMemoryDriver() });
+
+const task = await stores.tasks.create({
+  repositoryIds: repositoryScope(repositoryId),
+  kind: "analysis",
+  origin: { operator: "local:quickstart" },
+  replyTo: { channel: "local", address: "quickstart" },
+  work: {
+    ...taskWork({
+      title: "Return a greeting",
+      input: { name: "Factory" },
+    }),
+    completionCriteria: ["Return a greeting for the supplied name"],
+  },
+  dedupeKey: "quickstart:greeting",
+});
+
+const running = await stores.tasks.transition(task.id, "running");
+const completed = await stores.work.complete({
+  task: { taskId: running.id, attempt: running.attempt },
+  output: { greeting: "Hello, Factory!" },
+});
+const stored = await stores.tasks.get(task.id);
+
+if (
+  completed.state !== "succeeded" ||
+  stored === null ||
+  stored.state !== "succeeded" ||
+  stored.workResult === undefined
+) {
+  throw new Error("Expected the Task to succeed");
+}
+if (JSON.stringify(stored.workResult.output) !== '{"greeting":"Hello, Factory!"}') {
+  throw new Error("Expected the completed greeting");
+}
+
+console.log(
+  JSON.stringify({ taskId: stored.id, state: stored.state, output: stored.workResult.output }),
+);
+```
+
+<!-- runnable-example:end -->
+
+Run it directly with Node.js 24:
+
+```sh
+node factory-quickstart.mts
+```
+
+The command prints a generated Task ID, the `succeeded` state, and the validated output:
+
+```json
+{ "taskId": "task_<generated>", "state": "succeeded", "output": { "greeting": "Hello, Factory!" } }
+```
+
+`createInMemoryDriver` is non-durable and intended for development and tests. A production factory
+supplies a persistent driver and owns its authorization, workflow policy, credentials, and
+provider configuration.
+
+## What happened
+
+`taskWork` selected the built-in `task@1` workflow, which accepts bounded JSON input and output.
+Task creation persisted a queued Task and its graph root. The explicit transition started the
+Task, and `stores.work.complete` validated and recorded its output before moving it to `succeeded`.
+
+Task kinds are descriptive. Workflow bindings select input and output contracts, and exact agent
+routes select Eve agent execution. See the [documentation index](index.md) for typed workflows,
+persistent storage, execution providers, Task messages, and operator clients.

package/docs/index.md

@@ -0,0 +1,100 @@
+# `@vercel/factory` consumer documentation
+
+These guides and declaration files ship with the installed package. They describe the same version
+of `@vercel/factory` that your project resolves.
+
+Start with [Run an Eve agent as a Factory Task](recipes/eve-agent.md) for the primary integration
+path. The [local Task quickstart](getting-started.md) isolates the durable state model without
+running an agent. Read [runtime composition](runtime-integration.md) when assembling a complete
+factory.
+
+## Runnable recipes
+
+Each recipe contains a complete, self-checking TypeScript program. The programs use local storage
+or injected local boundaries, require no credentials, and are compiled and executed against both
+the built package and the packed release artifact.
+
+| Goal                                                    | Recipe                                                              | Main APIs                                                               |
+| ------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| Run and complete an Eve agent in one durable attempt    | [Eve agent integration](recipes/eve-agent.md)                       | `startEveSession`, `withFactoryTask`, Task tools and hooks              |
+| Submit a schema-specific result from an Eve tool        | [Typed Eve result](recipes/typed-eve-result.md)                     | `defineWorkflow`, `requireTaskExecution`, `completeWorkflow`            |
+| Pause for an authenticated answer and resume Eve        | [Human input](recipes/human-input.md)                               | `request_human_input`, `answer_question`, `sweepQueued`                 |
+| Enforce execution order and hand results between agents | [Dependent Eve agents](recipes/dependent-tasks.md)                  | dependencies, `sweepQueued`, authenticated Task tools                   |
+| Define typed work and connect a non-Eve provider        | [Custom workflow and local execution](recipes/custom-workflow.md)   | `defineWorkflow`, `dispatchTask`, `launchExecution`, `completeWorkflow` |
+| Reopen durable storage and recover workflow-owned work  | [Persistence and restart recovery](recipes/persistence-recovery.md) | `applyFactoryMigrations`, `createPostgresDriver`, `recover`             |
+| Stop provider or Eve work and fence late output         | [Cancellation](recipes/cancellation.md)                             | `cancelExecution`, `cancelEveSession`, attempt fences                   |
+| Recover Eve failures and exhaust bounded retries        | [Retry and recovery](recipes/retry-recovery.md)                     | `createFactoryHooks`, `sweepQueued`, authenticated completion           |
+| Send and process an authenticated typed message         | [Task messaging](recipes/task-messaging.md)                         | `requireTaskExecution`, message protocols, `processTaskMessage`         |
+
+Read them in table order when building an Eve-based factory. They progress from one authenticated
+session through typed results, human pauses, graph ordering, alternative execution, persistence,
+lifecycle recovery, and inter-Task communication.
+
+## Behavioral contracts
+
+The installed declarations are the source of truth for operation semantics. In particular:
+
+- `createStores` and `FactoryStores.tasks` document persistence, deduplication, transition fences,
+  and when a mutation is durable.
+- `dispatchTask` and `sweepQueued` distinguish accepted execution, completed work, retryable gates,
+  terminal routing failures, and provider acceptance that remains ambiguous.
+- `FactoryClient` documents idempotency keys, optimistic execution matching, request completion,
+  redirects, timeouts, and validated responses.
+- `createBlobDriver` and `createPostgresDriver` document concurrency, retry, migration, and
+  compare-and-swap responsibilities.
+
+Search the linked declaration files below for the exact installed signatures and JSDoc. Full
+recipes remain the preferred starting point when several operations must be composed.
+
+## Find the right capability
+
+| Goal                                                   | Import path                                                        | Start with                                                            | Version-matched declarations                                                                                                                                                       |
+| ------------------------------------------------------ | ------------------------------------------------------------------ | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Configure a factory and validate repository identity   | `@vercel/factory`                                                  | `defineFactory`, `repositoryIdSchema`, `repositoryIdForSlug`          | [root declarations](../dist/index.d.mts)                                                                                                                                           |
+| Create Tasks, graphs, messages, approvals, and effects | `@vercel/factory/tasks`                                            | `Task`, `createDefaultTaskMessageProtocols`, `taskBoundMessagePolicy` | [Task declarations](../dist/tasks.d.mts)                                                                                                                                           |
+| Define versioned work and exact agent routes           | `@vercel/factory/workflows`                                        | `defineWorkflow`, `defineWorkflows`, `taskWork`, `defineAgentRoutes`  | [workflow declarations](../dist/workflows.d.mts)                                                                                                                                   |
+| Create a store engine or local in-memory store         | `@vercel/factory/storage`                                          | `createStores`, `createInMemoryDriver`, `StoreDriver`                 | [storage declarations](../dist/storage.d.mts)                                                                                                                                      |
+| Use Blob or Postgres persistence                       | `@vercel/factory/storage/blob`, `@vercel/factory/storage/postgres` | `createBlobDriver`, `createPostgresDriver`                            | [Blob](../dist/blob/index.d.mts), [Postgres](../dist/postgres/index.d.mts)                                                                                                         |
+| Dispatch work through execution providers              | `@vercel/factory/execution`                                        | `dispatchTask`, `ExecutionAdapter`                                    | [execution declarations](../dist/execution-public.d.mts)                                                                                                                           |
+| Run bounded recursive planning                         | `@vercel/factory/planning`                                         | `createPlannerRuntime`, `createPlannerMessageProtocols`               | [planning declarations](../dist/planning/runtime.d.mts)                                                                                                                            |
+| Apply budgets and inspect immutable receipts           | `@vercel/factory/budgets`, `@vercel/factory/receipts`              | `canReserve`, `sweepBudget`, `receiptSchema`                          | [budgets](../dist/budgets.d.mts), [receipts](../dist/receipts.d.mts)                                                                                                               |
+| Normalize intake and deliver replies                   | `@vercel/factory/signals`, `@vercel/factory/communication`         | `signalSchema`, `createTaskCommunicationReconciler`                   | [signals](../dist/signals.d.mts), [communication](../dist/communication.d.mts)                                                                                                     |
+| Build browser or terminal operator clients             | `@vercel/factory/client`                                           | `FactoryClient`, `followSessionStream`, `Transcript`                  | [client declarations](../dist/client.d.mts)                                                                                                                                        |
+| Mount server handlers or a Next.js factory             | `@vercel/factory/api`, `@vercel/factory/next`                      | `createFactoryApi`, `buildFactory`                                    | [API](../dist/api.d.mts), [Next.js](../dist/build-factory.d.mts)                                                                                                                   |
+| Compose the supplied software-development policy       | `@vercel/factory/presets/software-development`                     | `createSoftwareDevelopmentTools`, `dispatchSoftwareDevelopmentWork`   | [preset declarations](../dist/presets/software-development.d.mts)                                                                                                                  |
+| Add sandbox execution                                  | `@vercel/factory/sandbox`                                          | `createSandboxExecutionAdapter`, `createTaskSandboxEnvironment`       | [sandbox declarations](../dist/sandbox/index.d.mts)                                                                                                                                |
+| Add provider adapters                                  | `@vercel/factory/integrations/<provider>`                          | Select GitHub, Slack, DeepSec, or Vercel explicitly                   | [GitHub](../dist/integrations/github.d.mts), [Slack](../dist/integrations/slack.d.mts), [DeepSec](../dist/integrations/deepsec.d.mts), [Vercel](../dist/integrations/vercel.d.mts) |
+
+Use the narrowest capability path that owns the API. This avoids loading server-only or optional
+integrations accidentally and gives each declaration one stable import path.
+
+## Domain capabilities
+
+Software-development records and operations are available from:
+
+- `@vercel/factory/changes` for Change lifecycle and verification
+- `@vercel/factory/findings` for findings and remediation
+- `@vercel/factory/code-review` for review policy and tools
+- `@vercel/factory/pull-requests` for publication and merge-conflict operations
+- `@vercel/factory/work-triage` for existing-work lookup
+- `@vercel/factory/delivery-metrics` for delivery ledger metrics
+
+Each path has a matching declaration entry under `dist/`. Provider-specific implementations remain
+under `@vercel/factory/integrations/<provider>`.
+
+## Reading the API
+
+Public declarations carry concise JSDoc summaries, and public schemas expose field descriptions at
+runtime. Search the linked `.d.mts` files for a symbol to inspect the exact installed signature.
+Configuration inputs use `*Options`, operation results use `*Result`, and errors use `*Error`.
+Factories use `create*`; declarative validators and registries use `define*`.
+
+The package is pre-1.0. Replaced names and import paths can be removed in a patch release. Review
+the [installed changelog](../CHANGELOG.md) before upgrading, and pin a version when a deployment
+requires a stable contract.
+
+The declarations are validated with TypeScript 5.9.3 and 7.0.2. Core workflows and the Blob adapter
+use `nodeNext` module resolution with library checking enabled. The `/client` entry point uses
+`bundler` resolution in a browser-only fixture that does not load Node or server-integration types.
+The Postgres adapter is checked with its Drizzle peer and `skipLibCheck` because Drizzle's
+declaration graph includes declarations for optional database drivers.

package/docs/recipes/cancellation.md

@@ -0,0 +1,215 @@
+# Cancel an execution safely
+
+Cancellation records canonical Task state before asking the provider to stop. A provider stop may
+be retried, and any final measured usage is retained and settled once.
+
+The program covers both the provider-neutral `ExecutionAdapter` contract and the Eve session
+boundary. In both cases the application records canonical cancellation before asking the provider
+to stop.
+
+## Run the recipe
+
+Save this as `cancellation.mts` in an ESM project with `@vercel/factory`, `eve`, and `zod`
+installed.
+
+<!-- runnable-example:start -->
+
+```ts
+import type { ToolContext } from "eve/tools";
+import {
+  cancelEveSession,
+  createTaskTools,
+  factoryTaskAttemptAttribute,
+  factoryTaskAttribute,
+  startEveSession,
+  taskHeaders,
+} from "@vercel/factory";
+import {
+  cancelExecution,
+  dispatchTask,
+  ExecutionFenceError,
+  inspectExecution,
+  launchExecution,
+  type ExecutionAdapter,
+  type ExecutionResult,
+} from "@vercel/factory/execution";
+import { createInMemoryDriver, createStores } from "@vercel/factory/storage";
+import { parseAgentRouteBinding, taskWork } from "@vercel/factory/workflows";
+
+const stores = createStores({ driver: createInMemoryDriver() });
+const repository = await stores.repositories.put({
+  schemaVersion: 1,
+  id: "repo_recipe03",
+  slug: "example/project",
+  defaultBranch: "main",
+  enabled: true,
+  dependsOn: [],
+  connectedAt: new Date().toISOString(),
+});
+const task = await stores.tasks.create({
+  repositoryIds: [repository.id],
+  kind: "example",
+  origin: { operator: "local:recipe" },
+  replyTo: { channel: "local", address: "cancellation" },
+  work: taskWork({ title: "Run cancellable work" }),
+});
+const running = await stores.tasks.transition(task.id, "running");
+const execution = { provider: "local", sessionId: "cancel-1" };
+const cancelledResult: ExecutionResult = {
+  status: "cancelled",
+  execution,
+  artifacts: [],
+  usage: { computeMs: 5, costUsd: 0.05 },
+  reason: "Stopped by the operator",
+};
+let providerObservedCancellation = false;
+const adapter: ExecutionAdapter = {
+  async start() {
+    return execution;
+  },
+  async inspect() {
+    return { status: "finished", result: cancelledResult };
+  },
+  async stop() {
+    providerObservedCancellation = (await stores.tasks.get(task.id))?.state === "cancelled";
+    return cancelledResult;
+  },
+};
+await launchExecution({
+  stores,
+  adapter,
+  request: {
+    taskId: running.id,
+    attempt: running.attempt,
+    repository: { slug: repository.slug, baseSha: "b".repeat(40) },
+    harness: "codex",
+    prompt: "Perform cancellable work",
+    allowedConstructs: [],
+    environment: { timeoutMs: 1_000 },
+    limits: { maxCostUsd: 1 },
+  },
+});
+
+const cancelled = await cancelExecution({
+  stores,
+  task: { taskId: running.id, attempt: running.attempt },
+  adapter,
+  reason: "Operator cancelled the example",
+});
+let lateResultRejected = false;
+try {
+  await inspectExecution({
+    stores,
+    task: { taskId: running.id, attempt: running.attempt },
+    adapter,
+  });
+} catch (error) {
+  lateResultRejected = error instanceof ExecutionFenceError;
+}
+if (
+  cancelled.state !== "cancelled" ||
+  cancelled.settledUsd !== 0.05 ||
+  !providerObservedCancellation ||
+  !lateResultRejected ||
+  cancelled.workResult !== undefined
+) {
+  throw new Error("Expected cancellation, settlement, and late-result fencing");
+}
+
+const eveRoute = parseAgentRouteBinding({ id: "worker", version: 1 });
+const eveTask = await stores.tasks.create({
+  repositoryIds: [repository.id],
+  kind: "example",
+  origin: { operator: "local:recipe" },
+  replyTo: { channel: "local", address: "cancellation" },
+  work: { ...taskWork({ title: "Cancel an Eve agent" }), route: eveRoute },
+});
+const runningEve = await dispatchTask(stores, {
+  taskId: eveTask.id,
+  route: eveRoute,
+  launch: (claimed) =>
+    startEveSession({
+      agentUrl: "https://factory.example/eve/agents/worker",
+      message: `Work Task ${claimed.id}`,
+      operationId: `factory-task:${claimed.id}:${claimed.attempt}`,
+      headers: taskHeaders({ taskId: claimed.id, attempt: claimed.attempt }),
+      fetch: async () => Response.json({ sessionId: "ses_cancel_eve" }),
+    }),
+});
+if (runningEve.execution?.provider !== "eve") throw new Error("Expected an Eve execution");
+const eveContext = {
+  session: {
+    id: runningEve.execution.sessionId,
+    auth: {
+      initiator: {
+        attributes: {
+          [factoryTaskAttribute]: runningEve.id,
+          [factoryTaskAttemptAttribute]: String(runningEve.attempt),
+        },
+      },
+    },
+  },
+} as unknown as ToolContext;
+
+await stores.tasks.transition(runningEve.id, "cancelled", {
+  expectFrom: "running",
+  expectAttempt: runningEve.attempt,
+  expectExecution: runningEve.execution,
+  reason: "Operator cancelled the Eve Task",
+});
+let eveObservedCancellation = false;
+let confirmedSession = "";
+await cancelEveSession({
+  agentUrl: "https://factory.example/eve/agents/worker",
+  sessionId: runningEve.execution.sessionId,
+  headers: taskHeaders({ taskId: runningEve.id, attempt: runningEve.attempt }),
+  fetch: async (input, init) => {
+    const request = new Request(input, init);
+    eveObservedCancellation =
+      request.url.endsWith("/eve/v1/session/ses_cancel_eve/cancel") &&
+      (await stores.tasks.get(runningEve.id))?.state === "cancelled";
+    return Response.json({ status: "cancelling" });
+  },
+  stream: async function* (input) {
+    confirmedSession = input.sessionId;
+    yield { type: "session.waiting" };
+  },
+});
+let lateEveCompletionRejected = false;
+try {
+  await createTaskTools(stores).finish_task.execute(
+    { taskId: runningEve.id, summary: "Late agent output" },
+    eveContext,
+  );
+} catch {
+  lateEveCompletionRejected = true;
+}
+if (
+  !eveObservedCancellation ||
+  confirmedSession !== runningEve.execution.sessionId ||
+  !lateEveCompletionRejected
+) {
+  throw new Error("Expected task-first Eve cancellation and late-tool fencing");
+}
+
+console.log(
+  JSON.stringify({
+    adapter: { state: cancelled.state, settledUsd: cancelled.settledUsd },
+    eve: { state: (await stores.tasks.get(runningEve.id))?.state, confirmedSession },
+  }),
+);
+```
+
+<!-- runnable-example:end -->
+
+## What it proves
+
+`cancelExecution` persists cancellation before invoking `adapter.stop`. It records the provider's
+final usage and settles measured cost, while the attempt fence prevents a late inspection from
+completing cancelled work. If stopping is ambiguous, retry `cancelExecution` with the same Task and
+attempt; adapters must make `stop` idempotent.
+
+For Eve, transition the Task with its attempt and execution fences, then pass the persisted session
+ID to `cancelEveSession`. The client waits for Eve's stream to confirm that the session is no longer
+running. A late tool call fails because the Task is already terminal. Provider cancellation and
+Task persistence are separate writes, so recovery should retry the idempotent provider request.

package/docs/recipes/custom-workflow.md

@@ -0,0 +1,153 @@
+# Custom workflow with a local execution adapter
+
+Use this recipe when a Task needs typed input and output plus an execution provider. The local
+adapter stands in for a model or sandbox provider, so the complete dispatch, inspection, and
+completion path runs without credentials or network access.
+
+This is the provider-adapter path used for coding harnesses, sandboxes, and other execution systems
+that return bounded evidence. It is not the usual Eve-agent setup. For an Eve agent, start with
+[Run an Eve agent as a Factory Task](./eve-agent.md), then expose the workflow output through an
+[authenticated typed result tool](./typed-eve-result.md).
+
+## Run the recipe
+
+Save this as `custom-workflow.mts` in an ESM project with `@vercel/factory`, `eve`, and `zod`
+installed.
+
+<!-- runnable-example:start -->
+
+```ts
+import { z } from "zod";
+import {
+  dispatchTask,
+  inspectExecution,
+  launchExecution,
+  type ExecutionAdapter,
+  type ExecutionResult,
+} from "@vercel/factory/execution";
+import { createInMemoryDriver, createStores } from "@vercel/factory/storage";
+import {
+  defineWorkflow,
+  defineWorkflows,
+  parseAgentRouteBinding,
+  taskWork,
+} from "@vercel/factory/workflows";
+
+const greetingWorkflow = defineWorkflow({
+  id: "greeting",
+  version: 1,
+  input: z.strictObject({ name: z.string().min(1) }),
+  output: z.strictObject({ greeting: z.string().min(1) }),
+});
+const route = parseAgentRouteBinding({ id: "local-worker", version: 1 });
+const stores = createStores({
+  driver: createInMemoryDriver(),
+  workflows: defineWorkflows([greetingWorkflow]),
+});
+const repository = await stores.repositories.put({
+  schemaVersion: 1,
+  id: "repo_recipe01",
+  slug: "example/project",
+  defaultBranch: "main",
+  enabled: true,
+  dependsOn: [],
+  connectedAt: new Date().toISOString(),
+});
+const task = await stores.tasks.create({
+  repositoryIds: [repository.id],
+  kind: "example",
+  origin: { operator: "local:recipe" },
+  replyTo: { channel: "local", address: "custom-workflow" },
+  work: {
+    ...taskWork({
+      title: "Create a greeting",
+      input: { name: "Factory" },
+      workflow: greetingWorkflow,
+    }),
+    route,
+    completionCriteria: ["Return a greeting for the supplied name"],
+  },
+});
+
+const execution = { provider: "local", sessionId: "greeting-1" };
+const result: ExecutionResult = {
+  status: "completed",
+  execution,
+  artifacts: [{ kind: "report", ref: "memory:greeting-1" }],
+  usage: { computeMs: 1, costUsd: 0 },
+};
+const adapter: ExecutionAdapter = {
+  async start({ launchKey }) {
+    if (launchKey !== `factory-task:${task.id}:1`) throw new Error("Unexpected launch key");
+    return execution;
+  },
+  async inspect() {
+    return { status: "finished", result };
+  },
+  async stop() {
+    return { ...result, status: "cancelled" };
+  },
+};
+
+const dispatched = await dispatchTask(stores, {
+  taskId: task.id,
+  route,
+  launch: (running) =>
+    launchExecution({
+      stores,
+      adapter,
+      request: {
+        taskId: running.id,
+        attempt: running.attempt,
+        repository: { slug: repository.slug, baseSha: "a".repeat(40) },
+        harness: "codex",
+        prompt: `Greet ${greetingWorkflow.input.parse(running.work.input).name}`,
+        allowedConstructs: [],
+        environment: { timeoutMs: 1_000 },
+        limits: { maxCostUsd: 1 },
+      },
+    }),
+});
+const observed = await inspectExecution({
+  stores,
+  task: { taskId: dispatched.id, attempt: dispatched.attempt },
+  adapter,
+});
+if (observed.status !== "finished" || observed.result.status !== "completed") {
+  throw new Error("Expected a completed local execution");
+}
+
+let invalidOutputRejected = false;
+try {
+  await stores.work.complete({
+    task: { taskId: dispatched.id, attempt: dispatched.attempt },
+    output: { greeting: 42 },
+  });
+} catch {
+  invalidOutputRejected = true;
+}
+if (!invalidOutputRejected) throw new Error("Expected invalid workflow output to be rejected");
+
+const completed = await stores.work.completeWorkflow({
+  task: { taskId: dispatched.id, attempt: dispatched.attempt },
+  workflow: greetingWorkflow.binding,
+  output: { greeting: "Hello, Factory!" },
+});
+const output = greetingWorkflow.output.parse(completed.workResult?.output);
+if (completed.state !== "succeeded" || output.greeting !== "Hello, Factory!") {
+  throw new Error("Expected validated workflow completion");
+}
+
+console.log(JSON.stringify({ state: completed.state, output }));
+```
+
+<!-- runnable-example:end -->
+
+## What it proves
+
+`dispatchTask` owns the queued-to-running admission and exact route check. `launchExecution` gives
+the adapter a stable per-attempt key and records its provider reference. Inspection returns
+evidence but does not complete the Task; workflow code explicitly validates and records the output.
+
+Replace the local adapter with a provider adapter in production. Keep the workflow definition and
+its exact version registered anywhere stored Tasks from that version may be read or completed.