@githolon/dsl 0.103.18 → 0.104.0

package/dart/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.64.16
+
+- Rebundle the runner runtime (`node-entry.mjs`, `offline-install.mjs`) generated from `@githolon/client` 0.103.19, which carries the evolve-gate fix: `promoteDomain` dispositions are read from the law that DECLARES the call, so a law upgrade with a genuine field/aggregate removal is promotable through the offer lane.
+
 ## 0.64.15
 
 - `DomainClientModelAdoptionRequired.accept` gains an optional `dispositions` parameter, threaded through to the bridge's `nomosFrameworkAdoptGeneratedModel` — a tenant can now acknowledge a genuine field/aggregate removal (`{"retired": [sid, ...]}`) from a generated client's `model.adopt()` decision instead of only via a raw adapter script.

package/dart/lib/src/provider.dart

@@ -90,15 +90,24 @@ final class TaskDeadLetter<R> extends TaskOutcome<R> {
   const TaskDeadLetter(this.deadLetterReason);
 }
 
-/// A typed RESULT a provider handler can encode into a Receipt's content-addressed
-/// `resultRef`. Every generated `…Result` class implements this: it serialises to the
-/// single JSON string the framework `complete…` Receipt records as its `resultRef` (the
-/// authoritative artifact). The framework's `resultRef` is a JSON STRING leaf
-/// (`impure_capability.ts` `completeSchema.resultRef`), so a structured result is JSON-encoded
-/// into it and decodes losslessly on the read side.
+/// A typed RESULT a provider handler returns for a Receipt.
+///
+/// A capability's DECLARED receipt fields travel as TYPED USDA values on the `complete…`
+/// payload — the mirror of the Obligation's request params — so [toReceiptFields] returns them
+/// keyed by their law field names and the dispatcher spreads them beside
+/// `{requestId, completedAt}`.
+///
+/// [toResultRef] is the address of a produced ARTIFACT (a blob ref / url) and is `null` unless
+/// the side-effect produced one. It was previously the single JSON string a structured result
+/// was encoded into; that made receipt values invisible to the law — untypeable, unindexable,
+/// and silently dropped when a key was misspelled.
 abstract interface class TaskResult {
-  /// Encode this result to the Receipt's `resultRef` JSON string.
-  String toResultRef();
+  /// The address of a produced artifact, or `null` when the result is carried by declared
+  /// receipt fields.
+  String? toResultRef();
+
+  /// The declared receipt values, keyed by their law field names.
+  Map<String, Object?> toReceiptFields();
 }
 
 /// The HOST CLOCK seam: the provider stamps the Receipt's terminal time (epoch-ms) from

package/dart/lib/src/runner/node-entry.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // <define:__NOMOS_KERNEL_RELEASE__>
-var define_NOMOS_KERNEL_RELEASE_default = { production: { hash: "8a39dd1041ce56b820ee321eab4d10cb5e53131f216a6ab8f1135799a2cc5f98", version: "kernel-8a39dd10", features: ["compoundKeys", "capturedReads", "invariantGate", "surfacedMerge", "fieldProvenance", "nullSemantics", "attestedReads", "conflictSnapshots", "ownedAudience", "temporalEnum"], protocol: 1 }, testMint: { hash: "4ec42988fffc7dd1c4f5553aec83720a7a9bc3f27eb35da211254e66eac2661c", version: "kernel-4ec42988", features: ["compoundKeys", "capturedReads", "invariantGate", "surfacedMerge", "fieldProvenance", "nullSemantics", "attestedReads", "conflictSnapshots", "ownedAudience", "temporalEnum"], protocol: 1 } };
+var define_NOMOS_KERNEL_RELEASE_default = { production: { hash: "7d3fcc3501bef23849493026e10ce75b3ef3d1400f789181d03f4a3b0b5b1fdb", version: "kernel-7d3fcc35", features: ["compoundKeys", "capturedReads", "invariantGate", "surfacedMerge", "fieldProvenance", "nullSemantics", "attestedReads", "conflictSnapshots", "ownedAudience", "temporalEnum"], protocol: 1 }, testMint: { hash: "0ae2f9ba0fa5ec2eccb798fdcb99f46a82d76c03d851a9fc62eed47ffc25c394", version: "kernel-0ae2f9ba", features: ["compoundKeys", "capturedReads", "invariantGate", "surfacedMerge", "fieldProvenance", "nullSemantics", "attestedReads", "conflictSnapshots", "ownedAudience", "temporalEnum"], protocol: 1 } };
 
 // runner/node-entry.ts
 import { createInterface } from "node:readline";
