@githolon/dsl 0.102.4 → 0.103.0

package/src/codegen_dart.ts

@@ -29,12 +29,12 @@
  * generated, so they stay reproducible from the domain definitions.
  */
 import { z } from "zod";
-import { voMetaOf, collectPayloadValueObjectDescriptors, idOfMetaOf, idOfTargetKindOf, brandedIdMetaOf, NOMOS_UNIT_BRAND } from "./value_object.js";
+import { voMetaOf, collectPayloadValueObjectDescriptors, idOfMetaOf, idOfTargetKindOf, versionedRefOfMetaOf, brandedIdMetaOf, NOMOS_UNIT_BRAND } from "./value_object.js";
 import { recursiveTypeBaseName, zodUnwrapLazy } from "./zod_lazy.js";
 import type { AggregateHandle } from "./aggregate.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import type { RelationTypeDecl } from "./relation_schema.js";
-import type { Field, FieldKind, ValueObjectDescriptor, ValueObjectFieldDescriptor } from "./fields.js";
+import { isSha256DigestSchema, type Field, type FieldKind, type ValueObjectDescriptor, type ValueObjectFieldDescriptor } from "./fields.js";
 import { admitsNull, nullMetaOf, nullDocLine } from "./null_meta.js";
 import type { Directive } from "./directive.js";
 import { executeDirectiveToIntent } from "./wire_encode.js";
@@ -84,6 +84,7 @@ export type ToJsonWrap =
   | "voList" // a list of value objects — emit `.map((e) => e.toJson()).toList()`.
   | "wrapped" // a standalone branded-id or unit extension type — emit `.value`.
   | "ref" // an aggregate-specific NomosRef<T> — emit its `.id` wire scalar.
