@githolon/dsl 0.14.0 → 0.16.0

package/src/codegen_dart.ts

@@ -15,13 +15,13 @@
  *     emit (e.g. `{name:"HQ", createdAt:1000}`);
  *   - typed READ accessors per aggregate + per declared query — reactive
  *     `watch…`/one-shot `read…` over the GitHolon `query()`/`query_by_id()`
- *     surface (the read half of the dispatch(intent) boundary);
+ *     surface (the read half of the offer/query boundary);
  *   - a Dart enum per `t.enum([...])` field;
  *   - a Dart intent class per domain action — a pure typed DTO. Each class exposes its
  *     `domain` / `intentType` (so the call site never hand-types a string) and a
  *     `toPayloadJson()` that serialises only its typed fields to data. It builds no
  *     `Event` and no `Hlc`: the GitHolon executes the installed domain plan.
- *   - a single generic write verb [`dispatch`] that ships {domain, intentType,
+ *   - a single generic effectful write verb [`offer`] that ships {domain, intentType,
  *     toPayloadJson()} to the GitHolon `author(domain, intentType, payloadJson, actor)`.
  *
  * It does NOT hand-write the fixed wire types (`Value`/`Op`/`Event`/...): those
@@ -671,13 +671,24 @@ function aggregateFieldSpecs(
         f.kind === "string" && ownIdFields.has(name)
           ? aggregateIdDartType(agg.id)
           : undefined;
-      const spec = aggFieldSpec(
+      const base = aggFieldSpec(
         name,
         f,
         enumDartTypes,
         refIdClassForAggregate,
         valueClass,
       );
+      // PARTIAL-FOLD DOCTRINE (every read-model field is nullable). The projection
+      // serves PARTIAL folds: a freshly-created or not-yet-fully-folded aggregate may
+      // carry no value for ANY scalar (only the fields touched so far appear in the
+      // flat `data`). So a read-model SCALAR is ALWAYS nullable — never a strict
+      // `as bool`/`readInt` that throws on an absent field (the `watch`/`read`
+      // decode would crash mid-fold). `.optional()` on the DSL field no longer
+      // changes the read surface; it was nullable in practice — this makes the type
+      // honest. Collections are unchanged (they already empty-default when absent).
+      const spec: AggFieldSpec = isCollectionKind(base.kind)
+        ? base
+        : { ...base, optional: true };
       if (used.has(spec.name)) {
         throw new Error(
           `aggregate '${agg.id}' field '${spec.wireName}' maps to duplicate Dart field '${spec.name}'`,
@@ -828,7 +839,7 @@ function emitPermissionVocabulary(vocab: PermissionVocabulary | undefined): stri
   return [
     `/// Generated permission vocabulary from the domain role catalogue.`,
     `///`,
-    `/// This is frontend read/dispatch vocabulary only. Domain execution and`,
+    `/// This is frontend read/offer vocabulary only. Domain execution and`,
     `/// admission still happen inside the installed GitHolon domain law.`,
     `class PermissionRole {`,
     `  const PermissionRole(this.value, this.capabilities);`,
@@ -1049,9 +1060,9 @@ function emitAggregate(
     `/// projection \`data\` map (the \`{type,id,data}\` row \`query()\`/\`query_by_id()\``,
     `/// emits) — e.g. \`{"name":"HQ","createdAt":1000}\`. The kernel aggregate`,
     `/// [aggregateId] is carried from the row \`id\`. Read it reactively through the`,
-    `/// generated \`watch…\` accessors below. Collection fields (\`set\`/\`map\`) default to`,
-    `/// EMPTY and \`.optional()\` scalars to \`null\` when a freshly-folded aggregate has`,
-    `/// not yet folded them; must-be-folded scalars still throw when absent.`,
+    `/// generated \`watch…\` accessors below. The projection serves PARTIAL folds, so`,
+    `/// EVERY scalar field is nullable — \`null\` when a freshly-folded aggregate has not`,
+    `/// yet folded it (never a strict cast that throws); collections default to EMPTY.`,
     `class ${className} {`,
     fieldDecls,
     ``,
@@ -1062,9 +1073,8 @@ function emitAggregate(
     `  /// Parse from the FLAT projection \`data\` map (the \`{type,id,data}\` row's`,
     `  /// \`data\` that \`query()\`/\`query_by_id()\` emit — fields already`,
     `  /// decoded to bare JSON), carrying the kernel aggregate [id] from the row \`id\``,
-    `  /// (defaults to '' for a bare-map call). Missing REQUIRED fields throw a`,
-    `  /// [FormatException]; absent collections decode empty and absent \`.optional()\``,
-    `  /// scalars decode \`null\`.`,
+    `  /// (defaults to '' for a bare-map call). PARTIAL folds: every scalar decodes`,
+    `  /// \`null\` when absent (never throws); absent collections decode empty.`,
     `  factory ${className}.fromJson(Map<String, dynamic> data, [String id = '']) {`,
     `    return ${className}(`,
     parseLines,
@@ -1125,7 +1135,7 @@ function emitEvidenceRefClass(): string {
     `    );`,
     `  }`,
     ``,
-    `  /// The authored payload shape (for dispatch): the typed value-object the DSL`,
+    `  /// The authored payload shape (for offer): the typed value-object the DSL`,
     `  /// \`t.evidence()\` field lowers to a kernel \`Value::Evidence\`.`,
     `  Map<String, Object?> toJson() => <String, Object?>{`,
     `        'hash': hash,`,
@@ -1471,8 +1481,9 @@ function emitReadModel(
     `/// DSL-named; a \`json\` value-object leaf (e.g. \`location\`)`,
     `/// is a STRUCTURED \`Map<String, Object?>\` — the decoded shape the engine emits, NOT a`,
     `/// JSON string. This class is fully DSL-derived.`,
-    `/// Collection fields (\`set\`/\`map\`) default to EMPTY and \`.optional()\` scalars to`,
-    `/// \`null\` when a freshly-folded aggregate has not yet folded them.`,
+    `/// The projection serves PARTIAL folds, so EVERY scalar field is nullable —`,
+    `/// \`null\` when a freshly-folded aggregate has not yet folded it (never a strict`,
+    `/// cast that throws); collection fields (\`set\`/\`map\`) default to EMPTY.`,
     `class ${className} {`,
     fieldDecls,
     ``,
@@ -1483,9 +1494,8 @@ function emitReadModel(
     `  /// Parse from the Rust read engine's already-decoded projected \`data\` map (the`,
     `  /// \`{type,id,data}\` row's \`data\` that \`query()\`/\`query_by_id()\` emit — every field`,
     `  /// already decoded to bare/structured JSON), carrying the kernel aggregate [id] from`,
-    `  /// the row \`id\` (defaults to '' for a bare-map call). Missing REQUIRED fields throw a`,
-    `  /// [FormatException]; absent collections decode empty and absent \`.optional()\` scalars`,
-    `  /// decode \`null\`.`,
+    `  /// the row \`id\` (defaults to '' for a bare-map call). PARTIAL folds: every scalar`,
+    `  /// decodes \`null\` when absent (never throws); absent collections decode empty.`,
     `  factory ${className}.fromProjected(Map<String, dynamic> data, [String id = '']) {`,
     `    return ${className}(`,
     parseLines,
@@ -1536,7 +1546,7 @@ function emitDirective(
     `/// Generated typed intent DTO for '${d.id}' (marker: ${d.marker},`,
     `/// aggregate: ${d.aggregateId}). It carries its [domain] + [intentType] and a`,
     `/// [toPayloadJson] that ships only typed fields as data. It builds no`,
-    `/// \`Event\` and no \`Hlc\`. Pass it to [dispatch]; the GitHolon executes`,
+    `/// \`Event\` and no \`Hlc\`. Pass it to [offer]; the GitHolon executes`,
     `/// the installed domain plan.`,
     `class ${className} implements NomosIntent {`,
     `  /// The policy domain this intent belongs to (the kernel \`author\` \`domain\`).`,
@@ -1587,7 +1597,7 @@ export function toJsonExpr(spec: PayloadFieldSpec, accessor: string): string {
 
 // ---- read accessors (typed subscriptions) ----------------------------------
 //
-// The READ half of the peer dispatch surface (Jack 2026-06-01): the app reads ONLY via
+// The READ half of the peer query surface (Jack 2026-06-18): the app reads ONLY via
 // these generated typed accessors over the GitHolon read surface
 // (`query(query_id, params_json)` + `query_by_id(aggregate_id)`, #140's indexed/PK
 // read-closure). It invents NO new Rust read primitive. Two emitters:
@@ -2503,11 +2513,11 @@ export interface DomainModule {
    */
   readModelAggregates?: string[];
   /**
-   * The domain's `impureCapability` capabilities (framework Order→Receipt; `impure_capability.ts`)
+   * The domain's `impureCapability` capabilities (framework Obligation→Receipt; `impure_capability.ts`)
    * for which to ALSO emit the typed PROVIDER SDK — the symmetric twin of the peer
-   * payload classes. For each declared task the codegen emits a typed `XOrder` (+
+   * payload classes. For each declared task the codegen emits a typed `XObligation` (+
    * `fromJson`), `XResult`/`XFailure`, a `XHandler` typedef and a `XProvider` dispatcher
-   * that decodes the incoming Order JSON and encodes the Receipt (reusing the
+   * that decodes the incoming Obligation JSON and encodes the Receipt (reusing the
    * peer-codegen `CompleteXPayload`/`FailXPayload`, so the Receipt is an ordinary
    * intent through the ONE write path). ADDITIVE + OPTIONAL: a domain that omits this is
    * byte-identical to before. NOT carried into any manifest/hash — a pure provider-side
@@ -2571,10 +2581,10 @@ export function generateDartDomain(mod: DomainModule): string {
   const mintedBlock = emitMintedCreates(mod.aggregates, mod.directives, domainKey, dartTypes);
 
   // PROVIDER SDK (the symmetric twin of the peer payload classes): for each declared
-  // `impureCapability` capability, a typed Order/Result/Failure + handler typedef + dispatcher.
+  // `impureCapability` capability, a typed Obligation/Result/Failure + handler typedef + dispatcher.
   // ADDITIVE + omit-when-empty: a domain with no `impureCapabilities` emits nothing (and the
   // `provider.dart` import is omitted), so it is byte-identical to before. The enum map is
-  // SHARED with the directive/aggregate codegen so an enum-typed order param references the
+  // SHARED with the directive/aggregate codegen so an enum-typed obligation param references the
   // already-emitted domain enum (no duplicate decl).
   const providerBlock = emitProviderSdk(mod.impureCapabilities ?? [], dartTypes);
 
@@ -2766,7 +2776,7 @@ export function generateDartDomain(mod: DomainModule): string {
           ``,
         ]
       : []),
-    `// ---- public intents (typed DTOs; ship via the generic dispatch() verb) ----`,
+    `// ---- public intents (typed DTOs; ship via the generic offer() verb) ----`,
     dirBlock,
     ``,
     ...(mintedBlock !== ""

package/src/codegen_dart_client.ts

@@ -13,7 +13,7 @@
  * hashed (the deployed law's content hash baked in), carrying a `<Domain>Client` over a connected
  * [NomosBridge] (the WebView runner) with:
  *
- *   * a typed DISPATCH method per directive — takes the generated `…Payload`, serialises via its
+ *   * a typed OFFER method per directive — takes the generated `…Payload`, serialises via its
  *     `toPayloadJson()`, auto-stamps omitted `…At` timestamps (the same caller-clock sugar the TS
  *     client applies), returns the new local head;
  *   * a typed declared-QUERY accessor per `query(...)` — one-shot `Future<List<…ReadModel>>` + a
@@ -21,9 +21,10 @@
  *   * by-id read/watch + a type-index `list…` per aggregate;
  *   * typed O(1) count/sum accessors.
  *
- * It IMPORTS the sibling `<name>.dart` (for the read-model + payload classes) and the vendored
- * `nomos_dsl.dart` barrel (for `NomosBridge`). NO manifest/hash impact — pure frontend codegen, exactly
- * like `codegen_dart.ts`. NO FALLBACK: an unsupported shape throws at compile time.
+ * It IMPORTS the sibling `<name>.dart` (for the read-model + payload classes) and either the vendored
+ * `nomos_dsl.dart` barrel or the package `nomos_dsl` barrel (for `NomosBridge`). NO manifest/hash impact —
+ * pure frontend codegen, exactly like `codegen_dart.ts`. NO FALLBACK: an unsupported shape throws at compile
+ * time.
  */
 import type { z } from "zod";
 
@@ -56,6 +57,15 @@ export const dartClientClassName = (domain: string): string => `${cap(camel(doma
 /** `guestbook` → `guestbookDomainHash` — the Dart top-level const (lowerCamel by lint). */
 export const dartHashConstName = (fileBase: string): string => `${lcFirst(camel(fileBase))}DomainHash`;
 
+/** `todo-nomos` → `todoNomosInterfaceJson` — the baked structural-interface JSON const (#72). */
+export const interfaceConstNameDart = (fileBase: string): string => `${lcFirst(camel(fileBase))}InterfaceJson`;
+
+/** Emit a Dart RAW triple-quoted string literal of an object's JSON (the interface is JSON-only
+ *  data — no `'`/`$`/backslash escaping concerns under `r'''…'''`; JSON never contains `'''`). */
+function dartRawJson(value: unknown): string {
+  return `r'''${JSON.stringify(value)}'''`;
+}
+
 const dartStr = (s: string) => `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
 
 /** The Dart param type for a query index key (int-kinded keys → `int`, else `String`). */
@@ -81,8 +91,14 @@ function rowToModel(model: string, rowVar: string): string {
 }
 
 export interface DartBridgeClientOptions {
-  /** sha256 of the built `.package.usda` — the law this client dispatches under. */
+  /** sha256 of the built `.package.usda` — the law this client offers under. */
   readonly domainHash: string;
+  /** This domain's STRUCTURAL INTERFACE (#72) — directives (payload shapes) + aggregates
+   *  (read shapes, sid-keyed). Baked in as JSON so the app can negotiate shape-compatibility
+   *  against the workspace's installed offer, NOT by law hash. */
+  readonly interface?: unknown;
+  /** Where the bridge/runtime support types are imported from. */
+  readonly supportImport?: "vendored" | "package";
 }
 
 /** Generate the `<name>.client.dart` async bridge client for one domain module. */
@@ -90,12 +106,16 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
   const domain = mod.domain ?? mod.name;
   const className = dartClientClassName(domain);
   const hashConst = dartHashConstName(mod.name);
+  const supportImport =
+    opts.supportImport === "package"
+      ? "package:nomos_dsl/nomos_dsl.dart"
+      : "nomos_dsl.dart";
   const aggById = new Map<string, AggregateHandle>();
   for (const a of mod.aggregates) aggById.set(a.id, a);
 
   const methods: string[] = [];
 
-  // ── directives → typed dispatch ──
+  // ── directives → typed offer ──
   const dirs = (mod.directives as AnyDirective[]).filter(
     (d) => d && typeof d.id === "string" && typeof (d as { payloadSchema?: unknown }).payloadSchema === "object",
   );
@@ -106,12 +126,12 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     if (stamps.length > 0) {
       methods.push(
         `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
-        `  /// Omitted ${stamps.map((s) => `\`${s}\``).join(" / ")} auto-stamp(s) ISO now() at dispatch.`,
+        `  /// Omitted ${stamps.map((s) => `\`${s}\``).join(" / ")} auto-stamp(s) ISO now() at offer.`,
         `  Future<String> ${method}(${payloadClass} payload) {`,
         `    final data = payload.toPayloadJson();`,
         `    final now = DateTime.now().toUtc().toIso8601String();`,
         ...stamps.map((s) => `    data.putIfAbsent(${dartStr(s)}, () => now);`),
-        `    return bridge.dispatch(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: data, domainHash: domainHash);`,
+        `    return bridge.offer(intentBytes: _encodeIntentOffer(${dartStr(domain)}, ${dartStr(d.id)}, data, domainHash));`,
         `  }`,
         ``,
       );
@@ -119,7 +139,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       methods.push(
         `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
         `  Future<String> ${method}(${payloadClass} payload) =>`,
-        `      bridge.dispatch(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: payload.toPayloadJson(), domainHash: domainHash);`,
+        `      bridge.offer(intentBytes: _encodeIntentOffer(${dartStr(domain)}, ${dartStr(d.id)}, payload.toPayloadJson(), domainHash));`,
         ``,
       );
     }
@@ -196,22 +216,64 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `//   final app = ${className}(bridge);`,
     `//   await app.${dirs[0] ? safeMethod(dirs[0].id) : "someDirective"}(/* typed payload */);`,
     ``,
-    `import 'nomos_dsl.dart';`,
+    `import 'dart:convert';`,
+    ``,
+    `import '${supportImport}';`,
     `import '${mod.name}.dart';`,
     `// Re-export the sibling types (read models + payloads + the bridge runtime) so ONE import of this`,
     `// client file gives an app the whole typed surface.`,
     `export '${mod.name}.dart';`,
-    `export 'nomos_dsl.dart' show NomosBridge, BridgeTransport, NomosBridgeError, kWebviewBridgeVersion;`,
+    `export '${supportImport}' show NomosBridge, BridgeTransport, NomosBridgeError, kWebviewBridgeVersion;`,
     ``,
-    `/// sha256 of the deployed \`.package.usda\` — the installed law this client dispatches under.`,
+    `/// sha256 of the deployed \`.package.usda\` — the installed law this client offers under.`,
     `const String ${hashConst} = ${dartStr(opts.domainHash)};`,
     ``,
+    ...(opts.interface !== undefined
+      ? [
+          `/// This client's STRUCTURAL INTERFACE REQUIREMENT (#72) as JSON — the directives (payload`,
+          `/// shapes) + aggregates (read shapes, sid-keyed) it depends on. \`connect()\` negotiates this`,
+          `/// against the workspace's installed offer by SHAPE (stable-id subtyping), not by law hash,`,
+          `/// so the domain can evolve without republishing this client.`,
+          `const String ${interfaceConstNameDart(mod.name)} = ${dartRawJson(opts.interface)};`,
+          ``,
+        ]
+      : []),
+    `String _encodeIntentOffer(String domain, String directiveId, Object? payload, String domainHash) =>`,
+    `    base64Encode(utf8.encode(jsonEncode({`,
+    `      'v': 2,`,
+    `      'intent': {`,
+    `        'domain': domain,`,
+    `        'directiveId': directiveId,`,
+    `        'payload': payload,`,
+    `        'domainHash': domainHash,`,
+    `      },`,
+    `    })));`,
+    ``,
     `/// Typed async client for the \`${domain}\` domain, bound to a connected [NomosBridge].`,
     `class ${className} {`,
     `  final NomosBridge bridge;`,
     `  final String domainHash;`,
     `  ${className}(this.bridge, {this.domainHash = ${hashConst}});`,
     ``,
+    ...(opts.interface !== undefined
+      ? [
+          `  /// This client's structural interface requirement (#72) as JSON — hand it to the`,
+          `  /// bridge's compatibility check to negotiate by SHAPE against the workspace's offer.`,
+          `  String get interfaceJson => ${interfaceConstNameDart(mod.name)};`,
+          ``,
+          `  Map<String, Object?> get _requirement =>`,
+          `      {${dartStr(domain)}: (jsonDecode(interfaceJson) as Map).cast<String, Object?>()};`,
+          ``,
+          `  /// SHAPE COMPATIBILITY (#72): one-shot verdict for THIS client against the workspace's`,
+          `  /// ON-LEDGER offer — \`{ ok, missing[], incompatible[] }\`, by shape not law hash.`,
+          `  Future<Map<String, Object?>> checkCompatibility() => bridge.checkCompatibility(_requirement);`,
+          ``,
+          `  /// SHAPE COMPATIBILITY as a LIVE BINDING (#72): a stream of verdicts that re-emits whenever`,
+          `  /// the workspace's installed law changes (a synced install/upgrade from another peer).`,
+          `  Stream<Map<String, Object?>> watchCompatibility() => bridge.watchCompatibility(_requirement);`,
+          ``,
+        ]
+      : []),
     ...methods,
     `}`,
     ``,

package/src/codegen_provider_dart.ts

@@ -9,32 +9,32 @@
  * Provider SDK codegen — the SYMMETRIC TWIN of the typed peer write codegen
  * (`codegen_dart.ts`).
  *
- * Order and Receipt are ordinary intent roles. This codegen gives a capability provider typed
+ * Obligation and Receipt are ordinary intent roles. This codegen gives a capability provider typed
  * decode/encode helpers; it does not create a separate admission job protocol or a privileged
  * mutation path.
  *
  * ── Why this exists (Jack 2026-06-04) ────────────────────────────────────────
  * Code is ~free; INTEGRATION POINTS are expensive + fuckup-guaranteed. A capability
  * PROVIDER (Whisper, a renderer, a multi-target PR transporter) sits at
- * the far end of the framework `impureCapability` Order→Receipt pair. Today a dev would
- * hand-parse the incoming Order intent JSON and hand-build the Receipt — exactly the
+ * the far end of the framework `impureCapability` Obligation→Receipt pair. Today a dev would
+ * hand-parse the incoming Obligation intent JSON and hand-build the Receipt — exactly the
  * brittle integration the peer write codegen eliminated on the WRITE side. This generator
  * eliminates it on the PROVIDE side: a dev writes ONE typed method
- * `handler(Order) -> Result | Failure`, and the generated dispatcher DECODES the Order
+ * `handler(Obligation) -> Result | Failure`, and the generated dispatcher DECODES the Obligation
  * and ENCODES the ordinary Receipt intent — proven in ISOLATION (a Dart unit test), with NO deploy /
  * daemon / e2e.
  *
  * ── What it emits, per `impureCapability` capability (the STANDARD shape, never invented) ──
- *   1. a typed `XOrder`   — the Order params (envelope provenance `requestId` /
+ *   1. a typed `XObligation` — the Obligation params (envelope provenance `requestId` /
  *      `requestedBy` / `requestedAt` ⊕ the tenant params from the DSL), with a
- *      `fromJson` decoding the incoming Order intent's payload JSON;
+ *      `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()`;
  *   3. typed failure/blocked/DLQ outcomes;
- *   4. a handler typedef `XHandler = TaskOutcome<XResult> Function(XOrder)`;
+ *   4. a handler typedef `XHandler = TaskOutcome<XResult> Function(XObligation)`;
  *   5. a generated `XProvider` dispatcher (`implements TaskProvider`): given the
- *      registered typed handler, `handleOrder(orderJson, now)` DECODES → calls the
+ *      registered typed handler, `handleObligation(obligationJson, now)` DECODES → calls the
  *      handler → ENCODES the typed outcome into the ordinary RECEIPT intent — REUSING the peer write
  *      codegen's `CompleteXPayload` / `FailXPayload` / `BlockXPayload` /
  *      `DeadLetterXPayload`. The Receipt is an
@@ -61,7 +61,7 @@ import {
 /**
  * The minimal shape of a `impureCapability` declaration the provider codegen needs. A
  * `ImpureCapability` (framework `impure_capability.ts`) carries EXACTLY this — its task `aggregate`
- * handle (whose `.id` is the wire type) and its `.order` / receipt directives
+ * handle (whose `.id` is the wire type) and its `.obligation` / receipt directives
  * directives — so a `impureCapability(...)` return value satisfies `ImpureCapabilityDecl`
  * STRUCTURALLY. The emit script passes the values straight through: no re-derivation, no
  * fragile structural inference over the flattened directive list.
@@ -69,8 +69,8 @@ import {
 export interface ImpureCapabilityDecl {
   /** The task aggregate handle; `.id` is the wire type (e.g. `TranscribeVoiceNoteAggregate`). */
   readonly aggregate: { readonly id: string };
-  /** The ORDER directive: `.creates`, payload = envelope ⊕ tenant params. */
-  readonly order: { readonly id: string; readonly payloadSchema: z.ZodTypeAny };
+  /** 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 FAIL (failure) Receipt directive: payload = {requestId, failureReason, failedAt}. */
@@ -81,17 +81,23 @@ export interface ImpureCapabilityDecl {
   readonly deadLetter: { readonly id: string };
 }
 
-/** The framework ORDER-ENVELOPE field names — provenance, NOT tenant params. The Order
- * type carries them (the provider sees the whole Order intent) but the codegen labels
+/** The framework Obligation envelope field names — provenance/timing, NOT tenant params. The Obligation
+ * type carries them (the provider sees the whole Obligation intent) but the codegen labels
  * them so the doc separates provenance from the tenant's request params. */
-const ORDER_ENVELOPE_FIELDS = new Set(["requestId", "requestedBy", "requestedAt"]);
+const OBLIGATION_ENVELOPE_FIELDS = new Set([
+  "requestId",
+  "requestedBy",
+  "requestedAt",
+  "scheduledAt",
+  "deadlineAt",
+]);
 
-/** A stable PascalCase base for a task's generated class family, derived from its ORDER
- * directive id with a leading `create`/`order` verb stripped (so `createTranscribeVoiceNote`
+/** 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. */
-export function taskBaseName(orderDirectiveId: string): string {
-  const stripped = orderDirectiveId.replace(/^(create|order)/, "");
-  const base = stripped === "" ? orderDirectiveId : stripped;
+export function taskBaseName(obligationDirectiveId: string): string {
+  const stripped = obligationDirectiveId.replace(/^(create|oblige)/, "");
+  const base = stripped === "" ? obligationDirectiveId : stripped;
   return cap(base);
 }
 
@@ -109,21 +115,21 @@ function deadLetterPayloadClass(deadLetterDirectiveId: string): string {
   return `${cap(deadLetterDirectiveId)}Payload`;
 }
 
-/** Dart field DECL for one Order field (optional → nullable). */
-function orderFieldDecl(s: PayloadFieldSpec): string {
-  const provenance = ORDER_ENVELOPE_FIELDS.has(s.name)
+/** Dart field DECL for one Obligation field (optional → nullable). */
+function obligationFieldDecl(s: PayloadFieldSpec): string {
+  const provenance = OBLIGATION_ENVELOPE_FIELDS.has(s.name)
     ? ` // envelope provenance (framework)`
     : ``;
   return `  final ${s.dartType}${s.optional ? "?" : ""} ${s.name};${provenance}`;
 }
 
-/** Dart ctor PARAM for one Order field. */
-function orderCtorParam(s: PayloadFieldSpec): string {
+/** Dart ctor PARAM for one Obligation field. */
+function obligationCtorParam(s: PayloadFieldSpec): string {
   return `    ${s.optional ? "" : "required "}this.${s.name},`;
 }
 
 /**
- * Expression decoding ONE Order field FROM the already-`jsonDecode`d payload map `j`.
+ * Expression decoding ONE Obligation field FROM the already-`jsonDecode`d payload map `j`.
  * The REVERSE of the peer codegen's `toJsonExpr` — same field-kind matrix:
  *   • scalar  — read directly, cast to the Dart scalar type.
  *   • enum    — `XEnum.fromWire(j['f'] as String)`.
@@ -132,7 +138,7 @@ function orderCtorParam(s: PayloadFieldSpec): string {
  * Optional fields tolerate absence (return null); required fields cast strictly (a
  * missing required field throws on the cast — the strict-decode contract).
  */
-function orderFromJsonExpr(s: PayloadFieldSpec): string {
+function obligationFromJsonExpr(s: PayloadFieldSpec): string {
   const raw = `j['${s.name}']`;
   switch (s.toJson) {
     case "scalar": {
@@ -168,22 +174,22 @@ function orderFromJsonExpr(s: PayloadFieldSpec): string {
   }
 }
 
-/** Emit the typed `XOrder` class — the DECODED incoming Order. */
-function emitOrderClass(
+/** Emit the typed `XObligation` class — the DECODED incoming Obligation. */
+function emitObligationClass(
   base: string,
-  orderDirectiveId: string,
+  obligationDirectiveId: string,
   specs: PayloadFieldSpec[],
 ): string {
-  const cls = `${base}Order`;
-  const fieldDecls = specs.map(orderFieldDecl).join("\n");
-  const ctorParams = specs.map(orderCtorParam).join("\n");
+  const cls = `${base}Obligation`;
+  const fieldDecls = specs.map(obligationFieldDecl).join("\n");
+  const ctorParams = specs.map(obligationCtorParam).join("\n");
   const fromJsonAssigns = specs
-    .map((s) => `      ${s.name}: ${orderFromJsonExpr(s)},`)
+    .map((s) => `      ${s.name}: ${obligationFromJsonExpr(s)},`)
     .join("\n");
   return [
-    `/// The typed ORDER for the \`${orderDirectiveId}\` capability — what the provider`,
+    `/// The typed Obligation for the \`${obligationDirectiveId}\` capability — what the provider`,
     `/// RECEIVES. Carries the framework envelope provenance (requestId / requestedBy /`,
-    `/// requestedAt) ⊕ the tenant request params. Decoded from the incoming Order intent's`,
+    `/// requestedAt / scheduledAt / deadlineAt) ⊕ the tenant request params. Decoded from the incoming Obligation intent's`,
     `/// payload JSON via [${cls}.fromJson]; the handler sees ONLY this typed value.`,
     `class ${cls} {`,
     fieldDecls,
@@ -192,8 +198,8 @@ function emitOrderClass(
     ctorParams,
     `  });`,
     ``,
-    `  /// Decode an Order from the already-\`jsonDecode\`d payload map (the EXACT shape the`,
-    `  /// peer's \`${orderDirectiveId}\` \`toPayloadJson()\` produced). Reverse of the peer`,
+    `  /// Decode an Obligation from the already-\`jsonDecode\`d payload map (the EXACT shape the`,
+    `  /// peer's \`${obligationDirectiveId}\` \`toPayloadJson()\` produced). Reverse of the peer`,
     `  /// encode — types stop here, at the JSON serde.`,
     `  factory ${cls}.fromJson(Map<String, Object?> j) => ${cls}(`,
     fromJsonAssigns,
@@ -224,7 +230,7 @@ function emitResultClasses(base: string, completeDirectiveId: string): string {
     ``,
     `/// The typed FAILURE the \`${base}\` handler returns — the recorded reason the side-effect`,
     `/// failed. Maps to the framework \`fail…\` Receipt (status:failed + failureReason +`,
-    `/// closesOrder); a recorded failure is terminal, NOT a retry storm.`,
+    `/// closesObligation); a recorded failure is terminal, NOT a retry storm.`,
     `class ${failureCls} {`,
     `  final String failureReason;`,
     `  const ${failureCls}({required this.failureReason});`,
@@ -237,7 +243,7 @@ function emitProviderClass(
   task: ImpureCapabilityDecl,
   base: string,
 ): string {
-  const orderCls = `${base}Order`;
+  const obligationCls = `${base}Obligation`;
   const resultCls = `${base}Result`;
   const handlerTypedef = `${base}Handler`;
   const providerCls = `${base}Provider`;
@@ -247,25 +253,25 @@ function emitProviderClass(
   const deadLetterCls = deadLetterPayloadClass(task.deadLetter.id);
   return [
     `/// The typed HANDLER the dev writes for the \`${base}\` capability: given the typed`,
-    `/// [${orderCls}], perform the side-effect and return a typed [TaskOutcome] — a`,
+    `/// [${obligationCls}], perform the side-effect and return a typed [TaskOutcome] — a`,
     `/// [TaskSuccess]<[${resultCls}]>, [TaskFailure], [TaskBlocked], or [TaskDeadLetter]. NO raw JSON, NO directive id, NO`,
     `/// Receipt construction: the dev writes pure typed business logic; the [${providerCls}]`,
     `/// does the decode/encode round-trip.`,
-    `typedef ${handlerTypedef} = TaskOutcome<${resultCls}> Function(${orderCls} order);`,
+    `typedef ${handlerTypedef} = TaskOutcome<${resultCls}> Function(${obligationCls} obligation);`,
     ``,
     `/// The GENERATED dispatcher for the \`${base}\` capability — the symmetric twin of the`,
-    `/// peer's typed dispatch. Register a typed [${handlerTypedef}]; [handleOrder] DECODES an`,
-    `/// incoming Order intent JSON into [${orderCls}], runs the handler, and ENCODES the typed`,
+    `/// peer's typed dispatch. Register a typed [${handlerTypedef}]; [handleObligation] DECODES an`,
+    `/// incoming Obligation intent JSON into [${obligationCls}], runs the handler, and ENCODES the typed`,
     `/// outcome into the ordinary RECEIPT intent: [${completeCls}], [${failCls}],`,
     `/// [${blockCls}], or [${deadLetterCls}]. The returned [NomosIntent] ships through the SAME`,
     `/// \`dispatch\` gate as any authored write (ONE-WRITE-PATH).`,
-    `class ${providerCls} implements TaskProvider<${orderCls}, ${resultCls}> {`,
+    `class ${providerCls} implements TaskProvider<${obligationCls}, ${resultCls}> {`,
     `  /// The dev's typed handler.`,
     `  final ${handlerTypedef} handler;`,
     `  const ${providerCls}(this.handler);`,
     ``,
     `  @override`,
-    `  String get orderDirectiveId => '${task.order.id}';`,
+    `  String get obligationDirectiveId => '${task.obligation.id}';`,
     `  @override`,
     `  String get completeDirectiveId => '${task.complete.id}';`,
     `  @override`,
@@ -276,39 +282,39 @@ function emitProviderClass(
     `  String get deadLetterDirectiveId => '${task.deadLetter.id}';`,
     ``,
     `  @override`,
-    `  NomosIntent handleOrder(String orderPayloadJson, {required HostClock now}) =>`,
-    `      handleOrderMap(decodeOrderPayload(orderPayloadJson), now: now);`,
+    `  NomosIntent handleObligation(String obligationPayloadJson, {required HostClock now}) =>`,
+    `      handleObligationMap(decodeObligationPayload(obligationPayloadJson), now: now);`,
     ``,
     `  @override`,
-    `  NomosIntent handleOrderMap(`,
-    `    Map<String, Object?> orderPayload, {`,
+    `  NomosIntent handleObligationMap(`,
+    `    Map<String, Object?> obligationPayload, {`,
     `    required HostClock now,`,
     `  }) {`,
-    `    final order = ${orderCls}.fromJson(orderPayload);`,
-    `    final outcome = handler(order);`,
+    `    final obligation = ${obligationCls}.fromJson(obligationPayload);`,
+    `    final outcome = handler(obligation);`,
     `    // ENCODE the outcome into the ordinary RECEIPT intent (reusing the peer-codegen Receipt`,
     `    // payload classes — same generated file). The Receipt addresses the SAME instance`,
-    `    // the Order created (keyed by requestId), so closesOrder == requestId by`,
+    `    // the Obligation created (keyed by requestId), so closesObligation == requestId by`,
     `    // construction in the engine's \`.plan()\` — terminal-once is the kernel's gate.`,
     `    return switch (outcome) {`,
     `      TaskSuccess<${resultCls}>(:final result) => ${completeCls}(`,
-    `          requestId: order.requestId,`,
+    `          requestId: obligation.requestId,`,
     `          resultRef: result.toResultRef(),`,
     `          completedAt: now(),`,
     `        ),`,
     `      TaskFailure<${resultCls}>(:final failureReason) => ${failCls}(`,
-    `          requestId: order.requestId,`,
+    `          requestId: obligation.requestId,`,
     `          failureReason: failureReason,`,
     `          failedAt: now(),`,
     `        ),`,
     `      TaskBlocked<${resultCls}>(:final blockedReason, :final nextAction) => ${blockCls}(`,
-    `          requestId: order.requestId,`,
+    `          requestId: obligation.requestId,`,
     `          blockedReason: blockedReason,`,
     `          blockedAt: now(),`,
     `          nextAction: nextAction,`,
     `        ),`,
     `      TaskDeadLetter<${resultCls}>(:final deadLetterReason) => ${deadLetterCls}(`,
-    `          requestId: order.requestId,`,
+    `          requestId: obligation.requestId,`,
     `          deadLetterReason: deadLetterReason,`,
     `          deadLetteredAt: now(),`,
     `        ),`,
@@ -319,20 +325,20 @@ function emitProviderClass(
 }
 
 /**
- * Emit the full provider SDK for ONE `impureCapability`: the typed Order/Result/Failure
+ * Emit the full provider SDK for ONE `impureCapability`: the typed Obligation/Result/Failure
  * classes + the handler typedef + the dispatcher. `enumDartTypes` is the SAME map the
- * domain's `collectEnums` produced (so an enum-typed order param references the
+ * domain's `collectEnums` produced (so an enum-typed obligation param references the
  * already-emitted domain enum — NO duplicate enum decl).
  */
 export function emitProviderTask(
   task: ImpureCapabilityDecl,
   enumDartTypes: Map<string, string>,
 ): string {
-  const base = taskBaseName(task.order.id);
-  const specs = introspectPayload(task.order.payloadSchema, enumDartTypes);
+  const base = taskBaseName(task.obligation.id);
+  const specs = introspectPayload(task.obligation.payloadSchema, enumDartTypes);
   return [
     `// ── provider SDK: ${base} (impureCapability '${task.aggregate.id}') ──`,
-    emitOrderClass(base, task.order.id, specs),
+    emitObligationClass(base, task.obligation.id, specs),
     ``,
     emitResultClasses(base, task.complete.id),
     ``,