@@ -10112,7 +10112,8 @@ ${String(commit).toLowerCase()}`;
     try {
       const outcome = await offerDirective("nomos", "promoteDomain", prepared.payload, {
         actor: connectionPrincipal,
-        returnCreated: false
+        returnCreated: false,
+        domainHash: String(currentLawInner()?.["nomos"] ?? "")
       });
       const head = typeof outcome === "string" ? outcome : String(outcome?.head ?? "");
       const readiness = await prepareDomainReady(domain, candidateHash);

package/dart/lib/src/runner/offline-install.mjs

@@ -6,7 +6,7 @@ var __export = (target, all) => {
 };
 
 // <define:__NOMOS_KERNEL_RELEASE__>
-var define_NOMOS_KERNEL_RELEASE_default = { production: { hash: "8a39dd1041ce56b820ee321eab4d10cb5e53131f216a6ab8f1135799a2cc5f98", version: "kernel-8a39dd10", features: ["compoundKeys", "capturedReads", "invariantGate", "surfacedMerge", "fieldProvenance", "nullSemantics", "attestedReads", "conflictSnapshots", "ownedAudience", "temporalEnum"], protocol: 1 }, testMint: { hash: "4ec42988fffc7dd1c4f5553aec83720a7a9bc3f27eb35da211254e66eac2661c", version: "kernel-4ec42988", features: ["compoundKeys", "capturedReads", "invariantGate", "surfacedMerge", "fieldProvenance", "nullSemantics", "attestedReads", "conflictSnapshots", "ownedAudience", "temporalEnum"], protocol: 1 } };
+var define_NOMOS_KERNEL_RELEASE_default = { production: { hash: "7d3fcc3501bef23849493026e10ce75b3ef3d1400f789181d03f4a3b0b5b1fdb", version: "kernel-7d3fcc35", features: ["compoundKeys", "capturedReads", "invariantGate", "surfacedMerge", "fieldProvenance", "nullSemantics", "attestedReads", "conflictSnapshots", "ownedAudience", "temporalEnum"], protocol: 1 }, testMint: { hash: "0ae2f9ba0fa5ec2eccb798fdcb99f46a82d76c03d851a9fc62eed47ffc25c394", version: "kernel-0ae2f9ba", features: ["compoundKeys", "capturedReads", "invariantGate", "surfacedMerge", "fieldProvenance", "nullSemantics", "attestedReads", "conflictSnapshots", "ownedAudience", "temporalEnum"], protocol: 1 } };
 
 // runner/offline-install.ts
 import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync } from "node:fs";

package/dart/pubspec.yaml

@@ -7,7 +7,7 @@ repository: https://github.com/Captain-App/nomos2
 description: >-
   Nomos 2 Dart client — generated domain values, intent payloads and application
   lifecycle types over the typed Nomos kernel protocol and USDA custody model.
-version: 0.64.15
+version: 0.64.16
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.103.18",
+  "version": "0.104.0",
   "type": "module",
   "sideEffects": false,
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",

package/runtime/generated-application-host.js

@@ -9163,7 +9163,8 @@ ${String(commit).toLowerCase()}`;
     try {
       const outcome = await offerDirective("nomos", "promoteDomain", prepared.payload, {
         actor: connectionPrincipal,
-        returnCreated: false
+        returnCreated: false,
+        domainHash: String(currentLawInner()?.["nomos"] ?? "")
       });
       const head = typeof outcome === "string" ? outcome : String(outcome?.head ?? "");
       const readiness = await prepareDomainReady(domain, candidateHash);

package/src/aggregate.ts

@@ -16,6 +16,8 @@
 import type { Field } from "./fields.js";
 import { admitsNull, attributionField, t } from "./fields.js";
 import { satisfiesContract, type ContractHandle } from "./contract.js";
+import type { FulfilmentDecl } from "./fulfilment.js";
+import { Lww } from "./drivers.js";
 
 /**
  * A pure, replay-stable predicate over one aggregate's PROJECTED snapshot —
@@ -196,6 +198,10 @@ export interface AggregateHandle<
   readonly hasMany: HasManyFields<F>;
   /** Brand so a plain string is never accepted where a handle is required. */
   readonly __isAggregateHandle: true;
+  /** The completeness declaration (`fulfilment.ts`), when this aggregate declares one. Codegen
+   *  reads it to emit the SEALED read model whose variants make each tier's guarantee a
+   *  NON-NULLABLE field — the law's guarantee becoming a type-level one. */
+  readonly fulfilment?: FulfilmentDecl;
   /** Name-only dependency handle. Export-safe, but never itself discoverable as domain law. */
   readonly __isForwardRef?: true;
   /** DOMAIN CONTRACTS this aggregate `.implements(...)` — the stable public shapes it satisfies (compile-
@@ -330,6 +336,13 @@ export interface AudienceMethods<Id extends string, F extends Record<string, Fie
 const DART_TYPE_NAME_RE = /^[A-Z][A-Za-z0-9_]*$/;
 
 type AggregateOptions = {
+  /**
+   * COMPLETENESS AS LAW (`fulfilment.ts`). Declares the record's completeness TIERS: at tier T
+   * the guarantees of T and every tier beneath it must hold, so an early record is LEGAL at a
+   * low tier instead of being refused into fabricated placeholders, while a record CLAIMING a
+   * tier it has not reached is a typed refusal.
+   */
+  fulfils?: FulfilmentDecl;
   invariant?: AggregateInvariantFn;
   invariantDeclassify?: string;
   cap?: number;
@@ -364,6 +377,22 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
     );
   }
   const { stored, hasMany } = partitionFields(fields);