+  | "versionedRef" // a publication pin + stable series — emit the atomic address pair.
   | "recipient"; // a framework-created Recipient<User> — emit its private delivery address.
 
 export interface PayloadFieldSpec {
@@ -91,10 +92,20 @@ export interface PayloadFieldSpec {
   dartType: string;
   /** Aggregate wire type when this field is a NomosRef<T>. */
   referenceType?: string;
+  /** Versioned publication/series metadata for payload decode and framework codegen. */
+  versionedRefTarget?: string;
+  versionedRefSeries?: string;
+  versionedRefCurrentField?: string;
+  versionedRefTargetInput?: string;
+  versionedRefSeriesInput?: string;
+  versionedRefTargetWireType?: string;
+  versionedRefSeriesWireType?: string;
   /** for enums: the Dart enum type name + raw values. */
   enumValues?: string[];
   /** how this field serialises into `nmsInternalToPayloadJson()`. */
   toJson: ToJsonWrap;
+  /** Wire scalar under a nominal wrapper. Keeps string semantics distinct from numeric units. */
+  wrappedScalarKind?: "string" | "number";
   /**
    * Whether the payload field is OPTIONAL (Zod `.optional()`/`.default()`). Optional
    * fields are nullable in Dart and OMITTED from `nmsInternalToPayloadJson()` when null — so the
@@ -118,6 +129,60 @@ export interface DartBusinessRecordInput {
   readonly dartType: string;
 }
 
+/**
+ * A payload NomosRef whose workspace locator is carried by the sibling field of
+ * a declared foreignRef output. The public action accepts the one atomic typed
+ * reference; codegen derives both wire fields so tenant code cannot split them.
+ */
+export interface DartForeignReferenceInput {
+  readonly idField: string;
+  readonly workspaceField: string;
+  readonly optional: boolean;
+}
+
+export function dartForeignReferenceInputs(
+  directive: AnyDirective,
+  aggregates: readonly AggregateHandle[],
+): DartForeignReferenceInput[] {
+  const specs = introspectPayload(directive.payloadSchema as z.ZodTypeAny, new Map());
+  const payloadNames = new Set(specs.map((spec) => spec.name));
+  const recordInputIds = new Set((directive.businessRecordInputs ?? []).map((input) => input.field));
+  const outputIds = new Set([
+    directive.aggregateId,
+    ...(directive.secondaryOutputs ?? []).map((output) => output.aggregateId),
+  ]);
+  const outputs = aggregates.filter((aggregate) => outputIds.has(aggregate.id));
+
+  return specs.flatMap((spec) => {
+    if (spec.toJson !== "ref" || recordInputIds.has(spec.name)) return [];
+    const matches = outputs.flatMap((aggregate) => {
+      const field = aggregate.fields[spec.name] as Field | undefined;
+      if (
+        field?.kind !== "ref" ||
+        field.foreignRef === undefined ||
+        (spec.referenceType !== undefined && field.foreignRef.targetAggregateId !== spec.referenceType)
+      ) {
+        return [];
+      }
+      return [field.foreignRef.workspaceField];
+    });
+    const workspaceFields = [...new Set(matches)];
+    if (workspaceFields.length === 0) return [];
+    if (workspaceFields.length > 1) {
+      throw new Error(
+        `${directive.id}: foreign reference payload '${spec.name}' maps to more than one workspace field`,
+      );
+    }
+    const workspaceField = workspaceFields[0]!;
+    if (!payloadNames.has(workspaceField)) {
+      throw new Error(
+        `${directive.id}: foreign reference payload '${spec.name}' must carry its declared locator '${workspaceField}'`,
+      );
+    }
+    return [{ idField: spec.name, workspaceField, optional: spec.optional }];
+  });
+}
+
 /**
  * Resolve `.fromRecord(field)` against the directive's target aggregate. The
  * aggregate owns the foreign-reference pairing, so authors name only the
@@ -378,6 +443,31 @@ function introspectField(
   enumDartTypes: Map<string, string>,
   lazyNames?: Map<z.ZodTypeAny, string>,
 ): Omit<PayloadFieldSpec, "optional"> {
+  const versioned = versionedRefOfMetaOf(zt);
+  if (versioned !== undefined) {
+    const target = versioned.targetKind === "contract"
+      ? contractTypeName(versioned.targetAggregateType)
+      : concreteClassName(versioned.targetAggregateType);
+    const series = versioned.seriesKind === "contract"
+      ? contractTypeName(versioned.seriesAggregateType)
+      : concreteClassName(versioned.seriesAggregateType);
+    return {
+      name,
+      dartType: `VersionedNomosRef<${target}, ${series}>`,
+      toJson: "versionedRef",
+      versionedRefTarget: target,
+      versionedRefSeries: series,
+      versionedRefCurrentField: versioned.currentField,
+      // The pinned version normally comes from the stable series' compiled
+      // current pointer, so it already carries the public contract type.
+      versionedRefTargetInput: target,
+      versionedRefSeriesInput: versioned.seriesKind === "contract"
+        ? concreteClassName(versioned.seriesAggregateType)
+        : series,
+      versionedRefTargetWireType: versioned.targetAggregateType,
+      versionedRefSeriesWireType: versioned.seriesAggregateType,
+    };
+  }
   if (recipientMetaOf(zt) !== undefined) {
     return { name, dartType: "Recipient<User>", toJson: "recipient" };
   }
@@ -425,10 +515,13 @@ function introspectField(
           toJson: "ref",
         };
       }
+      if (isSha256DigestSchema(zt)) {
+        return { name, dartType: "Sha256Digest", toJson: "wrapped", wrappedScalarKind: "string" };
+      }
       // brandedId("SiteId"): a standalone nominal string → the generated extension type.
       const brand = brandedIdMetaOf(zt);
       if (brand !== undefined) {
-        return { name, dartType: brand, toJson: "wrapped" };
+        return { name, dartType: brand, toJson: "wrapped", wrappedScalarKind: "string" };
       }
       return { name, dartType: "String", toJson: "scalar" };
     }
@@ -442,7 +535,7 @@ function introspectField(
       {
         const unitName = (zt as unknown as Record<symbol, unknown>)[NOMOS_UNIT_BRAND];
         if (typeof unitName === "string") {
-          return { name, dartType: unitName, toJson: "wrapped" };
+          return { name, dartType: unitName, toJson: "wrapped", wrappedScalarKind: "number" };
         }
       }
       return {
@@ -531,6 +624,8 @@ interface AggFieldSpec {
   wireName: string;
   kind: MaterializedFieldKind;
   dartType: string;
+  /** A canonical semantic string wrapper whose wire representation remains String. */
+  semanticString?: "sha256";
   enumValues?: string[];
   /** For an own-id string field represented as `NomosRef<TAggregate>`. */
   valueClass?: string;
@@ -561,6 +656,16 @@ interface AggFieldSpec {
    * WORKSPACE id (the locator's `workspace`, dynamic per row). `undefined` for a non-foreignRef field.
    */
   foreignRefWorkspaceField?: string;
+  /** A first-class atomic custody address (`t.nomosRef`). */
+  nomosRefTarget?: string;
+  /** The target aggregate's domain-qualified wire type. */
+  nomosRefAggregateType?: string;
+  /** A publication pin + stable series (`t.versionedForeignRef`). */
+  versionedRefTarget?: string;
+  /** The stable series' generated Dart class. */
+  versionedRefSeries?: string;
+  /** Compiled field on the series which carries its current publication. */
+  versionedRefCurrentField?: string;
   /**
    * Whether the field is OPTIONAL on a folded aggregate — derived from the DSL field
    * schema (GAP 1). A `set`/`map` is a COLLECTION: it is ALWAYS empty-defaultable
@@ -737,6 +842,9 @@ function readKeyParamSpec(
   if (fieldSpec.kind === "int") {
     return { dartType: "int", valueExpr: paramName };
   }
+  if (fieldSpec.semanticString === "sha256") {
+    return { dartType: "Sha256Digest", valueExpr: `${paramName}.value` };
+  }
   return { dartType: "String", valueExpr: paramName };
 }
 
@@ -845,8 +953,13 @@ function aggFieldSpec(
         name,
         wireName,
         kind: field.kind,
-        dartType: valueClass === undefined ? "String" : `NomosRef<${valueClass}>`,
+        dartType: valueClass === undefined
+          ? isSha256DigestSchema(field.zod as z.ZodTypeAny) ? "Sha256Digest" : "String"
+          : `NomosRef<${valueClass}>`,
         optional,
+        ...(valueClass === undefined && isSha256DigestSchema(field.zod as z.ZodTypeAny)
+          ? { semanticString: "sha256" as const }
+          : {}),
         ...(valueClass !== undefined && valueAggregateType !== undefined
           ? { valueClass, valueAggregateType }
           : {}),
@@ -876,6 +989,40 @@ function aggFieldSpec(
         ...(field.jsonShape !== undefined ? { jsonShape: field.jsonShape } : {}),
       };
     case "ref": {
+      if (field.versionedForeignRef !== undefined) {
+        const version = field.versionedForeignRef.targetIsContract === true
+          ? contractTypeName(field.versionedForeignRef.targetAggregateId)
+          : refIdClassForAggregate(field.versionedForeignRef.targetAggregateId);
+        const series = field.versionedForeignRef.seriesIsContract === true
+          ? contractTypeName(field.versionedForeignRef.seriesAggregateId)
+          : refIdClassForAggregate(field.versionedForeignRef.seriesAggregateId);
+        return {
+          name,
+          wireName,
+          kind: field.kind,
+          dartType: `VersionedNomosRef<${version}, ${series}>`,
+          optional,
+          versionedRefTarget: version,
+          versionedRefSeries: series,
+          versionedRefCurrentField: field.versionedForeignRef.currentField,
+        };
+      }
+      if (field.nomosRef !== undefined) {
+        const target = field.nomosRef.targetIsContract === true
+          ? contractTypeName(field.nomosRef.targetAggregateId)
+          : refIdClassForAggregate(field.nomosRef.targetAggregateId);
+        return {
+          name,
+          wireName,
+          kind: field.kind,
+          dartType: `NomosRef<${target}>`,
+          optional,
+          nomosRefTarget: target,
+          nomosRefAggregateType: aggregateWireTypeForAggregate(
+            field.nomosRef.targetAggregateId,
+          ),
+        };
+      }
       // A `t.foreignRef` field is a TYPED CROSS-WORKSPACE LOCATOR (not an atomic FK): surface it as
       // `ForeignRef<Target>` (the shared `nomos_types` runtime type) — the raw stored id + the sibling
       // workspace field give the app `resolve`/`watch`/`attest` on demand, without cloning the other holon.
@@ -1708,7 +1855,7 @@ function dartTypeOfVoField(f: ValueObjectFieldDescriptor, voName: string, fieldN
     case "string":
       return f.idOf !== undefined
         ? `NomosRef<${f.idOfContract === true ? contractTypeName(f.idOf) : concreteClassName(f.idOf)}>`
-        : f.brand ?? "String"; // a brandedId(...) → the generated extension-type wrapper
+        : f.digest === "sha256" ? "Sha256Digest" : f.brand ?? "String";
     case "number":
       // a UNIT-tagged number is the generated zero-cost extension type; `.int()` is Dart int.
       if (f.unit !== undefined) return f.unit;
@@ -1745,6 +1892,7 @@ function voFromExpr(
         const target = f.idOfContract === true ? contractTypeName(f.idOf) : concreteClassName(f.idOf);
         return `NmsInternalNomosRefs.create<${target}>(workspace: '', type: '${f.idOf}', id: ${expr} as String)`;
       }
+      if (f.digest === "sha256") return `Sha256Digest(${expr} as String)`;
       return f.brand !== undefined ? `${f.brand}(${expr} as String)` : `${expr} as String`;
     case "enum":
       // TOLERANT typed decode — an unknown wire value becomes the sentinel case.
@@ -1777,6 +1925,7 @@ function voToJsonExpr(f: ValueObjectFieldDescriptor, expr: string, depth = 0): s
       return f.unit !== undefined ? `${expr}.value` : expr;
     case "string":
       if (f.idOf !== undefined) return `NmsInternalNomosRefs.id(${expr})`;
+      if (f.digest === "sha256") return `${expr}.value`;
       return f.brand !== undefined ? `${expr}.value` : expr; // a brandedId extension type → its wire string
     case "boolean":
     case "literal":
@@ -2759,6 +2908,26 @@ function foreignRefExpr(s: AggFieldSpec, aggregate: string): string {
     : build(idReader);
 }
 
+function atomicNomosRefExpr(s: AggFieldSpec): string {
+  const target = s.nomosRefTarget as string;
+  const raw = `data['${s.wireName}']`;
+  return s.optional
+    ? `() { final v = ${raw}; return v == null ? null : NmsInternalNomosRefs.fromJson<${target}>(v); }()`
+    : `NmsInternalNomosRefs.fromJson<${target}>(${raw})`;
+}
+
+function versionedNomosRefExpr(s: AggFieldSpec): string {
+  const version = s.versionedRefTarget as string;
+  const series = s.versionedRefSeries as string;
+  const currentField = JSON.stringify(s.versionedRefCurrentField);
+  const build = (value: string): string =>
+    `() { final m = (${value} as Map).cast<String, Object?>(); return NmsInternalVersionedNomosRefs.create<${version}, ${series}>(pinned: NmsInternalNomosRefs.fromJson<${version}>(m['pinned']), series: NmsInternalNomosRefs.fromJson<${series}>(m['series']), currentField: ${currentField}); }()`;
+  const raw = `data['${s.wireName}']`;
+  return s.optional
+    ? `() { final v = ${raw}; return v == null ? null : ${build("v")}; }()`
+    : build(raw);
+}
+
 function parseField(s: AggFieldSpec, aggregate: string): string {
   // A `.optional()` scalar reads through the `…OrNull` tolerant reader (returns null
   // when the flat `data` lacks it — a freshly-folded aggregate need not have folded
@@ -2767,6 +2936,8 @@ function parseField(s: AggFieldSpec, aggregate: string): string {
   const opt = s.optional;
   switch (s.kind) {
     case "ref": {
+      if (s.versionedRefTarget !== undefined) return versionedNomosRefExpr(s);
+      if (s.nomosRefTarget !== undefined) return atomicNomosRefExpr(s);
       // A `t.foreignRef` field decodes to the shared `ForeignRef<Target>` locator (raw id + sibling
       // workspace field + the target `fromJson`), not a same-workspace NomosRef.
       if (s.foreignRefTarget !== undefined) return foreignRefExpr(s, aggregate);
@@ -2794,9 +2965,17 @@ function parseField(s: AggFieldSpec, aggregate: string): string {
           ? `() { final v = ${reader}; return v == null ? null : NmsInternalNomosRefs.create<${s.valueClass}>(workspace: _location, type: '${s.valueAggregateType}', id: v); }()`
           : `NmsInternalNomosRefs.create<${s.valueClass}>(workspace: _location, type: '${s.valueAggregateType}', id: ${reader})`;
       }
-      return opt
-        ? `readStrOrNull(data, '${s.wireName}')`
-        : `readStr(data, '${aggregate}', '${s.wireName}')`;
+      {
+        const reader = opt
+          ? `readStrOrNull(data, '${s.wireName}')`
+          : `readStr(data, '${aggregate}', '${s.wireName}')`;
+        if (s.semanticString === "sha256") {
+          return opt
+            ? `() { final v = ${reader}; return v == null ? null : Sha256Digest(v); }()`
+            : `Sha256Digest(${reader})`;
+        }
+        return reader;
+      }
     case "json":
       // A NAMED VALUE OBJECT reads the projection's decoded object and wraps it in its
       // generated class (the EvidenceRef pattern). A plain `json`-kind field is typed
@@ -2855,6 +3034,15 @@ function parseField(s: AggFieldSpec, aggregate: string): string {
 function slotDecodeCallback(s: AggFieldSpec, mode: "aggregate" | "readModel"): string {
   switch (s.kind) {
     case "ref":
+      if (s.versionedRefTarget !== undefined) {
+        const version = s.versionedRefTarget;
+        const series = s.versionedRefSeries as string;
+        const currentField = JSON.stringify(s.versionedRefCurrentField);
+        return `(v) { final m = (v as Map).cast<String, Object?>(); return NmsInternalVersionedNomosRefs.create<${version}, ${series}>(pinned: NmsInternalNomosRefs.fromJson<${version}>(m['pinned']), series: NmsInternalNomosRefs.fromJson<${series}>(m['series']), currentField: ${currentField}); }`;
+      }
+      if (s.nomosRefTarget !== undefined) {
+        return `(v) => NmsInternalNomosRefs.fromJson<${s.nomosRefTarget}>(v)`;
+      }
       // A null-admitting `t.foreignRef` (exotic): the sibling workspace field is not reachable from this
       // single leaf, so the locator carries the raw id with an empty workspace (resolves to not-found until
       // read through the normal field path). A plain ref keeps its typed-id decode.
@@ -2867,8 +3055,11 @@ function slotDecodeCallback(s: AggFieldSpec, mode: "aggregate" | "readModel"): s
         : `(v) => v as String`;
     case "position":
     case "string":
-      return s.valueClass !== undefined
-        ? `(v) => NmsInternalNomosRefs.create<${s.valueClass}>(workspace: _location, type: '${s.valueAggregateType}', id: v as String)`
+      if (s.valueClass !== undefined) {
+        return `(v) => NmsInternalNomosRefs.create<${s.valueClass}>(workspace: _location, type: '${s.valueAggregateType}', id: v as String)`;
+      }
+      return s.semanticString === "sha256"
+        ? `(v) => Sha256Digest(v as String)`
         : `(v) => v as String`;
     case "json":
       if (s.voClass !== undefined) {
@@ -2919,6 +3110,7 @@ export function readModelClassName(aggregateType: string): string {
 function readModelDartType(s: AggFieldSpec): string {
   switch (s.kind) {
     case "ref":
+      if (s.versionedRefTarget !== undefined || s.nomosRefTarget !== undefined) return s.dartType;
       // A `t.foreignRef` field surfaces as the typed cross-workspace `ForeignRef<Target>` locator; a plain
       // same-workspace ref stays `NomosRef<Target>` (or a bare String when the target is unknown).
       if (s.foreignRefTarget !== undefined) return `ForeignRef<${s.foreignRefTarget}>`;
@@ -2936,7 +3128,7 @@ function readModelDartType(s: AggFieldSpec): string {
     // so these labels are unreachable at runtime — present for FieldKind exhaustiveness.
     case "position":
     case "string":
-      return s.valueClass === undefined ? "String" : `NomosRef<${s.valueClass}>`;
+      return s.valueClass === undefined ? s.dartType : `NomosRef<${s.valueClass}>`;
     case "counter":
     case "int":
       return "int";
@@ -2984,6 +3176,8 @@ function parseReadModelField(s: AggFieldSpec, aggregate: string): string {
   const opt = s.optional;
   switch (s.kind) {
     case "ref": {
+      if (s.versionedRefTarget !== undefined) return versionedNomosRefExpr(s);
+      if (s.nomosRefTarget !== undefined) return atomicNomosRefExpr(s);
       // A `t.foreignRef` field decodes to the shared `ForeignRef<Target>` locator (same as the aggregate
       // class); a plain same-workspace ref stays `NomosRef<Target>`.
       if (s.foreignRefTarget !== undefined) return foreignRefExpr(s, aggregate);
@@ -3005,9 +3199,17 @@ function parseReadModelField(s: AggFieldSpec, aggregate: string): string {
           ? `() { final v = ${reader}; return v == null ? null : NmsInternalNomosRefs.create<${s.valueClass}>(workspace: _location, type: '${s.valueAggregateType}', id: v); }()`
           : `NmsInternalNomosRefs.create<${s.valueClass}>(workspace: _location, type: '${s.valueAggregateType}', id: ${reader})`;
       }
-      return opt
-        ? `readStrOrNull(data, '${s.wireName}')`
-        : `readStr(data, '${aggregate}', '${s.wireName}')`;
+      {
+        const reader = opt
+          ? `readStrOrNull(data, '${s.wireName}')`
+          : `readStr(data, '${aggregate}', '${s.wireName}')`;
+        if (s.semanticString === "sha256") {
+          return opt
+            ? `() { final v = ${reader}; return v == null ? null : Sha256Digest(v); }()`
+            : `Sha256Digest(${reader})`;
+        }
+        return reader;
+      }
     case "json":
       // An OBJECT-asserted leaf (`t.jsonObject()`, e.g. `location`): the read engine has
       // decoded the stored JSON into a structured object — surface it as a STRICT
@@ -3216,12 +3418,21 @@ function emitDirective(
   const className = dartActionInputClassName(d);
   const specs = introspectPayload(d.payloadSchema as z.ZodTypeAny, enumDartTypes, lazyNames);
   const recordInputs = dartBusinessRecordInputs(d, aggregates);
+  const foreignReferenceInputs = dartForeignReferenceInputs(d, aggregates);
+  const foreignReferenceIds = new Set(foreignReferenceInputs.map((input) => input.idField));
   const principalField = d.businessPrincipalField;
   const derivedFields = new Set([
     ...recordInputs.flatMap((input) => [input.idField, input.workspaceField]),
+    ...foreignReferenceInputs.map((input) => input.workspaceField),
     ...(principalField === undefined ? [] : [principalField]),
   ]);
   const publicSpecs = specs.filter((spec) => !derivedFields.has(spec.name));
+  // Optional first-class relationships are OPTIONAL on the wire but REQUIRED
+  // choices at the application boundary. A plain nullable constructor argument
+  // makes an accidentally forgotten relationship indistinguishable from a
+  // deliberate omission. The generated sum type keeps those meanings apart.
+  const isOptionalReferenceChoice = (spec: PayloadFieldSpec): boolean =>
+    spec.optional && spec.toJson === "ref";
   const internalPayloadArguments = [
     ...(principalField === undefined ? [] : ["required String nmsInternalPrincipal"]),
     ...(recordInputs.length === 0
@@ -3242,6 +3453,8 @@ function emitDirective(
     .map((s) =>
       s.nullAdmits === true
         ? `  final NomosSlot<${stripNullable(s.dartType)}> ${s.name};`
+        : isOptionalReferenceChoice(s)
+          ? `  final NomosOptionalRef<${s.dartType.replace(/^NomosRef<(.*)>$/, "$1")}> ${s.name};`
         : `  final ${s.dartType}${s.optional ? "?" : ""} ${s.name};`,
     ),
     ...recordInputs.map((input) => `  final ${input.dartType} ${input.argument};`),
@@ -3253,6 +3466,8 @@ function emitDirective(
       // an optional field defaults to null; a required field is `required`.
       s.nullAdmits === true
         ? `    this.${s.name} = const NomosSlot.omitted(),`
+        : isOptionalReferenceChoice(s)
+          ? `    required this.${s.name},`
         : `    ${s.optional ? "" : "required "}this.${s.name},`,
     ),
     ...recordInputs.map((input) => `    required this.${input.argument},`),
@@ -3270,10 +3485,20 @@ function emitDirective(
   // fields are written only when present (mirrors the engine's Zod: ops are emitted
   // only for present fields).
   const requiredEntries = specs
-    .filter((s) => !derivedFields.has(s.name) && !s.optional && s.nullAdmits !== true)
+    .filter((s) =>
+      !derivedFields.has(s.name) &&
+      !foreignReferenceIds.has(s.name) &&
+      !s.optional &&
+      s.nullAdmits !== true
+    )
     .map((s) => `    '${s.name}': ${toJsonExpr(s, s.name)},`);
   const optionalLines = specs
-    .filter((s) => !derivedFields.has(s.name) && s.optional && s.nullAdmits !== true)
+    .filter((s) =>
+      !derivedFields.has(s.name) &&
+      s.optional &&
+      s.nullAdmits !== true &&
+      !isOptionalReferenceChoice(s)
+    )
     .map(
       (s) =>
         `    if (${s.name} != null) '${s.name}': ${toJsonExpr(s, `${s.name}!`)},`,
@@ -3284,7 +3509,57 @@ function emitDirective(
   const slotWriteLines = slotSpecs.map(
     (s) => `    ${s.name}.writeTo(data, '${s.name}', (v) => ${toJsonExpr(s, "v")});`,
   );
-  const hasSlots = slotSpecs.length > 0;
+  const optionalReferenceSpecs = specs.filter(
+    (s) =>
+      !derivedFields.has(s.name) &&
+      !foreignReferenceIds.has(s.name) &&
+      isOptionalReferenceChoice(s),
+  );
+  const optionalReferenceWriteLines = optionalReferenceSpecs.map(
+    (s) => `    ${s.name}.writeTo(data, '${s.name}', (reference) => NmsInternalNomosRefs.id(reference));`,
+  );
+  const requiredForeignReferenceInputs = foreignReferenceInputs.filter((input) => !input.optional);
+  const requiredWorkspaceSources = new Map<string, DartForeignReferenceInput>();
+  const requiredForeignReferenceEntries = requiredForeignReferenceInputs.flatMap((input) => {
+    const first = requiredWorkspaceSources.get(input.workspaceField);
+    if (first === undefined) requiredWorkspaceSources.set(input.workspaceField, input);
+    return [
+      ...(first === undefined
+        ? [`    '${input.workspaceField}': NmsInternalNomosRefs.workspace(${input.idField}),`]
+        : []),
+      `    '${input.idField}': NmsInternalNomosRefs.id(${input.idField}),`,
+    ];
+  });
+  const requiredForeignReferenceValidationLines = requiredForeignReferenceInputs.flatMap((input) => {
+    const first = requiredWorkspaceSources.get(input.workspaceField)!;
+    if (first.idField === input.idField) return [];
+    return [
+      `    if (NmsInternalNomosRefs.workspace(${input.idField}) != NmsInternalNomosRefs.workspace(${first.idField})) {`,
+      `      throw ArgumentError('Foreign references for ${input.workspaceField} must belong to the same workspace.');`,
+      `    }`,
+    ];
+  });
+  const optionalForeignReferenceWriteLines = foreignReferenceInputs
+    .filter((input) => input.optional)
+    .flatMap((input) => [
+      `    ${input.idField}.when(`,
+      `      absent: () {},`,
+      `      present: (reference) {`,
+      `        final workspace = NmsInternalNomosRefs.workspace(reference);`,
+      `        final existingWorkspace = data['${input.workspaceField}'];`,
+      `        if (existingWorkspace != null && existingWorkspace != workspace) {`,
+      `          throw ArgumentError('Foreign references for ${input.workspaceField} must belong to the same workspace.');`,
+      `        }`,
+      `        data['${input.workspaceField}'] = workspace;`,
+      `        data['${input.idField}'] = NmsInternalNomosRefs.id(reference);`,
+      `      },`,
+      `    );`,
+    ]);
+  const hasPostWrites =
+    slotSpecs.length > 0 ||
+    optionalReferenceSpecs.length > 0 ||
+    requiredForeignReferenceValidationLines.length > 0 ||
+    optionalForeignReferenceWriteLines.length > 0;
 
   const docFirst = directiveDoc(d);
 
@@ -3302,11 +3577,12 @@ function emitDirective(
     ``,
     `  /// Nomos implementation seam used only by the generated application package.`,
     `  /// Tenant code should pass this object to the generated domain application instead.`,
-    ...(hasSlots
+    ...(hasPostWrites
       ? [
           `  Map<String, Object?> nmsInternalToPayloadJson(${internalPayloadSignature}) {`,
           `    final data = <String, Object?>{`,
           ...requiredEntries,
+          ...requiredForeignReferenceEntries,
           ...optionalLines,
           ...(principalField === undefined ? [] : [`      '${principalField}': nmsInternalPrincipal,`]),
           ...recordInputs.flatMap((input) => [
@@ -3314,13 +3590,17 @@ function emitDirective(
             `      '${input.idField}': nmsInternalIdOf(${input.argument}),`,
           ]),
           `    };`,
+          ...requiredForeignReferenceValidationLines,
           ...slotWriteLines,
+          ...optionalReferenceWriteLines,
+          ...optionalForeignReferenceWriteLines,
           `    return data;`,
           `  }`,
         ]
       : [
           `  Map<String, Object?> nmsInternalToPayloadJson(${internalPayloadSignature}) => <String, Object?>{`,
           ...requiredEntries,
+          ...requiredForeignReferenceEntries,
           ...optionalLines,
           ...(principalField === undefined ? [] : [`    '${principalField}': nmsInternalPrincipal,`]),
           ...recordInputs.flatMap((input) => [
@@ -3350,6 +3630,8 @@ export function toJsonExpr(spec: PayloadFieldSpec, accessor: string): string {
       return `${accessor}.value`;
     case "ref":
       return `NmsInternalNomosRefs.id(${accessor})`;
+    case "versionedRef":
+      return `{'pinned': NmsInternalNomosRefs.toJson(${accessor}.pinned), 'series': NmsInternalNomosRefs.toJson(${accessor}.series)}`;
     case "recipient":
       return `NmsInternalRecipients.address(${accessor})`;
   }
@@ -3413,6 +3695,7 @@ export function synthesizeRecursivePayloadTypes(
     }
     switch (zodTypeName(zt)) {
       case "ZodString": {
+        if (isSha256DigestSchema(zt)) return { type: "string", digest: "sha256" };
         const b = brandedIdMetaOf(zt);
         if (b !== undefined) return { type: "string", brand: b };
         const idAgg = idOfMetaOf(zt);
@@ -4026,7 +4309,7 @@ function buildProbePayload(
       zt = zodInnerType(zt);
     }
     const sentinel = fieldBySentinel.get(name);
-    out[name] = sentinel !== undefined && zodTypeName(zt) === "ZodString"
+    out[name] = sentinel !== undefined && zodTypeName(zt) === "ZodString" && !isSha256DigestSchema(zt)
       ? sentinel
       : sampleFromZod(zt);
   }
@@ -4041,7 +4324,7 @@ function sampleFromZod(zt: z.ZodTypeAny): unknown {
   }
   switch (zodTypeName(t)) {
     case "ZodString":
-      return "x";
+      return isSha256DigestSchema(t) ? "0".repeat(64) : "x";
     case "ZodNumber":
       return 1;
     case "ZodBoolean":
@@ -4506,7 +4789,7 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
       try {
         for (const spec of introspectPayload(schema as z.ZodTypeAny, new Map())) {
           // A wrapped spec whose brand a VO descriptor already registered is a brandedId, not a unit.
-          if (spec.toJson === "wrapped" && !spec.dartType.endsWith("Id") && !brandNames.has(spec.dartType)) {
+          if (spec.toJson === "wrapped" && spec.wrappedScalarKind === "number") {
             unitNames.add(spec.dartType);
           }
         }