@githolon/dsl 0.1.0

package/src/framework/impure_capability.ts

@@ -0,0 +1,643 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * framework/impure_capability.ts — the FRAMEWORK Order→Receipt mechanism (tenant-agnostic).
+ *
+ * ── Why this module exists (the framework↔tenant line) ───────────────────────
+ * A *provider-side intent* in Nomos 1 was an ephemeral job: dispatch → the
+ * handler ran a side-effect inline (build a ZIP, render a report, dispatch work
+ * across user workspaces) → mutated the HTTP response → fired a follow-up
+ * notification. Nothing durable, nothing replayable, and it leaned on the deleted
+ * `dispatch(IntentBase)` + response-mutation back-channel.
+ *
+ * Nomos 2's law is "**every authored intent folds SOME aggregate**" (contract §1) —
+ * there is no ephemeral job. The faithful shape of an async impure capability is therefore
+ * an **Order → Receipt** pair of ordinary `WireIntent`s with a first-class lifecycle law:
+ *
+ *   • **Order**   — a normal intent whose role is the request: a peer dispatches
+ *                   `order…(params, status:'requested')`,
+ *                   `.creates` a task aggregate keyed by a KERNEL-MINTED order id
+ *                   (`<OrderType>_<uuidv7>`, via the marker-driven front-door; idempotent on
+ *                   replay by capture).
+ *   • **(impure work)** — a capability provider watches `status:'requested'` rows, performs
+ *                   the side-effect (rendering / upload / multi-target provider work — a host/report
+ *                   concern, NOT part of any fold), then authors a Receipt intent.
+ *   • **Receipt** — a normal intent whose role is the outcome:
+ *                   `complete…(requestId, resultRef, completedAt)` → `status:'completed'`
+ *                   OR `fail…(requestId, failureReason, failedAt)` → `status:'failed'`.
+ *                   Some domains also expose explicit blocked/DLQ receipts using the
+ *                   same envelope fields below.
+ *
+ * Order and Receipt are roles/facets of `Intent`, not special admission objects, job-table rows,
+ * or a privileged mutation channel.
+ *
+ * **Reporting upward = the authoring peer reactively WATCHES the task aggregate.** The receipt
+ * arrives as an ordinary projection update (no polling, no fire-and-forget push, no
+ * response-mutation). This is exactly the proven `ExportJobAggregate` shape
+ * (the tenant domains package `thing_structures`) generalised into a reusable framework pattern so a
+ * domain dev does NOT hand-roll the {aggregate + order + complete + fail} quartet each
+ * time — they DECLARE the task's params and get the quartet for free, like `rbac.ts`
+ * gives grant/revoke for free.
+ *
+ * ── What is framework vs tenant ──────────────────────────────────────────────
+ * Framework (here): the task LIFECYCLE shape — the `requestId / status / resultRef? /
+ * failureReason? / completedAt? / blockedReason? / nextAction? / deadLetterReason?`
+ * envelope, the `requested|completed|failed|blocked|deadLettered` status
+ * vocabulary, the deterministic instance-id rule (the task is keyed by its own
+ * requestId), and the three plan builders that write that envelope. Tenant: the task's
+ * NAME (`exportJob`, `thingExport`) and its request PARAMS (which group, which
+ * filters) — the domain dev supplies those via `impureCapability({...})`.
+ *
+ * ── Boundaries this module deliberately does NOT cross ───────────────────────
+ *  • The side-effect itself (rendering, GCS upload, multi-target provider work) is a
+ *    host/report concern, never part of a fold — the provider does it, the Receipt intent
+ *    only records the content-addressed RESULT (a blob ref / url as `resultRef`).
+ *  • Cross-workspace effects (e.g. propagate-thing-rename to N user workspaces) are the
+ *    PR tier (contract §5b / conformance X1), not a single impure capability — a provider opens
+ *    one PR per target workspace. A impure capability is the SAME-workspace async-job half;
+ *    the §5b PR is the cross-workspace half. They compose; this lifecycle pattern is the former.
+ *  • Authoring the Receipt intent goes through the ONE write path like any author — the
+ *    reactor is itself a Nomos peer (`admission-hosting.md`: provider-originated intents author
+ *    *through* a policy unit too). This module only provides the directive SHAPES.
+ */
+import { z } from "zod";
+import { aggregate, instance, type AggregateHandle } from "../aggregate.js";
+import { t, type Field } from "../fields.js";
+import { Lww } from "../drivers.js";
+import { set, type PlannedOp } from "../ops.js";
+import { directive, type RequirableDirective } from "../directive.js";
+import { executeDirectiveToIntent } from "../wire_encode.js";
+import type { WireIntent } from "../wire.js";
+import type { Ports } from "../ctx.js";
+
+/**
+ * The impure-capability lifecycle vocabulary — framework-fixed. A task is `requested` when
+ * the peer orders it; the provider authors the ordinary Receipt intent that flips it
+ * to `completed` (with a `resultRef`) or `failed` (with a `failureReason`). One-way after a
+ * terminal state: the lifecycle law is terminal-once at the gate/envelope, not a separate
+ * privileged mutation channel.
+ */
+export const IMPURE_CAPABILITY_STATUSES = [
+  "requested",
+  "completed",
+  "failed",
+  "blocked",
+  "deadLettered",
+] as const;
+export type ImpureCapabilityStatus = (typeof IMPURE_CAPABILITY_STATUSES)[number];
+
+/**
+ * The framework envelope fields EVERY impure-capability aggregate carries — the Order→Receipt
+ * lifecycle, independent of the tenant's request params:
+ *
+ *  - requestId      Lww — the task's own id (== the aggregate instance id; a
+ *                   KERNEL-MINTED `<OrderType>_<uuidv7>`). Immutable-after-create (the
+ *                   create-only gap; modelled Lww).
+ *  - requestedBy    Lww — who ordered the task (provenance). Immutable-after-create.
+ *  - requestedAt    Int — epoch-ms the order was authored. Immutable-after-create.
+ *  - status         Lww enum — `requested` → the reactor flips to a terminal status.
+ *  - resultRef      Lww json (OPTIONAL) — the content-addressed RESULT the reactor
+ *                   records on completion (a blob ref / download url JSON leaf). Absent
+ *                   on a fresh request; absent on failure.
+ *  - failureReason  Lww (OPTIONAL) — set only when the reactor flips to `failed`.
+ *  - completedAt    Int (OPTIONAL) — epoch-ms the task reached its terminal state
+ *                   (completed OR failed). Absent while `requested`.
+ *  - blockedReason  Lww (OPTIONAL) — why the provider cannot proceed without an
+ *                   external condition.
+ *  - blockedAt      Int (OPTIONAL) — epoch-ms the task was parked as blocked.
+ *  - nextAction     Lww (OPTIONAL) — human/host-action hint, e.g. refreshAuth.
+ *  - deadLetterReason Lww (OPTIONAL) — why the order was moved to the DLQ.
+ *  - deadLetteredAt Int (OPTIONAL) — epoch-ms the order entered the DLQ.
+ *
+ * The OPTIONALs are `.optional()` so a freshly-ordered task (which folds none of them)
+ * decodes on the generated read type — the same read-decode discipline the rest of the
+ * framework uses (identity NOTE 1a / gap 1).
+ */
+export const IMPURE_CAPABILITY_ENVELOPE = {
+  requestId: t.string().merge(Lww),
+  requestedBy: t.string().merge(Lww),
+  requestedAt: t.int().merge(Lww),
+  status: t.enum(IMPURE_CAPABILITY_STATUSES).merge(Lww),
+  resultRef: t.json().merge(Lww).optional(),
+  failureReason: t.string().merge(Lww).optional(),
+  completedAt: t.int().merge(Lww).optional(),
+  blockedReason: t.string().merge(Lww).optional(),
+  blockedAt: t.int().merge(Lww).optional(),
+  nextAction: t.string().merge(Lww).optional(),
+  deadLetterReason: t.string().merge(Lww).optional(),
+  deadLetteredAt: t.int().merge(Lww).optional(),
+  // The FRAMEWORK Order↔Receipt CLOSURE link (OPTIONAL): the id of the Order this
+  // RECEIPT closes (== the task's own requestId — the reactor mutates the task instance).
+  // GENERIC, written by every impureCapability Receipt (complete OR fail), so the read
+  // projection answers "is Order O closed, by which Receipt, with what result" in O(1)
+  // off the `(closesOrder, order_id)` index — never a ledger scan. Absent while
+  // `requested` (a fresh order has no closing receipt). Wire-identical to the Rust
+  // reactor's `closesOrder` op (`git-holon::reactor::receipt_intent`,
+  // `kernel::manifest_view::IMPURE_CAPABILITY_RECEIPT_FIELDS`).
+  closesOrder: t.string().merge(Lww).optional(),
+} as const;
+
+/**
+ * Declare a impure-capability aggregate: the framework {@link IMPURE_CAPABILITY_ENVELOPE} MERGED
+ * with the tenant's request-param fields. The tenant supplies the task's wire id (e.g.
+ * `"ExportJobAggregate"`) and its params (`{ targetKey: t.string()…, … }`);
+ * the framework supplies the lifecycle envelope.
+ *
+ * A param field name colliding with an envelope field is a COMPILE error (the spread
+ * key types overlap) — the envelope is reserved, so a tenant can't shadow `status`.
+ *
+ * Returns a plain {@link AggregateHandle}, so it lowers, codegens, and is referenced
+ * exactly like any hand-authored aggregate (no special-casing downstream).
+ */
+export function impureCapabilityAggregate<
+  const Id extends string,
+  P extends Record<string, Field>,
+>(id: Id, params: P): AggregateHandle<Id, typeof IMPURE_CAPABILITY_ENVELOPE & P> {
+  return aggregate(id, { ...IMPURE_CAPABILITY_ENVELOPE, ...params });
+}
+
+/**
+ * The deterministic instance-id rule: a impure capability is keyed by its OWN order id.
+ * That id is KERNEL-MINTED (`<OrderType>_<uuidv7>`, via the marker-driven front-door),
+ * captured + committed — so the `order` create is idempotent on replay by capture, and the
+ * `complete`/`fail` receipt addresses the SAME instance by reading the committed minted id.
+ * Trivial today (identity), but centralised here so the keying rule has ONE home (the
+ * symmetry with `rbac.ts`'s `userPermissionsInstanceId`).
+ */
+export function impureCapabilityInstanceId(requestId: string): string {
+  return requestId;
+}
+
+/** The Zod schema for the framework envelope fields the ORDER payload always carries. */
+const orderEnvelopeSchema = z.object({
+  requestId: z.string(),
+  requestedBy: z.string(),
+  requestedAt: z.number().int(),
+});
+
+/** The receipt-COMPLETE payload: the request id + the content-addressed result + when. */
+const completeSchema = z.object({
+  requestId: z.string(),
+  // The produced artifact's content-addressed ref (blob ref / url) as a JSON string.
+  resultRef: z.string(),
+  completedAt: z.number().int(),
+});
+
+/** The receipt-FAIL payload: the request id + the failure reason + when. */
+const failSchema = z.object({
+  requestId: z.string(),
+  failureReason: z.string(),
+  failedAt: z.number().int(),
+});
+
+/** The receipt-BLOCKED payload: parked pending external action, not retried blindly. */
+const blockSchema = z.object({
+  requestId: z.string(),
+  blockedReason: z.string(),
+  blockedAt: z.number().int(),
+  nextAction: z.string(),
+});
+
+/** The receipt-DLQ payload: terminal dead-letter, requiring a fresh order to recover. */
+const deadLetterSchema = z.object({
+  requestId: z.string(),
+  deadLetterReason: z.string(),
+  deadLetteredAt: z.number().int(),
+});
+
+/**
+ * The three plan builders. Each takes the task aggregate handle + the (already
+ * Zod-validated) payload and returns the `PlannedOp[]` writing the envelope. A tenant
+ * routes its directive `.plan` through these so the envelope shape can never drift —
+ * exactly how `rbac.ts`'s grant/revoke route through `buildBinding`/`writeBinding`.
+ */
+
+/**
+ * Bind an ENVELOPE-ONLY handle for `aggregateId` at its task instance. The op-builders
+ * write ONLY envelope fields (never tenant params), so they resolve `set()` against the
+ * fixed {@link IMPURE_CAPABILITY_ENVELOPE} field map — not the tenant's open param generic.
+ * Wire-identical: lowering keys off `aggregateId` + field names + values, all of which
+ * this carries (the tenant param fields live on the SAME aggregate id via the task
+ * handle; the envelope handle just types the envelope subset for `set()`).
+ */
+function envelopeInstance(aggregateId: string, requestId: string) {
+  const envelopeHandle = aggregate(aggregateId, IMPURE_CAPABILITY_ENVELOPE);
+  return instance(envelopeHandle, impureCapabilityInstanceId(requestId));
+}
+
+/**
+ * orderOps — the ORDER half. Seeds the envelope provenance + `status:'requested'`,
+ * PLUS the tenant's request params (the `paramOps` the caller's `.plan` supplies for
+ * its own fields). The task is bound to its requestId instance (#105).
+ */
+export function orderOps(
+  aggregateId: string,
+  p: z.infer<typeof orderEnvelopeSchema>,
+  paramOps: PlannedOp[] = [],
+): PlannedOp[] {
+  const taskInstance = envelopeInstance(aggregateId, p.requestId);
+  return [
+    set(taskInstance, "requestId", p.requestId),
+    set(taskInstance, "requestedBy", p.requestedBy),
+    set(taskInstance, "requestedAt", p.requestedAt),
+    set(taskInstance, "status", "requested"),
+    ...paramOps,
+  ];
+}
+
+/**
+ * completeOps — the RECEIPT (success) half: flip `status:'completed'`, record the
+ * content-addressed `resultRef`, stamp `completedAt`. The reactor's write once the
+ * side-effect finishes.
+ */
+export function completeOps(
+  aggregateId: string,
+  p: z.infer<typeof completeSchema>,
+  resultOps: PlannedOp[] = [],
+): PlannedOp[] {
+  const taskInstance = envelopeInstance(aggregateId, p.requestId);
+  return [
+    set(taskInstance, "status", "completed"),
+    set(taskInstance, "resultRef", p.resultRef),
+    set(taskInstance, "completedAt", p.completedAt),
+    // The FRAMEWORK Order↔Receipt CLOSURE link — this Receipt closes the Order whose
+    // id == requestId (the task instance the reactor mutates). Indexed by the read
+    // projection for the O(1) closure read. Wire-identical to the Rust reactor's op.
+    set(taskInstance, "closesOrder", impureCapabilityInstanceId(p.requestId)),
+    // The TENANT RESULT FIELDS the Receipt writes into the task aggregate (e.g.
+    // `transcription = <text>`). The envelope is auto; these are the tenant's own
+    // structured result. Framework writes them verbatim; the tenant owns their meaning.
+    ...resultOps,
+  ];
+}
+
+/**
+ * failOps — the RECEIPT (failure) half: flip `status:'failed'`, record the
+ * `failureReason`, stamp `completedAt` (the terminal time, success or failure). The
+ * reactor's write when the side-effect throws — recorded, never a retry storm
+ * (conformance X1's "declined is recorded" discipline at the task scale).
+ */
+export function failOps(
+  aggregateId: string,
+  p: z.infer<typeof failSchema>,
+): PlannedOp[] {
+  const taskInstance = envelopeInstance(aggregateId, p.requestId);
+  return [
+    set(taskInstance, "status", "failed"),
+    set(taskInstance, "failureReason", p.failureReason),
+    set(taskInstance, "completedAt", p.failedAt),
+    // CLOSURE link — a FAILED task is still CLOSED by its receipt (the closure read
+    // reports it CLOSED with no result). Same `closesOrder == requestId` as `completeOps`.
+    set(taskInstance, "closesOrder", impureCapabilityInstanceId(p.requestId)),
+  ];
+}
+
+/** blockOps — terminal park with an explicit next action, not a hidden retry loop. */
+export function blockOps(
+  aggregateId: string,
+  p: z.infer<typeof blockSchema>,
+): PlannedOp[] {
+  const taskInstance = envelopeInstance(aggregateId, p.requestId);
+  return [
+    set(taskInstance, "status", "blocked"),
+    set(taskInstance, "blockedReason", p.blockedReason),
+    set(taskInstance, "blockedAt", p.blockedAt),
+    set(taskInstance, "nextAction", p.nextAction),
+    set(taskInstance, "closesOrder", impureCapabilityInstanceId(p.requestId)),
+  ];
+}
+
+/** deadLetterOps — terminal DLQ receipt. Recovery is a fresh explicit Order. */
+export function deadLetterOps(
+  aggregateId: string,
+  p: z.infer<typeof deadLetterSchema>,
+): PlannedOp[] {
+  const taskInstance = envelopeInstance(aggregateId, p.requestId);
+  return [
+    set(taskInstance, "status", "deadLettered"),
+    set(taskInstance, "deadLetterReason", p.deadLetterReason),
+    set(taskInstance, "deadLetteredAt", p.deadLetteredAt),
+    set(taskInstance, "closesOrder", impureCapabilityInstanceId(p.requestId)),
+  ];
+}
+
+/**
+ * The generated directive QUARTET for a impure capability. A domain dev calls
+ * {@link impureCapability} ONCE and gets:
+ *   • `aggregate`  — the task aggregate handle (envelope ⊕ params),
+ *   • `order`      — `.creates` directive (the authored Order),
+ *   • `complete`   — `.mutates` directive (the reactor's success Receipt),
+ *   • `fail`       — `.mutates` directive (the reactor's failure Receipt),
+ * plus the deterministic `instanceId` rule. The `order` payload is the framework
+ * order-envelope MERGED with the tenant's `paramsSchema`; `complete`/`fail` are fixed.
+ */
+export interface ImpureCapability<
+  Id extends string,
+  ParamsShape extends z.ZodRawShape,
+  F extends Record<string, Field>,
+> {
+  readonly aggregate: AggregateHandle<Id, typeof IMPURE_CAPABILITY_ENVELOPE & F>;
+  readonly order: RequirableDirective<OrderPayload<ParamsShape>>;
+  readonly complete: RequirableDirective<z.infer<typeof completeSchema>>;
+  readonly fail: RequirableDirective<z.infer<typeof failSchema>>;
+  readonly block: RequirableDirective<z.infer<typeof blockSchema>>;
+  readonly deadLetter: RequirableDirective<z.infer<typeof deadLetterSchema>>;
+  readonly instanceId: (requestId: string) => string;
+}
+
+/**
+ * The inferred ORDER payload type = the framework envelope schema EXTENDED with the
+ * tenant's param shape — the EXACT inference `orderEnvelopeSchema.extend(paramsSchema)`
+ * produces (so the declared `ImpureCapability.order` directive type and the value the factory
+ * builds are the same type, with no brittle hand-written intersection).
+ */
+export type OrderPayload<ParamsShape extends z.ZodRawShape> = z.infer<
+  ReturnType<typeof orderEnvelopeSchema.extend<ParamsShape>>
+>;
+
+/**
+ * impureCapability — the framework FACTORY. Declares an Order→Receipt task in ONE call:
+ *
+ * ```ts
+ * // Build the aggregate handle FIRST so `writeParams` references it without a
+ * // self-cycle (a `const` can't reference itself in its own initializer).
+ * const exportParams = { targetKey: t.string().merge(Lww), format: t.enum(EXPORT_FORMATS).merge(Lww) };
+ * const exportTaskAgg = impureCapabilityAggregate("ExportJobAggregate", exportParams);
+ *
+ * export const exportJob = impureCapability({
+ *   aggregateId: "ExportJobAggregate",
+ *   orderDirectiveId: "createExportJob",
+ *   completeDirectiveId: "completeExportJob",
+ *   failDirectiveId: "failExportJob",
+ *   blockDirectiveId: "blockExportJob",
+ *   deadLetterDirectiveId: "deadLetterExportJob",
+ *   params: exportParams,
+ *   paramsSchema: { targetKey: z.string(), format: z.enum(EXPORT_FORMATS) },
+ *   writeParams: (taskInstanceId, p) => [
+ *     set(instance(exportTaskAgg, taskInstanceId), "targetKey", p.targetKey),
+ *     set(instance(exportTaskAgg, taskInstanceId), "format", p.format),
+ *   ],
+ * });
+ * ```
+ *
+ * The tenant declares the wire ids (so they're stable, minify-safe DATA — the same
+ * declared-once rule as `aggregate()`/`directive()`), the param FIELDS (for the
+ * aggregate shape + codegen) and the param SCHEMA (for the order payload + the
+ * `writeParams` plan fragment). The framework wires the lifecycle: status defaulting,
+ * the requestId keying, and the complete/fail receipt directives.
+ *
+ * `writeParams(taskInstanceId, params)` returns the `PlannedOp[]` for the tenant's OWN
+ * fields (the framework already writes the envelope) — the param half of the order
+ * plan, kept type-checked against the tenant's param fields via the `set()` helper.
+ */
+export function impureCapability<
+  const Id extends string,
+  const OrderId extends string,
+  const CompleteId extends string,
+  const FailId extends string,
+  ParamsShape extends z.ZodRawShape,
+  F extends Record<string, Field>,
+>(spec: {
+  aggregateId: Id;
+  orderDirectiveId: OrderId;
+  completeDirectiveId: CompleteId;
+  failDirectiveId: FailId;
+  blockDirectiveId: string;
+  deadLetterDirectiveId: string;
+  /** The task's request-param FIELDS (merged onto the envelope for the aggregate shape). */
+  params: F;
+  /** The task's request-param Zod SHAPE (merged onto the order envelope schema). */
+  paramsSchema: ParamsShape;
+  /** Plan fragment writing the tenant's param fields for the order (envelope is auto). */
+  writeParams: (
+    taskInstanceId: string,
+    params: z.infer<z.ZodObject<ParamsShape>>,
+  ) => PlannedOp[];
+  /**
+   * OPTIONAL plan fragment writing the tenant's STRUCTURED RESULT fields onto the task
+   * aggregate when the `complete` Receipt is authored (the lifecycle envelope + the
+   * `closesOrder` link are auto). The receipt's `resultRef` carries the content-addressed
+   * Evidence ref (the authoritative artifact); a tenant that ALSO wants the result in a
+   * typed, queryable field (e.g. a voice-note's `transcription`) supplies it here. The
+   * `resultRef` string is passed through so the tenant can derive the field value from the
+   * result when it is the same data (e.g. `transcription = resultRef`). Wire-identical to
+   * the Rust reactor's `result_fields` (`HandlerSuccess::with_result_field`).
+   */
+  completeResult?: (taskInstanceId: string, resultRef: string) => PlannedOp[];
+}): ImpureCapability<Id, ParamsShape, F> {
+  const taskAggregate = impureCapabilityAggregate(spec.aggregateId, spec.params);
+
+  // The order payload = the framework provenance envelope ⊕ the tenant's params.
+  const orderPayload = orderEnvelopeSchema.extend(spec.paramsSchema);
+
+  const order: RequirableDirective<OrderPayload<ParamsShape>> = directive(
+    spec.orderDirectiveId,
+  )
+    .creates(taskAggregate)
+    .payload(orderPayload)
+    .plan((p) => {
+      // The validated payload carries BOTH the envelope (required string/int) and the
+      // tenant params. `orderOps` writes the envelope; the tenant's `writeParams`
+      // writes its own fields. Extract the envelope explicitly (it is required on the
+      // schema, so these are present non-undefined values).
+      const envelope = orderEnvelopeSchema.parse(p);
+      const params = p as z.infer<z.ZodObject<ParamsShape>>;
+      return orderOps(
+        spec.aggregateId,
+        envelope,
+        spec.writeParams(impureCapabilityInstanceId(envelope.requestId), params),
+      );
+    });
+
+  const complete = directive(spec.completeDirectiveId)
+    .mutates(taskAggregate)
+    .payload(completeSchema)
+    .plan((p) =>
+      completeOps(
+        spec.aggregateId,
+        p,
+        // Tenant structured-result ops (e.g. `transcription`) if the task declares them.
+        spec.completeResult?.(impureCapabilityInstanceId(p.requestId), p.resultRef) ?? [],
+      ),
+    );
+
+  const fail = directive(spec.failDirectiveId)
+    .mutates(taskAggregate)
+    .payload(failSchema)
+    .plan((p) => failOps(spec.aggregateId, p));
+
+  const block = directive(spec.blockDirectiveId)
+    .mutates(taskAggregate)
+    .payload(blockSchema)
+    .plan((p) => blockOps(spec.aggregateId, p));
+
+  const deadLetter = directive(spec.deadLetterDirectiveId)
+    .mutates(taskAggregate)
+    .payload(deadLetterSchema)
+    .plan((p) => deadLetterOps(spec.aggregateId, p));
+
+  return {
+    aggregate: taskAggregate,
+    order,
+    complete,
+    fail,
+    block,
+    deadLetter,
+    instanceId: impureCapabilityInstanceId,
+  };
+}
+
+// ─────────────────────────── THE CAPABILITY PROVIDER ─────────────────────────
+//
+// The Order half (`order`) is an ordinary Intent authored by the peer through the one write
+// path. The Receipt half (`complete`/`fail`) is an ordinary Intent authored by a capability
+// PROVIDER — itself a Nomos author (`admission-hosting.md`: hosted/provider-originated
+// intents author *through* a policy unit too"). The provider is the runtime ROLE; this
+// section is its host-agnostic, PURE contract (the impure parts — watching + the side-effect —
+// are the host's, and deliberately are NOT in the fold).
+//
+// THE LOOP (host pseudo-code; the host is the Rust git-holon or a Dart provider peer):
+//
+//   for await (const task of watchRequestedTasks(taskAggregate)) {   // impure: read
+//     let outcome: TaskOutcome;
+//     try {
+//       const resultRef = await runSideEffect(task);  // impure: render/upload/provider work
+//       outcome = { kind: "completed", resultRef };
+//     } catch (e) {
+//       outcome = { kind: "failed", failureReason: String(e) };      // recorded, NOT retried
+//     }
+//     const receipt = impureCapabilityReceipt(impureCapability, task.requestId, outcome, hostClock());
+//     await dispatchTyped(receipt.directive, receipt.payload);        // ordinary Intent, one gate
+//   }
+//
+// The reactor MUST be idempotent on a re-run of the SAME requested task: it should act
+// only while `status === 'requested'` (a task already `completed`/`failed` is skipped),
+// so a redelivered watch event or a replayed log produces no duplicate side-effect — the
+// terminal-once gate/envelope law prevents a second terminal fact.
+
+/** The result of running a impure capability's side-effect — the input to {@link impureCapabilityReceipt}. */
+export type TaskOutcome =
+  | {
+      readonly kind: "completed";
+      /** The content-addressed result (a blob ref / download url) as a JSON string. */
+      readonly resultRef: string;
+    }
+  | {
+      readonly kind: "failed";
+      readonly failureReason: string;
+    }
+  | {
+      readonly kind: "blocked";
+      readonly blockedReason: string;
+      readonly nextAction: string;
+    }
+  | {
+      readonly kind: "deadLettered";
+      readonly deadLetterReason: string;
+    };
+
+/**
+ * A Receipt intent the reactor should author: the `complete`/`fail` directive to dispatch +
+ * its typed payload. The directive and payload are INTERNALLY CORRELATED (built
+ * together), so the host dispatches them as a pair — `run(agg, ports)` lowers them
+ * through their own directive (keeping the directive↔payload pairing sound; a consumer
+ * never re-pairs a union-typed directive with a union-typed payload). `kind` is the
+ * discriminant a host can switch on without inspecting the directive.
+ */
+export interface TaskReceipt<P> {
+  /** Which receipt this is — success, failure, blocked, or DLQ. */
+  readonly kind: "complete" | "fail" | "block" | "deadLetter";
+  readonly directive: RequirableDirective<P>;
+  readonly payload: P;
+  /** Lower this receipt through its own directive (the correlated, sound pairing). */
+  readonly run: (agg: AggregateHandle, ports: Ports) => WireIntent;
+}
+
+/**
+ * impureCapabilityReceipt — the PURE map from a side-effect {@link TaskOutcome} to the
+ * ordinary Receipt intent the reactor authors. Picks `complete` (with `resultRef` +
+ * `completedAt`) for a success and `fail` (with `failureReason` + `failedAt`) for a failure,
+ * stamping the
+ * host-supplied terminal time `now` (epoch-ms). Returning the {@link TaskReceipt}
+ * keeps the reactor's DECISION pure + unit-testable; the host does the impure
+ * `dispatchTyped(receipt.directive, receipt.payload)` (or `receipt.run(...)` in a
+ * typed harness).
+ *
+ * `now` is the host's clock reading (the reactor is an authoring peer; its authoring HLC comes
+ * from the host port like any author) — passed in so this function stays pure.
+ */
+export function impureCapabilityReceipt<
+  Id extends string,
+  ParamsShape extends z.ZodRawShape,
+  F extends Record<string, Field>,
+>(
+  task: ImpureCapability<Id, ParamsShape, F>,
+  requestId: string,
+  outcome: TaskOutcome,
+  now: number,
+):
+  | TaskReceipt<z.infer<typeof completeSchema>>
+  | TaskReceipt<z.infer<typeof failSchema>>
+  | TaskReceipt<z.infer<typeof blockSchema>>
+  | TaskReceipt<z.infer<typeof deadLetterSchema>> {
+  if (outcome.kind === "completed") {
+    const directive = task.complete;
+    const payload: z.infer<typeof completeSchema> = {
+      requestId,
+      resultRef: outcome.resultRef,
+      completedAt: now,
+    };
+    return {
+      kind: "complete",
+      directive,
+      payload,
+      run: (agg, ports) => executeDirectiveToIntent(directive, agg, payload, ports),
+    };
+  }
+  if (outcome.kind === "failed") {
+    const directive = task.fail;
+    const payload: z.infer<typeof failSchema> = {
+      requestId,
+      failureReason: outcome.failureReason,
+      failedAt: now,
+    };
+    return {
+      kind: "fail",
+      directive,
+      payload,
+      run: (agg, ports) => executeDirectiveToIntent(directive, agg, payload, ports),
+    };
+  }
+  if (outcome.kind === "blocked") {
+    const directive = task.block;
+    const payload: z.infer<typeof blockSchema> = {
+      requestId,
+      blockedReason: outcome.blockedReason,
+      blockedAt: now,
+      nextAction: outcome.nextAction,
+    };
+    return {
+      kind: "block",
+      directive,
+      payload,
+      run: (agg, ports) => executeDirectiveToIntent(directive, agg, payload, ports),
+    };
+  }
+  const directive = task.deadLetter;
+  const payload: z.infer<typeof deadLetterSchema> = {
+    requestId,
+    deadLetterReason: outcome.deadLetterReason,
+    deadLetteredAt: now,
+  };
+  return {
+    kind: "deadLetter",
+    directive,
+    payload,
+    run: (agg, ports) => executeDirectiveToIntent(directive, agg, payload, ports),
+  };
+}