+  // THE TIER FIELDS (`fulfilment.ts`). Completeness is law-state, so it is a real declared field
+  // — hashed, projected, queryable, evolvable — not something a reader re-derives by guessing
+  // which columns happen to be null. The blocked sibling records a TERMINAL reason, so "no
+  // address exists here" is distinguishable from "still resolving".
+  if (opts?.fulfils !== undefined) {
+    const decl = opts.fulfils;
+    for (const reserved of [decl.name, decl.blockedField]) {
+      if (stored[reserved] !== undefined) {
+        throw new Error(
+          `aggregate '${id}': field '${reserved}' collides with the fulfilment '${decl.name}' (it owns '${decl.name}' + '${decl.blockedField}') — rename your field`,
+        );
+      }
+    }
+    stored[decl.name] = t.enum(decl.tiers as readonly [string, ...string[]]).merge(Lww).optional();
+    stored[decl.blockedField] = t.string().merge(Lww).optional();
+  }
   // FOREIGN-REF SIBLING CHECK (pain point #4): a `t.foreignRef({ workspace, target })` field names a
   // SIBLING string field (`workspaceField`) that holds the foreign workspace id — the target workspace is
   // DYNAMIC, read from that sibling at resolve time. That link is STRINGLY-TYPED (a bare field name), so a
@@ -528,6 +557,17 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
     .map(([name]) => name)
     .sort();
   const userInvariant = opts?.invariant;
+  // TIER-SCOPED COMPLETENESS (`fulfilment.ts`), composed like the fromBirth presence check and
+  // BEFORE the user's own law: structural claims first, domain judgement second.
+  const fulfils = opts?.fulfils;
+  const afterFulfilment: AggregateInvariantFn | undefined =
+    fulfils !== undefined
+      ? (snapshot) => {
+          const verdict = fulfils.invariant(snapshot);
+          if ("reject" in verdict) return { reject: `${id}: ${verdict.reject}` };
+          return userInvariant !== undefined ? userInvariant(snapshot) : { accept: true };
+        }
+      : userInvariant;
   const composedInvariant: AggregateInvariantFn | undefined =
     fromBirthFields.length > 0
       ? (snapshot) => {
@@ -537,9 +577,9 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
               return { reject: `${id}.${name} is fromBirth() — every ${id} must carry it from creation (the plan left it unset)` };
             }
           }
-          return userInvariant !== undefined ? userInvariant(snapshot) : { accept: true };
+          return afterFulfilment !== undefined ? afterFulfilment(snapshot) : { accept: true };
         }
-      : userInvariant;
+      : afterFulfilment;
 
   // The audience-free DATA shape; the audience is attached below (from the legacy `{visibility}` opt or a
   // fluent `.public()`/`.readableBy()`/`.owned()` call).
@@ -548,6 +588,7 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
     fields: stored as StoredFields<F>,
     hasMany: hasMany as HasManyFields<F>,
     __isAggregateHandle: true as const,
+    ...(opts?.fulfils !== undefined ? { fulfilment: opts.fulfils } : {}),
     ...(composedInvariant !== undefined
       ? { hasInvariant: true as const, invariant: composedInvariant }
       : {}),

package/src/capability_exports.ts

@@ -34,7 +34,10 @@ export function isCapabilityDecl(v: unknown): v is Record<string, unknown> {
   );
 }
 
-const PIECES = ["aggregate", "obligation", "complete", "fail", "block", "deadLetter", "tasks"] as const;
+// `relations` carries the receipt fence's relation SCHEMA. It MUST expand with the bundle:
+// `.requires(...)` is inert in a law that declares no relation schema, so omitting it would
+// leave every capability looking fenced while enforcing nothing.
+const PIECES = ["aggregate", "obligation", "complete", "fail", "block", "deadLetter", "tasks", "relations", "grantProvider", "revokeProvider"] as const;
 
 /**
  * Expand every `capability()` bundle in an exports bag into discoverable

package/src/codegen_dart.ts

@@ -3411,6 +3411,146 @@ function parseReadModelField(s: AggFieldSpec, aggregate: string): string {
  * `{type,id,data}` row location) plus a DSL-named typed field per DSL
  * field declaration, and a [fromProjected] factory that reads the read engine's
  * already-decoded projected `data` shape. */
