@githolon/dsl 0.103.18 → 0.104.0

package/src/framework/capability.ts

@@ -27,15 +27,24 @@
  * //   capability "llm.complete"         (the CapabilityBinding the executor must hold)
  * ```
  *
- * THE RECEIPT-FIELD MECHANISM (stated honestly — the sheet's §4 comment): the
- * complete Receipt's payload is the framework-FIXED `{requestId, resultRef,
- * completedAt}`; typed receipt VALUES ride INSIDE `resultRef` as a JSON object,
- * and the generated `completeResult` ops decode them into the declared typed
- * fields (per-field zod-validated IN the plan — a malformed executor result is a
- * typed plan-halt refusal, never a silent partial fold). Receipt fields are
- * auto-`.optional()` on the aggregate (absent while `requested` — the
- * read-decode discipline). Large bodies belong in content-addressed
- * `resultRef`/`resultEvidence` refs, not inline values.
+ * THE RECEIPT IS TYPED LAW. The complete Receipt's payload is the envelope
+ * `{requestId, completedAt}` MERGED with the declared receipt fields — typed USDA
+ * values, exactly as the obligation merges its request params. Each declared field
+ * becomes a first-class contract field in the emitted law (its own stable id and
+ * `nomos:type`), so the kernel can read it, the evolve gate governs it, and a
+ * wrong-typed or missing value is refused at the payload boundary.
+ *
+ * It previously travelled as a JSON object stringified into `resultRef` and re-parsed
+ * in the plan. That made the receipt half the one place a declared, typed shape
+ * degraded to an opaque string: invisible to the law, unindexable, and silently
+ * partial when a provider misspelled a key. `resultRef` now means only what its name
+ * says — the address of a produced ARTIFACT — and is required solely for a capability
+ * that declares no receipt fields, so a Receipt can never report nothing.
+ *
+ * Receipt fields are auto-`.optional()` on the AGGREGATE (absent while `requested` —
+ * the read-decode discipline) but required on the PAYLOAD unless the author declares
+ * them optional: a partial result is something you declare, not something you assume.
+ * Large bodies still belong in content-addressed `resultRef`/`resultEvidence` refs.
  *
  * Naming: the capability name uses the shipped binding grammar
  * (`^[a-z0-9][a-z0-9._-]{0,63}$` — dots legal; marketplace interfaces are
@@ -55,10 +64,41 @@ import {
   impureCapabilityInstanceId,
   type ImpureCapability,
 } from "./impure_capability.js";
+import { key, relationRef, relationType, self, user } from "../relation_schema.js";
+import { directive } from "../directive.js";
+import { RelationTuple, removeTuple, writeTuple } from "./relations.js";
 
 /** The shipped CapabilityBinding name grammar (worker + governance law agree). */
 export const CAPABILITY_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
 
+/**
+ * THE RECEIPT FENCE — who may close an obligation.
+ *
+ * A Receipt (`complete`/`fail`/`block`/`deadLetter`) is the moment an OUTSIDE effect becomes
+ * chain fact, so it is the one write that must prove it came from the provider the work was
+ * offered to. The proof is asymmetric and re-derived on every lane: the provider SIGNS its
+ * receipt with its DEVICE KEY, the kernel verifies that signature and resolves the author as
+ * `key:<hash>`, and this relation says whether that key may close obligations for THIS
+ * capability. No bearer token, nothing host-held, nothing that lands in committed state.
+ *
+ * The object is per-capability (`nomosCapability:<name>`), so a transcription provider cannot
+ * close a payments obligation. `user()` is allowed alongside `key()` for an operator closing a
+ * receipt by hand under an authenticated identity.
+ */
+export const CAPABILITY_PROVIDER_RELATION = relationRef("nomosCapabilityProvider");
+
+/** The relation SCHEMA for the fence. Shipped automatically with every `capability()` (via the
+ *  bundle's `relations` piece) because `.requires(...)` is INERT — it fails OPEN — in a law that
+ *  carries no relation schema. A fence that silently enforces nothing is worse than none. */
+export const capabilityProviderRelations = relationType("nomosCapability")
+  .asGlobal()
+  .relation(CAPABILITY_PROVIDER_RELATION, { rewrite: self(), allow: [user(), key()] });
+
+/** The per-capability authz object a provider grant is written against. */
+export function capabilityProviderObject(name: string): string {
+  return `nomosCapability:${name}`;
+}
+
 /** "llm.complete" → "LlmComplete" — the deterministic id stem. */
 export function capabilityPascal(name: string): string {
   return name
@@ -81,7 +121,12 @@ type RequestShape<Req extends Record<string, Field>> = { [K in keyof Req]: Req[K
 export interface CapabilityDecl<
   Req extends Record<string, Field>,
   Rec extends Record<string, Field>,
-> extends ImpureCapability<string, RequestShape<Req>, Req & Rec> {
+> extends ImpureCapability<
+    string,
+    RequestShape<Req>,
+    Req & Rec,
+    { [K in keyof Rec]: Rec[K]["zod"] }
+  > {
   /** The capability name — the `CapabilityBinding` slot the executor must hold. */
   readonly name: string;
   /**
@@ -111,8 +156,14 @@ export interface CapabilityDecl<
   readonly tasks: QueryDecl;
   /** The receipt fields' zod object — `{}` when the capability declares none. */
   readonly receiptSchema: z.ZodObject<{ [K in keyof Rec]: Rec[K]["zod"] }>;
-  /** Build the `resultRef` JSON for a complete Receipt from typed receipt values. */
-  readonly encodeResult: (values: { [K in keyof Rec]: z.infer<Rec[K]["zod"]> }) => string;
+  /**
+   * Validate typed receipt values against the declared receipt shape. A provider spreads the
+   * result into the `complete<Pascal>` payload alongside `{requestId, completedAt}`; there is
+   * no encode step, because receipt values travel as typed USDA exactly like request params.
+   */
+  readonly parseResult: (values: { [K in keyof Rec]: z.infer<Rec[K]["zod"]> }) => {
+    [K in keyof Rec]: z.infer<Rec[K]["zod"]>;
+  };
 }
 
 /**
@@ -128,7 +179,22 @@ export function capability<
   const Name extends string,
   Req extends Record<string, Field>,
   Rec extends Record<string, Field> = Record<never, Field>,
->(name: Name, spec: { request: Req; receipt?: Rec; endpoint?: string; declassify?: string }): CapabilityDecl<Req, Rec> {
+>(name: Name, spec: {
+  request: Req;
+  receipt?: Rec;
+  endpoint?: string;
+  declassify?: string;
+  /**
+   * THE ACKNOWLEDGED WAIVER — open this capability's Receipts to any authorised author.
+   *
+   * Receipts are fenced by default (see {@link CAPABILITY_PROVIDER_RELATION}): closing an
+   * obligation is how an outside effect becomes chain fact, so by default it takes a
+   * device-key-signed author holding provider authority for this capability. A genuinely
+   * public capability may waive that, but it says WHY in the law — the same shape as
+   * `declassify`, replayable and auditable, never a silent default.
+   */
+  openReceipts?: string;
+}): CapabilityDecl<Req, Rec> {
   if (!CAPABILITY_NAME_RE.test(name)) {
     throw new Error(
       `capability('${name}'): the name must match ${CAPABILITY_NAME_RE} (lowercase, dot-namespaced — e.g. 'llm.complete'); it doubles as the CapabilityBinding slot the executor must hold`,
@@ -175,17 +241,6 @@ export function capability<
     Object.entries(receipt).map(([k, f]) => [k, f.zod]),
   ) as { [K in keyof Rec]: Rec[K]["zod"] };
   const receiptEntries = Object.entries(receipt) as [string, Field][];
-  const decodeReceipt = (resultRef: string): Record<string, unknown> => {
-    const decoded = JSON.parse(resultRef) as unknown;
-    if (decoded === null || typeof decoded !== "object" || Array.isArray(decoded)) {
-      throw new Error("a typed capability receipt must encode a JSON object");
-    }
-    const values = decoded as Record<string, unknown>;
-    for (const [k, f] of receiptEntries) {
-      if (values[k] !== undefined) f.zod.parse(values[k]);
-    }
-    return values;
-  };
 
   const quartet = impureCapability({
     aggregateId,
@@ -202,25 +257,17 @@ export function capability<
       Object.keys(spec.request).map((k) =>
         set(instance(taskAggregate, taskId), k as never, (p as Record<string, unknown>)[k] as never),
       ),
-    // The receipt-field mechanism: typed values ride INSIDE resultRef as JSON;
-    // decode + per-field zod-validate IN the plan (pure function of payload —
-    // deterministic; a malformed executor result is a typed plan-halt refusal).
-    // Absent keys are skipped (partial results are legal — read-decode
-    // discipline), present keys must validate.
+    // The receipt half, symmetrical with the request half above: declared fields are merged
+    // onto the complete envelope as TYPED values and written straight through. The payload
+    // boundary has already validated them against the same zod the author declared, so the
+    // plan has nothing to decode. Absent keys are skipped — partial results stay legal.
     ...(receiptEntries.length > 0
       ? {
-          completeResultSchema: z.string().refine((value) => {
-            try { decodeReceipt(value); return true; } catch { return false; }
-          }, "must encode a valid typed capability receipt JSON object"),
-          completeResult: (taskId: string, resultRef: string): PlannedOp[] => {
-            const decoded = decodeReceipt(resultRef);
-            const ops: PlannedOp[] = [];
-            for (const [k, f] of receiptEntries) {
-              if (decoded[k] === undefined) continue;
-              ops.push(set(instance(taskAggregate, taskId), k as never, f.zod.parse(decoded[k]) as never));
-            }
-            return ops;
-          },
+          receiptSchema: receiptShape,
+          writeReceipt: (taskId: string, r: Record<string, unknown>): PlannedOp[] =>
+            receiptEntries
+              .filter(([k]) => r[k] !== undefined)
+              .map(([k]) => set(instance(taskAggregate, taskId), k as never, r[k] as never)),
         }
       : {}),
     capability: name,
@@ -229,8 +276,70 @@ export function capability<
   const camel = pascal[0]!.toLowerCase() + pascal.slice(1);
   const tasks = query(`${camel}TasksByStatus`).key("status").returns(taskAggregate);
 
+  // THE GATED GRANT — never the raw tuple writer.
+  //
+  // `relateSubject`/`unrelateSubject` are UNGATED framework primitives; governance learned this
+  // the hard way (re-exporting them registered an ungated `workspace:self#admin@…` writer — a
+  // self-grant-admin hole). A law that exported them alongside this fence would let anyone
+  // self-grant provider authority and close their own obligations. So provider authority is
+  // seated ONLY through these admin-gated wrappers, scoped to THIS capability's object.
+  const grantPayload = z.object({
+    subject: z.string().min(1),
+    grantedBy: z.string().min(1),
+    grantedAt: z.string().min(1),
+  });
+  const grantProvider = directive(`grant${pascal}Provider`)
+    .ensures(RelationTuple)
+    .payload(grantPayload)
+    .plan((p) =>
+      writeTuple({
+        object: capabilityProviderObject(name),
+        relation: CAPABILITY_PROVIDER_RELATION,
+        subject: p.subject,
+        grantedBy: p.grantedBy,
+        grantedAt: p.grantedAt,
+      }),
+    )
+    .requires("admin");
+  const revokeProvider = directive(`revoke${pascal}Provider`)
+    .ensures(RelationTuple)
+    .payload(grantPayload.extend({ revokedBy: z.string().min(1), revokedAt: z.string().min(1) }))
+    .plan((p) =>
+      removeTuple({
+        object: capabilityProviderObject(name),
+        relation: CAPABILITY_PROVIDER_RELATION,
+        subject: p.subject,
+        grantedBy: p.grantedBy,
+        grantedAt: p.grantedAt,
+        revokedBy: p.revokedBy,
+        revokedAt: p.revokedAt,
+      }),
+    )
+    .requires("admin");
+
+  // THE FENCE, APPLIED. Every Receipt verb is gated on provider authority for THIS capability
+  // unless the law carries an explicit `openReceipts` waiver. The gate is the shipped native
+  // relation gate, so it is re-derived on author, edge admission AND verify_chain — a receipt
+  // forged on the open session lane never folds anywhere.
+  const fenced = <D extends { requires: (rel: string, opts?: { object?: string }) => unknown }>(d: D): D =>
+    spec.openReceipts !== undefined
+      ? d
+      : (d.requires(CAPABILITY_PROVIDER_RELATION, {
+          object: capabilityProviderObject(name),
+        }) as D);
+
   return {
     ...quartet,
+    complete: fenced(quartet.complete),
+    fail: fenced(quartet.fail),
+    block: fenced(quartet.block),
+    deadLetter: fenced(quartet.deadLetter),
+    // The relation SCHEMA rides with the bundle so the gate can never be inert (a law without
+    // a relation schema does not enforce `.requires` at all).
+    relations: capabilityProviderRelations,
+    grantProvider,
+    revokeProvider,
+    ...(spec.openReceipts !== undefined ? { openReceipts: spec.openReceipts } : {}),
     aggregate: taskAggregate,
     instanceId: impureCapabilityInstanceId,
     name,
@@ -238,7 +347,7 @@ export function capability<
     ...(spec.declassify !== undefined ? { declassify: spec.declassify } : {}),
     requestSchema: z.object(requestShape),
     receiptSchema: z.object(receiptShape),
-    encodeResult: (values) => JSON.stringify(z.object(receiptShape).parse(values)),
+    parseResult: (values) => z.object(receiptShape).parse(values),
     tasks,
     // The one-export expansion tag (capability_exports.ts): every exports walk
     // discovers this bundle's aggregate + quartet + scan query without re-exports.

package/src/framework/impure_capability.ts

@@ -102,12 +102,14 @@ export type ImpureCapabilityStatus = (typeof IMPURE_CAPABILITY_STATUSES)[number]
  *  - requestedBy    Lww — who obligated the task (provenance). Immutable-after-create.
  *  - requestedAt    Int — epoch-ms the obligation was authored. Immutable-after-create.
  *  - status         Lww enum — `requested` → the reactor flips to a terminal status.
- *  - resultRef      Lww string (OPTIONAL) — the content-addressed RESULT the reactor
- *                   records on completion: a blob ref / download url. The receipt-field
- *                   mechanism (capability.ts) TRANSPORTS typed values through this string
- *                   (JSON.stringify → JSON.parse into separate typed fields), so the ref
- *                   itself is honestly a STRING — NOT a `t.json()` leaf (which is now the
- *                   first-class `Value::Json`, reserved for genuinely-structured fields).
+ *  - resultRef      Lww string (OPTIONAL) — the content-addressed ARTIFACT the provider
+ *                   records on completion: a blob ref / download url, and nothing else. It
+ *                   is honestly a STRING because an artifact address IS a string. A
+ *                   capability with something structured to report DECLARES receipt fields;
+ *                   those travel as typed USDA values merged onto the complete payload
+ *                   (symmetrically with request params) and fold into their own typed
+ *                   fields. `resultRef` is required only for a capability that declares no
+ *                   receipt fields, so a Receipt can never report nothing.
  *                   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
@@ -193,14 +195,28 @@ const obligationEnvelopeSchema = z.object({
   deadlineAt: z.number().int(),
 });
 
-/** The receipt-COMPLETE payload: the request id + the content-addressed result + when. */
-const completeSchema = z.object({
+/** The receipt-COMPLETE envelope every capability carries, whatever its result shape. */
+const completeEnvelopeSchema = 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-COMPLETE payload for a capability declaring NO typed receipt fields: the
+ * envelope plus a required content-addressed ref to the produced ARTIFACT (blob ref / url).
+ * It is an artifact address, never an envelope for typed values — a capability that has
+ * something to say declares receipt fields and says it in typed USDA.
+ */
+const completeSchema = completeEnvelopeSchema.extend({
+  resultRef: z.string(),
+});
+
+/** The complete envelope for a capability whose result rides in DECLARED receipt fields:
+ *  the artifact address becomes optional, because the typed fields carry the outcome. */
+const completeArtifactOptionalSchema = completeEnvelopeSchema.extend({
+  resultRef: z.string().optional(),
+});
+
 /** The receipt-FAIL payload: the request id + the failure reason + when. */
 const failSchema = z.object({
   requestId: z.string(),
@@ -272,13 +288,15 @@ export function obligationOps(
  */
 export function completeOps(
   aggregateId: string,
-  p: z.infer<typeof completeSchema>,
+  p: z.infer<typeof completeEnvelopeSchema> & { resultRef?: string },
   resultOps: PlannedOp[] = [],
 ): PlannedOp[] {
   const taskInstance = envelopeInstance(aggregateId, p.requestId);
   return [
     set(taskInstance, "status", "completed"),
-    set(taskInstance, "resultRef", p.resultRef),
+    // Present iff this capability produced an ARTIFACT. A typed-receipt capability carries
+    // its result in its declared fields instead, so it writes no artifact address at all.
+    ...(p.resultRef !== undefined ? [set(taskInstance, "resultRef", p.resultRef)] : []),
     set(taskInstance, "completedAt", p.completedAt),
     // The FRAMEWORK Obligation↔Receipt CLOSURE link — this Receipt closes the Obligation whose
     // id == requestId (the task instance the reactor mutates). Indexed by the read
@@ -349,16 +367,32 @@ export function deadLetterOps(
  *   • `complete`   — `.mutates` directive (the reactor's success Receipt),
  *   • `fail`       — `.mutates` directive (the reactor's failure Receipt),
  * plus the deterministic `instanceId` rule. The `obligation` payload is the framework
- * obligation-envelope MERGED with the tenant's `paramsSchema`; `complete`/`fail` are fixed.
+ * obligation-envelope MERGED with the tenant's `paramsSchema`; the `complete` payload is
+ * SYMMETRICALLY the complete-envelope merged with the tenant's `receiptSchema` (typed USDA
+ * values, never an encoded blob); `fail`/`block`/`deadLetter` are fixed.
  */
+// Infer from the EXTENDED schema, exactly as ObligationPayload does — a conditional or an
+// intersection around this turns a `.optional()` receipt field into a REQUIRED key of type
+// `T | undefined` under exactOptionalPropertyTypes, so a genuinely optional receipt field
+// could not be omitted. The receipt-free case is then the same shape with no extra keys,
+// where `resultRef` is separately required (see `completeSchema`).
+export type CompletePayload<ReceiptShape extends z.ZodRawShape> = z.infer<
+  ReturnType<typeof completeArtifactOptionalSchema.extend<ReceiptShape>>
+> &
+  // A capability declaring NO receipt fields must still report SOMETHING, so its artifact
+  // address stays required. Intersected only in that branch — where there are no receipt
+  // fields whose optionality it could flatten.
+  (keyof ReceiptShape extends never ? { resultRef: string } : unknown);
+
 export interface ImpureCapability<
   Id extends string,
   ParamsShape extends z.ZodRawShape,
   F extends Record<string, Field>,
+  ReceiptShape extends z.ZodRawShape = Record<never, never>,
 > {
   readonly aggregate: AggregateHandle<Id, typeof IMPURE_CAPABILITY_ENVELOPE & F>;
   readonly obligation: RequirableDirective<ObligationPayload<ParamsShape>>;
-  readonly complete: RequirableDirective<z.infer<typeof completeSchema>>;
+  readonly complete: RequirableDirective<CompletePayload<ReceiptShape>>;
   readonly fail: RequirableDirective<z.infer<typeof failSchema>>;
   readonly block: RequirableDirective<z.infer<typeof blockSchema>>;
   readonly deadLetter: RequirableDirective<z.infer<typeof deadLetterSchema>>;
@@ -429,6 +463,7 @@ export function impureCapability<
   const FailId extends string,
   ParamsShape extends z.ZodRawShape,
   F extends Record<string, Field>,
+  ReceiptShape extends z.ZodRawShape = Record<never, never>,
 >(spec: {
   aggregateId: Id;
   obligationDirectiveId: ObligationId;
@@ -446,29 +481,33 @@ export function impureCapability<
     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
-   * `closesObligation` link is 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`).
+   * The task's RECEIPT Zod SHAPE — merged onto the complete envelope schema exactly as
+   * `paramsSchema` is merged onto the obligation envelope. A declared receipt travels as
+   * TYPED USDA VALUES on the wire, symmetrically with the request half.
+   *
+   * It previously rode as a JSON object stringified into `resultRef` and re-parsed in the
+   * plan. That made the receipt half of a capability the one place in the framework where a
+   * declared, typed shape degraded to an opaque string — unqueryable until decoded, invisible
+   * to the value algebra, and (in the kernel's owner-recovery lane) silently empty on a
+   * malformed parse. Receipts are law, so they are typed like law.
    */
-  completeResult?: (taskInstanceId: string, resultRef: string) => PlannedOp[];
+  receiptSchema?: ReceiptShape;
   /**
-   * OPTIONAL validation for the result reference before the plan runs. Typed capabilities use this
-   * to make malformed encoded receipts impossible to admit at the payload boundary; receipt-free
-   * capabilities retain the ordinary opaque-string result reference.
+   * Plan fragment writing the tenant's RECEIPT fields onto the task aggregate when the
+   * `complete` Receipt is authored (the lifecycle envelope + the `closesObligation` link is
+   * auto). The mirror of {@link writeParams}. Supplied iff `receiptSchema` is.
    */
-  completeResultSchema?: z.ZodString;
+  writeReceipt?: (
+    taskInstanceId: string,
+    receipt: Record<string, unknown>,
+  ) => PlannedOp[];
   /**
    * OPTIONAL: the capability-credential name the provider host must hold a
    * law-state `CapabilityBinding` for (see {@link ImpureCapability.capability}).
    * Omit-when-absent — declaring nothing changes nothing on the wire.
    */
   capability?: string;
-}): ImpureCapability<Id, ParamsShape, F> {
+}): ImpureCapability<Id, ParamsShape, F, ReceiptShape> {
   const taskAggregate = impureCapabilityAggregate(spec.aggregateId, spec.params);
   const typedRequestId = { requestId: idOf(taskAggregate) };
   const obligationPayloadBase = obligationEnvelopeSchema.extend(spec.paramsSchema);
@@ -476,9 +515,17 @@ export function impureCapability<
   // replaces; its extra aggregate identity lives in Zod metadata for lint/codegen.
   // Preserve the generic payload type while installing that richer runtime schema.
   const obligationPayload = obligationPayloadBase.extend(typedRequestId) as typeof obligationPayloadBase;
-  const typedCompleteBase = completeSchema.extend(typedRequestId);
-  const typedCompleteSchema = spec.completeResultSchema !== undefined
-    ? typedCompleteBase.extend({ resultRef: spec.completeResultSchema })
+  // THE RECEIPT IS TYPED LAW, SYMMETRICAL WITH THE REQUEST. A capability that declares
+  // receipt fields carries them as typed values merged onto the complete envelope, exactly
+  // as the obligation merges its params. `resultRef` then keeps only its honest meaning —
+  // a content-addressed ref to a produced ARTIFACT — and is required solely when there are
+  // no declared receipt fields to carry the result, so a receipt can never say nothing.
+  const typedCompleteBase = (spec.receiptSchema !== undefined
+    ? completeArtifactOptionalSchema
+    : completeSchema
+  ).extend(typedRequestId);
+  const typedCompleteSchema = spec.receiptSchema !== undefined
+    ? typedCompleteBase.extend(spec.receiptSchema)
     : typedCompleteBase;
   const typedFailSchema = failSchema.extend(typedRequestId);
   const typedBlockSchema = blockSchema.extend(typedRequestId);
@@ -503,15 +550,23 @@ export function impureCapability<
       );
     });
 
-  const complete = directive(spec.completeDirectiveId)
+  // The two branches above are distinct object schemas; the declared payload TYPE is the
+  // `CompletePayload<ReceiptShape>` conditional, so name it once here rather than leaking a
+  // union through the directive's public type.
+  const completePayload = typedCompleteSchema as unknown as z.ZodType<CompletePayload<ReceiptShape>>;
+
+  const complete: RequirableDirective<CompletePayload<ReceiptShape>> = directive(
+    spec.completeDirectiveId,
+  )
     .mutates(taskAggregate)
-    .payload(typedCompleteSchema)
+    .payload(completePayload)
     .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) ?? [],
+        p as z.infer<typeof completeEnvelopeSchema> & { resultRef?: string },
+        // The tenant's TYPED receipt fields, read straight off the validated payload —
+        // no decode step, because there is no encoding to undo.
+        spec.writeReceipt?.(impureCapabilityInstanceId((p as { requestId: string }).requestId), p as Record<string, unknown>) ?? [],
       ),
     );
 

package/src/framework/owned_custody.ts

@@ -65,8 +65,28 @@ const recoveryOrderParams = {
   deviceRequest: t.string().merge(Lww),
 };
 
+/**
+ * THE RECOVERY RECEIPT'S OWN DECLARED FIELD. The re-wrapped owned custody the recovery
+ * principal produces is the RESULT of this capability, so it is a typed receipt field.
+ *
+ * It previously rode as a JSON object stringified into `resultRef`, which the kernel dug back
+ * out with `serde_json::from_str(...).unwrap_or_default()` — so a malformed Receipt silently
+ * read as an EMPTY custody string on the accept leg rather than refusing. Custody handoff is
+ * the last thing that should degrade quietly.
+ */
+const recoveryReceipt = {
+  ownedCustody: z.string().min(1),
+};
+
+/** Order fields ⊕ the receipt field, so the aggregate can hold what the Receipt writes. */
+const recoveryOrderFields = {
+  ...recoveryOrderParams,
+  // Absent until the recovery principal's Receipt lands (the read-decode discipline).
+  ownedCustody: t.string().merge(Lww).optional(),
+};
+
 /** Private framework Order -> Receipt journal. Generated business clients never expose this aggregate. */
-export const OwnedRecoveryOrder = impureCapabilityAggregate("NomosOwnedRecoveryOrder", recoveryOrderParams);
+export const OwnedRecoveryOrder = impureCapabilityAggregate("NomosOwnedRecoveryOrder", recoveryOrderFields);
 const ownedRecoveryLifecycle = impureCapability({
   aggregateId: OwnedRecoveryOrder.id,
   obligationDirectiveId: OWNED_RECOVERY_REQUEST_DIRECTIVE,
@@ -74,7 +94,7 @@ const ownedRecoveryLifecycle = impureCapability({
   failDirectiveId: OWNED_RECOVERY_FAIL_DIRECTIVE,
   blockDirectiveId: OWNED_RECOVERY_BLOCK_DIRECTIVE,
   deadLetterDirectiveId: OWNED_RECOVERY_DEAD_LETTER_DIRECTIVE,
-  params: recoveryOrderParams,
+  params: recoveryOrderFields,
   paramsSchema: {
     ownerPrincipal: principal,
     recoveryPrincipal: principal,
@@ -85,6 +105,10 @@ const ownedRecoveryLifecycle = impureCapability({
     set(instance(OwnedRecoveryOrder, id), "recoveryPrincipal", p.recoveryPrincipal),
     set(instance(OwnedRecoveryOrder, id), "deviceRequest", p.deviceRequest),
   ],
+  receiptSchema: recoveryReceipt,
+  writeReceipt: (id, r) => [
+    set(instance(OwnedRecoveryOrder, id), "ownedCustody", r.ownedCustody as string),
+  ],
 });
 
 export const ownedRecoveryOrdersByRecoveryPrincipal = query("nomosOwnedRecoveryOrdersByRecoveryPrincipal")

package/src/framework/sync_lifecycle.ts

@@ -63,22 +63,30 @@ function optionalParamOps(
   return ops;
 }
 
-function syncResultOps(taskId: string, resultRef: string): PlannedOp[] {
+/**
+ * The sync Receipt's own declared shape. These four were previously smuggled through
+ * `resultRef` as a JSON object and recovered with `typeof`/`Number.isInteger` guards — the
+ * receipt of the framework's OWN capability was untyped, so a provider that misspelled a key
+ * or sent a string count simply had that value dropped on the floor. They are ordinary typed
+ * receipt fields now: the payload boundary validates them and a wrong shape is refused.
+ */
+const syncReceipt = {
+  resultHead: z.string().optional(),
+  resultCursor: z.string().optional(),
+  appliedIntentCount: z.number().int().optional(),
+  pushedIntentCount: z.number().int().optional(),
+};
+
+function syncResultOps(taskId: string, r: Record<string, unknown>): PlannedOp[] {
   const sync = instance(WorkspaceSyncOperation, taskId);
   const ops: PlannedOp[] = [];
-  const result = JSON.parse(resultRef) as {
-    head?: unknown;
-    cursor?: unknown;
-    appliedIntentCount?: unknown;
-    pushedIntentCount?: unknown;
-  };
-  if (typeof result.head === "string") ops.push(set(sync, "resultHead", result.head));
-  if (typeof result.cursor === "string") ops.push(set(sync, "resultCursor", result.cursor));
-  if (Number.isInteger(result.appliedIntentCount)) {
-    ops.push(set(sync, "appliedIntentCount", result.appliedIntentCount as number));
+  if (r.resultHead !== undefined) ops.push(set(sync, "resultHead", r.resultHead as string));
+  if (r.resultCursor !== undefined) ops.push(set(sync, "resultCursor", r.resultCursor as string));
+  if (r.appliedIntentCount !== undefined) {
+    ops.push(set(sync, "appliedIntentCount", r.appliedIntentCount as number));
   }
-  if (Number.isInteger(result.pushedIntentCount)) {
-    ops.push(set(sync, "pushedIntentCount", result.pushedIntentCount as number));
+  if (r.pushedIntentCount !== undefined) {
+    ops.push(set(sync, "pushedIntentCount", r.pushedIntentCount as number));
   }
   return ops;
 }
@@ -110,7 +118,8 @@ const workspaceSyncTask = impureCapability({
       ...optionalParamOps(sync, p),
     ];
   },
-  completeResult: syncResultOps,
+  receiptSchema: syncReceipt,
+  writeReceipt: syncResultOps,
 });
 
 export const requestWorkspaceSync = workspaceSyncTask.obligation.requires("requestWorkspaceSync");