@githolon/dsl 0.1.0

package/src/codegen_provider_dart.ts

@@ -0,0 +1,358 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * 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
+ * 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
+ * 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
+ * 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` /
+ *      `requestedBy` / `requestedAt` ⊕ the tenant params from the DSL), with a
+ *      `fromJson` decoding the incoming Order 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)`;
+ *   5. a generated `XProvider` dispatcher (`implements TaskProvider`): given the
+ *      registered typed handler, `handleOrder(orderJson, 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
+ *      ordinary `NomosIntent` → it ships through the SAME `dispatch` gate (ONE-WRITE-
+ *      PATH; the provider is a Nomos author, not a bypass).
+ *
+ * VENDOR-NEUTRAL: no lambda/worker/cloud-function nouns — the generated SDK is a pure
+ * typed decode/encode pair the host loop drives. TYPESAFE-TO-THE-BOUNDARY: no `dynamic`
+ * / `Map<String,dynamic>` / raw-JSON in the dev-facing handler API; types stop only at
+ * the JSON serde inside `fromJson` / the reused `toPayloadJson`.
+ *
+ * It REUSES the peer codegen's already-emitted Receipt payload classes (same file),
+ * so the Receipt the provider authors is byte-identical to the one the peer codegen
+ * already proved lowers correctly — the round-trip is closed by construction.
+ */
+import { z } from "zod";
+import {
+  cap,
+  introspectPayload,
+  toJsonExpr,
+  type PayloadFieldSpec,
+} from "./codegen_dart.js";
+
+/**
+ * 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
+ * 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.
+ */
+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 COMPLETE (success) Receipt directive: payload = {requestId, resultRef, completedAt}. */
+  readonly complete: { readonly id: string };
+  /** The FAIL (failure) Receipt directive: payload = {requestId, failureReason, failedAt}. */
+  readonly fail: { readonly id: string };
+  /** The BLOCKED Receipt directive: payload = {requestId, blockedReason, blockedAt, nextAction}. */
+  readonly block: { readonly id: string };
+  /** The DLQ Receipt directive: payload = {requestId, deadLetterReason, deadLetteredAt}. */
+  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
+ * them so the doc separates provenance from the tenant's request params. */
+const ORDER_ENVELOPE_FIELDS = new Set(["requestId", "requestedBy", "requestedAt"]);
+
+/** 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`
+ * → `TranscribeVoiceNote`). Pure + deterministic. */
+export function taskBaseName(orderDirectiveId: string): string {
+  const stripped = orderDirectiveId.replace(/^(create|order)/, "");
+  const base = stripped === "" ? orderDirectiveId : stripped;
+  return cap(base);
+}
+
+/** The reused peer-codegen Receipt payload class names (same generated file). */
+function completePayloadClass(completeDirectiveId: string): string {
+  return `${cap(completeDirectiveId)}Payload`;
+}
+function failPayloadClass(failDirectiveId: string): string {
+  return `${cap(failDirectiveId)}Payload`;
+}
+function blockPayloadClass(blockDirectiveId: string): string {
+  return `${cap(blockDirectiveId)}Payload`;
+}
+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)
+    ? ` // envelope provenance (framework)`
+    : ``;
+  return `  final ${s.dartType}${s.optional ? "?" : ""} ${s.name};${provenance}`;
+}
+
+/** Dart ctor PARAM for one Order field. */
+function orderCtorParam(s: PayloadFieldSpec): string {
+  return `    ${s.optional ? "" : "required "}this.${s.name},`;
+}
+
+/**
+ * Expression decoding ONE Order 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)`.
+ *   • strList — `(j['f'] as List).cast<String>()`.
+ *   • json    — the nested object/list verbatim (`Map<String,Object?>` / `List<Object?>`).
+ * 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 {
+  const raw = `j['${s.name}']`;
+  switch (s.toJson) {
+    case "scalar": {
+      // int reads tolerate a JSON number that decodes as double/int; cast via `as num`.
+      if (s.dartType === "int") {
+        return s.optional
+          ? `${raw} == null ? null : (${raw} as num).toInt()`
+          : `(${raw} as num).toInt()`;
+      }
+      if (s.dartType === "double") {
+        return s.optional
+          ? `${raw} == null ? null : (${raw} as num).toDouble()`
+          : `(${raw} as num).toDouble()`;
+      }
+      // String / bool.
+      return s.optional ? `${raw} as ${s.dartType}?` : `${raw} as ${s.dartType}`;
+    }
+    case "enum": {
+      return s.optional
+        ? `${raw} == null ? null : ${s.dartType}.fromWire(${raw} as String)`
+        : `${s.dartType}.fromWire(${raw} as String)`;
+    }
+    case "strList": {
+      return s.optional
+        ? `(${raw} as List<Object?>?)?.cast<String>()`
+        : `(${raw} as List<Object?>).cast<String>()`;
+    }
+    case "json": {
+      // A nested object → `Map<String,Object?>`; a `List<Object?>` payload (rare) stays
+      // a list. The Dart type drives the cast.
+      return s.optional ? `${raw} as ${s.dartType}?` : `${raw} as ${s.dartType}`;
+    }
+  }
+}
+
+/** Emit the typed `XOrder` class — the DECODED incoming Order. */
+function emitOrderClass(
+  base: string,
+  orderDirectiveId: string,
+  specs: PayloadFieldSpec[],
+): string {
+  const cls = `${base}Order`;
+  const fieldDecls = specs.map(orderFieldDecl).join("\n");
+  const ctorParams = specs.map(orderCtorParam).join("\n");
+  const fromJsonAssigns = specs
+    .map((s) => `      ${s.name}: ${orderFromJsonExpr(s)},`)
+    .join("\n");
+  return [
+    `/// The typed ORDER for the \`${orderDirectiveId}\` capability — what the provider`,
+    `/// RECEIVES. Carries the framework envelope provenance (requestId / requestedBy /`,
+    `/// requestedAt) ⊕ the tenant request params. Decoded from the incoming Order intent's`,
+    `/// payload JSON via [${cls}.fromJson]; the handler sees ONLY this typed value.`,
+    `class ${cls} {`,
+    fieldDecls,
+    ``,
+    `  const ${cls}({`,
+    ctorParams,
+    `  });`,
+    ``,
+    `  /// Decode an Order from the already-\`jsonDecode\`d payload map (the EXACT shape the`,
+    `  /// peer's \`${orderDirectiveId}\` \`toPayloadJson()\` produced). Reverse of the peer`,
+    `  /// encode — types stop here, at the JSON serde.`,
+    `  factory ${cls}.fromJson(Map<String, Object?> j) => ${cls}(`,
+    fromJsonAssigns,
+    `      );`,
+    `}`,
+  ].join("\n");
+}
+
+/** Emit the typed `XResult` (success) + `XFailure` classes the handler returns. */
+function emitResultClasses(base: string, completeDirectiveId: string): string {
+  const resultCls = `${base}Result`;
+  const failureCls = `${base}Failure`;
+  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\`).`,
+    `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});`,
+    ``,
+    `  @override`,
+    `  String toResultRef() => resultRef;`,
+    `}`,
+    ``,
+    `/// 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.`,
+    `class ${failureCls} {`,
+    `  final String failureReason;`,
+    `  const ${failureCls}({required this.failureReason});`,
+    `}`,
+  ].join("\n");
+}
+
+/** Emit the handler typedef + the generated `XProvider` dispatcher. */
+function emitProviderClass(
+  task: ImpureCapabilityDecl,
+  base: string,
+): string {
+  const orderCls = `${base}Order`;
+  const resultCls = `${base}Result`;
+  const handlerTypedef = `${base}Handler`;
+  const providerCls = `${base}Provider`;
+  const completeCls = completePayloadClass(task.complete.id);
+  const failCls = failPayloadClass(task.fail.id);
+  const blockCls = blockPayloadClass(task.block.id);
+  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`,
+    `/// [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);`,
+    ``,
+    `/// 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`,
+    `/// 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}> {`,
+    `  /// The dev's typed handler.`,
+    `  final ${handlerTypedef} handler;`,
+    `  const ${providerCls}(this.handler);`,
+    ``,
+    `  @override`,
+    `  String get orderDirectiveId => '${task.order.id}';`,
+    `  @override`,
+    `  String get completeDirectiveId => '${task.complete.id}';`,
+    `  @override`,
+    `  String get failDirectiveId => '${task.fail.id}';`,
+    `  @override`,
+    `  String get blockDirectiveId => '${task.block.id}';`,
+    `  @override`,
+    `  String get deadLetterDirectiveId => '${task.deadLetter.id}';`,
+    ``,
+    `  @override`,
+    `  NomosIntent handleOrder(String orderPayloadJson, {required HostClock now}) =>`,
+    `      handleOrderMap(decodeOrderPayload(orderPayloadJson), now: now);`,
+    ``,
+    `  @override`,
+    `  NomosIntent handleOrderMap(`,
+    `    Map<String, Object?> orderPayload, {`,
+    `    required HostClock now,`,
+    `  }) {`,
+    `    final order = ${orderCls}.fromJson(orderPayload);`,
+    `    final outcome = handler(order);`,
+    `    // 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`,
+    `    // construction in the engine's \`.plan()\` — terminal-once is the kernel's gate.`,
+    `    return switch (outcome) {`,
+    `      TaskSuccess<${resultCls}>(:final result) => ${completeCls}(`,
+    `          requestId: order.requestId,`,
+    `          resultRef: result.toResultRef(),`,
+    `          completedAt: now(),`,
+    `        ),`,
+    `      TaskFailure<${resultCls}>(:final failureReason) => ${failCls}(`,
+    `          requestId: order.requestId,`,
+    `          failureReason: failureReason,`,
+    `          failedAt: now(),`,
+    `        ),`,
+    `      TaskBlocked<${resultCls}>(:final blockedReason, :final nextAction) => ${blockCls}(`,
+    `          requestId: order.requestId,`,
+    `          blockedReason: blockedReason,`,
+    `          blockedAt: now(),`,
+    `          nextAction: nextAction,`,
+    `        ),`,
+    `      TaskDeadLetter<${resultCls}>(:final deadLetterReason) => ${deadLetterCls}(`,
+    `          requestId: order.requestId,`,
+    `          deadLetterReason: deadLetterReason,`,
+    `          deadLetteredAt: now(),`,
+    `        ),`,
+    `    };`,
+    `  }`,
+    `}`,
+  ].join("\n");
+}
+
+/**
+ * Emit the full provider SDK for ONE `impureCapability`: the typed Order/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
+ * 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);
+  return [
+    `// ── provider SDK: ${base} (impureCapability '${task.aggregate.id}') ──`,
+    emitOrderClass(base, task.order.id, specs),
+    ``,
+    emitResultClasses(base, task.complete.id),
+    ``,
+    emitProviderClass(task, base),
+  ].join("\n");
+}
+
+/**
+ * Emit the provider SDK block for a domain's `impureCapabilities`. Returns `""` when the
+ * domain declares none (ADDITIVE + omit-when-empty — a domain without impure capabilities is
+ * byte-identical to before this block existed). `toJsonExpr` is re-exported only to keep
+ * the peer/provider codegen symmetric in one module surface; it is not used here
+ * directly (the Receipt encode reuses the peer payload classes), so reference it to
+ * avoid an unused-import lint while documenting the symmetry.
+ */
+export function emitProviderSdk(
+  tasks: readonly ImpureCapabilityDecl[],
+  enumDartTypes: Map<string, string>,
+): string {
+  if (tasks.length === 0) return "";
+  void toJsonExpr; // symmetry marker (see doc); the encode reuses the peer payload classes.
+  return tasks.map((t) => emitProviderTask(t, enumDartTypes)).join("\n\n");
+}