+/**
+ * THE SEALED COMPLETENESS TYPE (`fulfilment.ts`) — the tier's guarantee, made a TYPE guarantee.
+ *
+ * Declaring completeness in law fixed the domain dev's problem and, on its own, MOVED the app
+ * dev's: a flat read model hands them `tier: String?` plus nullable guaranteed fields, so the UI
+ * writes exactly the scattered conditional tiers were meant to dissolve — with more moving parts
+ * than before.
+ *
+ * So each tier becomes a VARIANT whose guaranteed fields are NON-NULLABLE, and the app switches
+ * exhaustively:
+ *
+ * ```dart
+ * switch (site.siteFulfilment) {
+ *   SiteFulfilmentResolved(:final postalAddress) => Text(postalAddress.city),
+ *   SiteFulfilmentPinned()                       => const Text('Resolving…'),
+ *   SiteFulfilmentBlocked(:final reason)         => Text(reason),
+ *   SiteFulfilmentUnfulfilled()                  => const Text('No location'),
+ * }
+ * ```
+ *
+ * No null checks, and adding a tier later fails COMPILATION until every switch handles it — the
+ * same LOUD REQUIRED discipline the DSL applies, reaching the UI.
+ *
+ * This is only expressible because the tier is LAW-STATE. Were completeness inferred from which
+ * fields happen to be null, codegen could not know which combinations are legal and could type
+ * nothing non-nullable.
+ */
+function emitFulfilmentSealed(
+  agg: AggregateHandle,
+  specs: AggFieldSpec[],
+): { code: string; consumed: Set<string>; accessorType: string; accessorName: string } | null {
+  const decl = (agg as { fulfilment?: {
+    name: string;
+    tiers: readonly string[];
+    blockedField: string;
+    guaranteesAt(tier: string): readonly string[];
+  } }).fulfilment;
+  if (decl === undefined) return null;
+
+  const base = `${dartNameStem(agg.id)}${cap(decl.name)}`;
+  const byName = new Map(specs.map((s) => [s.name, s]));
+  // A guarantee names a field path; the sealed variant carries its LEAF. A dotted path's parent
+  // (a value object holding more than the guarantee) stays on the flat model — only a top-level
+  // guarantee is fully absorbed.
+  const leafOf = (path: string) => path.split(".").pop()!;
+  const consumed = new Set<string>([decl.name, decl.blockedField]);
+  for (const tier of decl.tiers) {
+    for (const path of decl.guaranteesAt(tier)) {
+      if (!path.includes(".") && byName.has(path)) consumed.add(path);
+    }
+  }
+
+  const variantFields = (tier: string): string[] =>
+    decl.guaranteesAt(tier).map((path) => {
+      const spec = byName.get(path);
+      const name = dartMemberName(leafOf(path));
+      // NON-NULLABLE: the tier is exactly the claim that this is present.
+      const type = spec !== undefined ? stripNullable(readModelDartType(spec)) : "Object";
+      return `  final ${type} ${name};`;
+    });
+  const variantCtor = (tier: string): string => {
+    const params = decl
+      .guaranteesAt(tier)
+      .map((path) => `required this.${dartMemberName(leafOf(path))},`);
+    return params.length === 0
+      ? `  const ${base}${cap(tier)}();`
+      : [`  const ${base}${cap(tier)}({`, ...params.map((p) => `    ${p}`), `  });`].join("\n");
+  };
+
+  const code = [
+    `/// How complete this ${dartNameStem(agg.id)}'s '${decl.name}' is — a CLAIM the law enforces.`,
+    `/// Switch exhaustively; each variant's fields are non-nullable because the tier guarantees them.`,
+    `sealed class ${base} {`,
+    `  const ${base}();`,
+    `}`,
+    ``,
+    `/// No tier claimed yet: the record guarantees nothing, which is a legal state.`,
+    `final class ${base}Unfulfilled extends ${base} {`,
+    `  const ${base}Unfulfilled();`,
+    `}`,
+    ``,
+    ...decl.tiers.flatMap((tier) => [
+      `/// Tier '${tier}' — guarantees ${decl.guaranteesAt(tier).map((g) => `'${g}'`).join(", ")}.`,
+      `final class ${base}${cap(tier)} extends ${base} {`,
+      ...variantFields(tier),
+      variantCtor(tier),
+      `}`,
+      ``,
+    ]),
+    `/// Terminally unfulfillable — the climb will never happen, and [reason] says why. Distinct`,
+    `/// from "still resolving", so a progress indicator cannot lie forever.`,
+    `final class ${base}Blocked extends ${base} {`,
+    `  final String reason;`,
+    `  const ${base}Blocked({required this.reason});`,
+    `}`,
+    ``,
+    `/// Decode the tier from a projected row. The projection serves PARTIAL folds, so a row may`,
+    `/// name a tier before every guaranteed field has folded; that decodes as the highest tier`,
+    `/// whose guarantees are actually present, never a throw and never a fabricated value.`,
+    `${base} _decode${base}(Map<String, dynamic> data) {`,
+    `  final blocked = readStrOrNull(data, '${decl.blockedField}');`,
+    `  if (blocked != null && blocked.trim().isNotEmpty) {`,
+    `    return ${base}Blocked(reason: blocked);`,
+    `  }`,
+    `  final tier = readStrOrNull(data, '${decl.name}');`,
+    ...[...decl.tiers].reverse().flatMap((tier) => {
+      const guards = decl
+        .guaranteesAt(tier)
+        .map((path) => `${dartMemberName(leafOf(path))} != null`);
+      const reads = decl.guaranteesAt(tier).map((path) => {
+        const spec = byName.get(path);
+        const name = dartMemberName(leafOf(path));
+        const type = spec !== undefined ? stripNullable(readModelDartType(spec)) : "Object";
+        // The guaranteed fields are optional on the aggregate (absent at lower tiers), so the
+        // ordinary read-model parse already yields a nullable value.
+        return `    final ${name} = ${
+          spec !== undefined
+            ? parseReadModelField(spec, agg.id)
+            : `data['${leafOf(path)}'] as ${type}?`
+        };`;
+      });
+      return [
+        `  if (tier == '${tier}') {`,
+        ...reads,
+        `    if (${guards.join(" && ")}) {`,
+        `      return ${base}${cap(tier)}(${decl
+          .guaranteesAt(tier)
+          .map((p) => `${dartMemberName(leafOf(p))}: ${dartMemberName(leafOf(p))}`)
+          .join(", ")});`,
+        `    }`,
+        `  }`,
+      ];
+    }),
+    `  return const ${base}Unfulfilled();`,
+    `}`,
+    ``,
+  ].join("\n");
+  return { code, consumed, accessorType: base, accessorName: decl.name };
+}
+
 function emitReadModel(
   agg: AggregateHandle,
   enumDartTypes: Map<string, string>,
@@ -3422,13 +3562,20 @@ function emitReadModel(
 ): string {
   const className = readModelClassName(agg.id);
   const wireType = agg.id;
-  const specs = aggregateFieldSpecs(
+  const allSpecs = aggregateFieldSpecs(
     agg,
     enumDartTypes,
     refIdClassForAggregate,
     ownIdFields,
     aggregateWireTypeForAggregate,
   );
+  // THE SEALED COMPLETENESS TYPE REPLACES its fields on the flat model. Emitting both would
+  // leave the nullable ones in reach, devs would use the familiar shape, and the guarantee
+  // would buy nothing — the abstraction has to be the only surface to be worth having.
+  const sealedFulfilment = emitFulfilmentSealed(agg, allSpecs);
+  const specs = sealedFulfilment === null
+    ? allSpecs
+    : allSpecs.filter((s) => !sealedFulfilment.consumed.has(s.name));
 
   // DERIVED/COMBINED read fields are engine-projected JSON leaves. Their value schema is
   // declared in the DSL via `.returns(z...)`, so the Dart surface is typed instead of
@@ -3443,6 +3590,13 @@ function emitReadModel(
     `  /// The canonical workspace-qualified identity of this ${concreteClassName(agg.id)}.`,
     `  /// Pass this exact value to generated actions, find and watch methods.`,
     `  final NomosRef<${concreteClassName(agg.id)}> ref;`,
+    ...(sealedFulfilment !== null
+      ? [
+          `  /// How complete this record is. Switch exhaustively — each variant's fields are`,
+          `  /// non-nullable because the tier GUARANTEES them, so there is nothing to null-check.`,
+          `  final ${sealedFulfilment.accessorType} ${dartMemberName(sealedFulfilment.accessorName)};`,
+        ]
+      : []),
     ...specs.flatMap((s) => {
       const doc = s.nullReason !== undefined ? [`  /// null semantic: ${s.nullReason}`] : [];
       const temporalGuidance = s.temporalEnumIds === undefined
@@ -3478,6 +3632,13 @@ function emitReadModel(
   ].join("\n");
   const ctorParams = [
     `    required this.ref,`,
+    ...(sealedFulfilment !== null
+      ? [
+          // Defaults to Unfulfilled: the projection serves PARTIAL folds, and "nothing claimed
+          // yet" is the honest reading of a row whose tier has not folded.
+          `    this.${dartMemberName(sealedFulfilment.accessorName)} = const ${sealedFulfilment.accessorType}Unfulfilled(),`,
+        ]
+      : []),
     ...specs.map((s) =>
       // A required field is `required`; an optional scalar, a collection, OR a
       // permissive json leaf (already nullable `Object?`) takes its default/null.
@@ -3523,6 +3684,9 @@ function emitReadModel(
 
   const parseLines = [
     `      ref: NmsInternalNomosRefs.create<${concreteClassName(agg.id)}>(workspace: _location, type: _kind.isEmpty ? '${aggregateWireTypeForAggregate(agg.id)}' : _kind, id: id),`,
+    ...(sealedFulfilment !== null
+      ? [`      ${dartMemberName(sealedFulfilment.accessorName)}: _decode${sealedFulfilment.accessorType}(data),`]
+      : []),
     ...specs.map((s) =>
       s.surfaced === true
         ? `      ${s.name}: SurfacedValue.decode<${readModelDartType(s)}>(data, '${s.wireName}', ${slotDecodeCallback(s, "readModel")}),`
@@ -3543,6 +3707,7 @@ function emitReadModel(
   ].join("\n");
 
   return [
+    ...(sealedFulfilment !== null ? [sealedFulfilment.code] : []),
     `/// Generated read model for '${agg.id}'.`,
     `///`,
     `/// Deserialized via [${className}.fromProjected] from the Rust read engine's already-`,
@@ -3590,7 +3755,10 @@ function emitDirective(
   const foreignReferenceInputs = dartForeignReferenceInputs(d, aggregates);
   const foreignReferenceIds = new Set(foreignReferenceInputs.map((input) => input.idField));
   const principalField = d.businessPrincipalField;
-  const targetBinding = isBusinessIntent(d) ? d.targetBinding : undefined;
+  // targetBinding is declared on AnyDirective — honour it everywhere (client method,
+  // payload class, application surface) or the three emitters disagree and the
+  // generated Dart cannot compile.
+  const targetBinding = (d as { targetBinding?: import("./directive.js").DirectiveTargetBinding }).targetBinding;
   const targetType = targetBinding === undefined
     ? undefined
     : `NomosRef<${concreteClassName(targetBinding.aggregateId)}>`;

package/src/codegen_dart_client.ts

@@ -594,7 +594,10 @@ export function generateDartBridgeClient(
   }
   for (const d of dirs) {
     const payloadClass = dartActionInputClassName(d);
-    const targetBinding = isBusinessIntent(d) ? d.targetBinding : undefined;
+    // targetBinding is declared on AnyDirective (directive.ts) — honour it for EVERY
+    // directive, exactly as the application surface does (a split here emits a 2-arg
+    // application call against a 1-arg client method: generated Dart that cannot compile).
+    const targetBinding = (d as { targetBinding?: import("./directive.js").DirectiveTargetBinding }).targetBinding;
     const targetType = targetBinding === undefined
       ? undefined
       : `NomosRef<${concreteClassName(targetBinding.aggregateId)}>`;

package/src/codegen_provider_dart.ts

@@ -28,9 +28,10 @@
  *   1. a typed `XObligation` — the Obligation params (envelope provenance `requestId` /
  *      `requestedBy` / `requestedAt` ⊕ the tenant params from the DSL), with a
  *      `fromJson` decoding the incoming Obligation intent's payload JSON;
- *   2. a typed `XResult`  — the success payload the handler returns (`resultRef`, the
- *      content-addressed Evidence handle — the framework's `completeSchema.resultRef`),
- *      implementing `TaskResult.toResultRef()`;
+ *   2. a typed `XResult`  — the success payload the handler returns: the capability's DECLARED
+ *      receipt fields as TYPED members (they travel to the Receipt as typed USDA values, the
+ *      mirror of the Obligation's request params), plus an optional `resultRef` naming a
+ *      produced ARTIFACT. Implements `TaskResult.toReceiptFields()`/`toResultRef()`;
  *   3. typed failure/blocked/DLQ outcomes;
  *   4. a handler typedef `XHandler = TaskOutcome<XResult> Function(XObligation)`;
  *   5. a generated `XProvider` dispatcher (`implements TaskProvider`): given the
@@ -77,8 +78,16 @@ export interface ImpureCapabilityDecl {
   readonly aggregate: { readonly id: string };
   /** The Obligation directive: `.creates`, payload = envelope ⊕ tenant params. */
   readonly obligation: { readonly id: string; readonly payloadSchema: z.ZodTypeAny };
-  /** The COMPLETE (success) Receipt directive: payload = {requestId, resultRef, completedAt}. */
-  readonly complete: { readonly id: string };
+  /**
+   * The COMPLETE (success) Receipt directive: payload = the complete envelope
+   * `{requestId, completedAt}` ⊕ the capability's DECLARED receipt fields (typed USDA values,
+   * symmetrical with the obligation's params) ⊕ an optional `resultRef` artifact address.
+   *
+   * The schema is exposed for the same reason the obligation's is: so the provider SDK emits
+   * the receipt as TYPED properties. Without it the generated contract could only offer an
+   * untyped bag, which is how receipt values ended up stringly in the first place.
+   */
+  readonly complete: { readonly id: string; readonly payloadSchema?: z.ZodTypeAny };
   /** The FAIL (failure) Receipt directive: payload = {requestId, failureReason, failedAt}. */
   readonly fail: { readonly id: string };
   /** The BLOCKED Receipt directive: payload = {requestId, blockedReason, blockedAt, nextAction}. */
@@ -98,6 +107,11 @@ const OBLIGATION_ENVELOPE_FIELDS = new Set([
   "deadlineAt",
 ]);
 
+/** The framework COMPLETE-envelope field names. Everything else on the complete payload is a
+ * DECLARED receipt field the provider must supply, so the generated result type can type them
+ * individually instead of offering an untyped bag. `resultRef` is the artifact address. */
+export const COMPLETE_ENVELOPE_FIELDS = new Set(["requestId", "completedAt", "resultRef"]);
+
 /** A stable PascalCase base for a task's generated class family, derived from its Obligation
  * directive id with a leading `create`/`oblige` verb stripped (so `createTranscribeVoiceNote`
  * → `TranscribeVoiceNote`). Pure + deterministic. */
@@ -257,23 +271,63 @@ function emitObligationClass(
 }
 
 /** Emit the typed `XResult` (success) + `XFailure` classes the handler returns. */
-function emitResultClasses(base: string, completeDirectiveId: string): string {
+function emitResultClasses(
+  base: string,
+  completeDirectiveId: string,
+  receiptFields: PayloadFieldSpec[] = [],
+): string {
   const resultCls = `${base}Result`;
   const failureCls = `${base}Failure`;
+  // The DECLARED receipt fields become typed constructor params, so a provider states its
+  // result in the capability's own vocabulary. `resultRef` stays for a produced ARTIFACT and is
+  // optional whenever the capability says what it returns through declared fields.
+  const hasReceipt = receiptFields.length > 0;
+  const receiptDecls = receiptFields.map(
+    (s) => `  final ${s.dartType}${s.optional ? "?" : ""} ${s.name};`,
+  );
+  const ctorParams = [
+    ...receiptFields.map((s) => (s.optional ? `    this.${s.name},` : `    required this.${s.name},`)),
+    hasReceipt ? `    this.resultRef,` : `    required this.resultRef,`,
+  ];
+  const receiptEntries = receiptFields.map(
+    (s) =>
+      s.optional
+        ? `    if (${s.name} != null) '${s.name}': ${s.name},`
+        : `    '${s.name}': ${s.name},`,
+  );
   return [
-    `/// The typed SUCCESS RESULT the \`${base}\` handler returns. Carries the content-addressed`,
-    `/// [resultRef] (the Evidence handle — the framework \`${completeDirectiveId}\` Receipt's`,
-    `/// authoritative \`resultRef\`). [toResultRef] encodes it for the Receipt; the framework`,
-    `/// Receipt records it verbatim and a tenant \`completeResult\` may ALSO derive a typed`,
-    `/// result field from it (e.g. a voice-note's \`transcription\`).`,
+    `/// The typed SUCCESS RESULT the \`${base}\` handler returns.`,
+    ...(hasReceipt
+      ? [
+          `///`,
+          `/// The capability's DECLARED receipt fields are typed members here and travel to the`,
+          `/// \`${completeDirectiveId}\` Receipt as typed USDA values — the mirror of the`,
+          `/// Obligation's request params. [resultRef] is optional and means only what its name`,
+          `/// says: the address of a produced ARTIFACT.`,
+        ]
+      : [
+          `///`,
+          `/// This capability declares no receipt fields, so it reports through [resultRef] — the`,
+          `/// content-addressed address of what it produced. Declaring receipt fields is how a`,
+          `/// capability says something structured.`,
+        ]),
     `class ${resultCls} implements TaskResult {`,
-    `  /// The content-addressed result the side-effect produced (a blob ref / url / text`,
-    `  /// captured as Evidence) — recorded verbatim as the Receipt's \`resultRef\`.`,
-    `  final String resultRef;`,
-    `  const ${resultCls}({required this.resultRef});`,
+    ...receiptDecls,
+    `  /// The content-addressed ARTIFACT the side-effect produced (a blob ref / url).`,
+    `  final String${hasReceipt ? "?" : ""} resultRef;`,
+    `  const ${resultCls}({`,
+    ...ctorParams,
+    `  });`,
+    ``,
+    `  @override`,
+    `  String? toResultRef() => resultRef;`,
     ``,
+    `  /// The declared receipt values, keyed by their law field names — spread onto the Receipt`,
+    `  /// payload beside \`{requestId, completedAt}\`.`,
     `  @override`,
-    `  String toResultRef() => resultRef;`,
+    `  Map<String, Object?> toReceiptFields() => {`,
+    ...receiptEntries,
+    `  };`,
     `}`,
     ``,
     `/// The typed FAILURE the \`${base}\` handler returns — the recorded reason the side-effect`,
@@ -290,6 +344,7 @@ function emitResultClasses(base: string, completeDirectiveId: string): string {
 function emitProviderClass(
   task: ImpureCapabilityDecl,
   base: string,
+  receiptFields: PayloadFieldSpec[] = [],
 ): string {
   const obligationCls = `${base}Obligation`;
   const resultCls = `${base}Result`;
@@ -347,6 +402,7 @@ function emitProviderClass(
     `    return switch (outcome) {`,
     `      TaskSuccess<${resultCls}>(:final result) => ${completeCls}(`,
     `          requestId: obligation.requestId,`,
+    ...receiptFields.map((f) => `          ${f.name}: result.${f.name},`),
     `          resultRef: result.toResultRef(),`,
     `          completedAt: now(),`,
     `        ),`,
@@ -384,13 +440,20 @@ export function emitProviderTask(
 ): string {
   const base = taskBaseName(task.obligation.id);
   const specs = introspectPayload(task.obligation.payloadSchema, enumDartTypes);
+  // The declared receipt fields = the complete payload minus the framework envelope. Typed
+  // here so the generated result class states them individually instead of a stringly bag.
+  const receiptSpecs = task.complete.payloadSchema
+    ? introspectPayload(task.complete.payloadSchema, enumDartTypes).filter(
+        (s) => !COMPLETE_ENVELOPE_FIELDS.has(s.name),
+      )
+    : [];
   return [
     `// ── provider SDK: ${base} (impureCapability '${task.aggregate.id}') ──`,
     emitObligationClass(base, task.obligation.id, specs),
     ``,
-    emitResultClasses(base, task.complete.id),
+    emitResultClasses(base, task.complete.id, receiptSpecs),
     ``,
-    emitProviderClass(task, base),
+    emitProviderClass(task, base, receiptSpecs),
   ].join("\n");
 }
 

package/src/compile_package_main.ts

@@ -14,7 +14,7 @@
  *     export default {
  *       name: "guestbook",                       // → build/guestbook.law.usdz + readable USDA
  *       domains: [
- *         { key: "guestbook", modules: ["./domains/guestbook.ts"] },
+ *         { key: "guestbook", features: [{ key: "guestbook", modules: ["./domains/guestbook.ts"] }] },
  *       ],
  *     };
  *
@@ -1648,12 +1648,12 @@ const dartTypesImportFor = (generatedSource: string): string => {
  *  just the floor generated code needs — a lagging pin forces tenants into dependency_overrides. */
 // 0.3.0: SurfacedValue<T>/SurfacedObservation/PendingConflictRow — generated Surfaced-field typing +
 //        the pendingConflicts read rows.
-const NOMOS_TYPES_DEP = "^0.8.4";
+const NOMOS_TYPES_DEP = "^0.8.5";
 // 0.48.x: session-bound clients (XClient.bind/NomosClientInterface/DomainClientSessionMismatch/
 //         DomainNotInstalledForSession, engine.follow, pendingConflicts lanes) — the generated client
 //         REQUIRES this surface. 0.48.1 fixes NomosSession.watchPendingConflicts delegation.
-const NOMOS_CLIENT_DEP = "^0.64.14";
-const NOMOS_FLUTTER_DEP = "^0.63.22";
+const NOMOS_CLIENT_DEP = "^0.64.16";
+const NOMOS_FLUTTER_DEP = "^0.63.24";
 // DRIFT TRIPWIRE: pubspec_pins.test.ts asserts these equal the CURRENT versions in dsl/dart/pubspec.yaml
 // and dsl/dart_types/pubspec.yaml — a Dart release without this bump fails the suite, so tenants never
 // land back in dependency_overrides (the exact co2 report this closes, third occurrence).