@githolon/dsl 0.108.7 → 0.110.0

package/src/codegen_call_usda.ts

@@ -127,15 +127,48 @@ export const TS_CALL_USDA_PRELUDE = [
   `const _nmsGeneratedCall = <Domain extends string, Directive extends string>(domain: Domain, directive: Directive, canonicalUsda: Uint8Array, routingCandidates: readonly string[]): NmsGeneratedCall<Domain, Directive> =>`,
   `  ({ domain, directive, canonicalUsda, routingCandidates: [...new Set(routingCandidates)] }) as unknown as NmsGeneratedCall<Domain, Directive>;`,
   ``,
+  `type _NmsCallReferenceData = { readonly workspace: string; readonly type: string; readonly id: string };`,
+  `const _nmsReferenceTypeMatches = (actual: string, expected: string): boolean =>`,
+  `  expected === "" || actual === expected || actual.endsWith("." + expected);`,
+  `const _nmsReferenceData = (value: unknown, field = "reference"): _NmsCallReferenceData => {`,
+  `  if (typeof value !== "object" || value === null) {`,
+  `    throw new TypeError(field + " must carry a complete NomosRef { workspace, type, id }");`,
+  `  }`,
+  `  const ref = value as { workspace?: unknown; type?: unknown; id?: unknown };`,
+  `  if (typeof ref.workspace !== "string" || ref.workspace.length === 0 || typeof ref.type !== "string" || ref.type.length === 0 || typeof ref.id !== "string" || ref.id.length === 0) {`,
+  `    throw new TypeError(field + " must carry a complete NomosRef { workspace, type, id }");`,
+  `  }`,
+  `  return { workspace: ref.workspace, type: ref.type, id: ref.id };`,
+  `};`,
+  `const _nmsReferenceId = (value: unknown, expectedType: string, workspace: string, field: string): string => {`,
+  `  const ref = _nmsReferenceData(value, field);`,
+  `  if (!_nmsReferenceTypeMatches(ref.type, expectedType)) {`,
+  `    throw new TypeError(field + " refers to " + ref.type + "; expected " + expectedType);`,
+  `  }`,
+  `  if (workspace !== "" && ref.workspace !== workspace) {`,
+  `    throw new TypeError(field + " belongs to workspace " + ref.workspace + "; this application is bound to " + workspace);`,
+  `  }`,
+  `  return ref.id;`,
+  `};`,
+  `const _nmsCheckedReferenceData = (value: unknown, expectedType: string, workspace: string, field: string): _NmsCallReferenceData => {`,
+  `  _nmsReferenceId(value, expectedType, workspace, field);`,
+  `  return _nmsReferenceData(value, field);`,
+  `};`,
+  ``,
   `declare const _nmsGeneratedQueryBrand: unique symbol;`,
   `interface NmsGeneratedQuery<Domain extends string = string, Query extends string = string> {`,
   `  readonly domain: Domain;`,
   `  readonly query: Query;`,
-  `  readonly canonicalArgumentsUsda: Uint8Array;`,
+  `  readonly protobufType: string;`,
+  `  readonly protobufPayload: Uint8Array;`,
   `  readonly [_nmsGeneratedQueryBrand]: readonly [Domain, Query];`,
   `}`,
-  `const _nmsGeneratedQuery = <Domain extends string, Query extends string>(domain: Domain, query: Query, canonicalArgumentsUsda: Uint8Array): NmsGeneratedQuery<Domain, Query> =>`,
-  `  ({ domain, query, canonicalArgumentsUsda }) as NmsGeneratedQuery<Domain, Query>;`,
+  `const _nmsGeneratedQuery = <Domain extends string, Query extends string>(domain: Domain, query: Query, protobufType: string, protobufPayload: Uint8Array): NmsGeneratedQuery<Domain, Query> =>`,
+  `  ({ domain, query, protobufType, protobufPayload }) as NmsGeneratedQuery<Domain, Query>;`,
+  `interface NmsGeneratedResult {`,
+  `  readonly protobufType: string;`,
+  `  readonly protobufPayload: Uint8Array;`,
+  `}`,
   ``,
   // The same generated call encoder runs in browsers, Dart's JS runner and the
   // sealed QuickJS engine.  TextEncoder is a browser/Node convenience, not an
@@ -197,6 +230,14 @@ export const TS_CALL_USDA_PRELUDE = [
   ``,
 ] as const;
 
+/** Query arguments still use their existing nominal USDA contract. Keep that
+ * surface isolated from directive authoring while it is migrated separately. */
+export const TS_QUERY_USDA_PRELUDE = TS_CALL_USDA_PRELUDE.slice(
+  TS_CALL_USDA_PRELUDE.findIndex((line) =>
+    line.startsWith("declare const _nmsGeneratedQueryBrand")
+  ),
+);
+
 /** OpenUSD syntax primitives for generated Dart clients. These helpers never
  * inspect domain values: every value access is expanded into a directive-
  * specific encoder by {@link emitDartCallUsdaEncoder}. */
@@ -270,6 +311,7 @@ export function emitTsCallUsdaEncoder(
   if (intent === undefined) {
     throw new Error(`call USDA codegen: domain '${domain}' has no law intent for '${directive}'`);
   }
+  const publicDirective = intent.publicRoute ?? intent.entity.label;
   const contract = nodes.get(intent.accepts.id);
   if (contract?.kind !== "payload-contract") {
     throw new Error(`call USDA codegen: '${domain}/${directive}' accepts no payload contract`);
@@ -315,7 +357,7 @@ export function emitTsCallUsdaEncoder(
     const canonicalValue = valueIsCanonical || semantic === undefined
       ? value
       : semantic.kind === "id-reference"
-        ? `_nmsReferenceId(${value}, ${JSON.stringify(semantic.target)}, nmsInternalWorkspace, ${JSON.stringify(fieldLabel)})`
+        ? `_nmsReferenceId(${value}, ${JSON.stringify(semantic.target)}, ${semantic.targetKind === "contract" ? '\"\"' : "nmsInternalWorkspace"}, ${JSON.stringify(fieldLabel)})`
         : semantic.kind === "address-reference"
           ? `_nmsCheckedReferenceData(${value}, ${JSON.stringify(semantic.target)}, "", ${JSON.stringify(fieldLabel)})`
           : semantic.kind === "versioned-reference"
@@ -641,7 +683,7 @@ export function emitTsCallUsdaEncoder(
     `  _nmsUsdaClose(out, 2);`,
     `  _nmsUsdaClose(out, 1);`,
     `  _nmsUsdaClose(out, 0);`,
-    `  return _nmsGeneratedCall(${JSON.stringify(domain)}, ${JSON.stringify(directive)}, _nmsUsdaUtf8(out.join("\\n") + "\\n"), _nmsRoutingCandidates);`,
+    `  return _nmsGeneratedCall(${JSON.stringify(domain)}, ${JSON.stringify(publicDirective)}, _nmsUsdaUtf8(out.join("\\n") + "\\n"), _nmsRoutingCandidates);`,
     `}`,
     ``,
   );
@@ -676,6 +718,7 @@ export function emitDartCallUsdaEncoder(
   if (intent === undefined) {
     throw new Error(`Dart call USDA codegen: domain '${domain}' has no law intent for '${directive}'`);
   }
+  const publicDirective = intent.publicRoute ?? intent.entity.label;
   const contract = nodes.get(intent.accepts.id);
   if (contract?.kind !== "payload-contract") {
     throw new Error(`Dart call USDA codegen: '${domain}/${directive}' accepts no payload contract`);
@@ -1106,7 +1149,7 @@ export function emitDartCallUsdaEncoder(
     `  _nmsUsdaClose(out, 0);`,
     `  return NmsInternalGeneratedCalls.create(`,
     `    domain: ${dartString(domain)},`,
-    `    directive: ${dartString(directive)},`,
+    `    directive: ${dartString(publicDirective)},`,
     `    canonicalUsda: Uint8List.fromList(utf8.encode('\${out.join('\\n')}\\n')),`,
     `  );`,
     `}`,

package/src/codegen_dart.ts

@@ -1,7 +1,8 @@
+import { dartRefusalUnions } from "./codegen_refusal.js";
 // 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},
-// byte-identical everywhere. Host JS is only the bridge; domain JS runs inside
+// byte-identical everywhere. Host JS is only the session; domain JS runs inside
 // GitHolon, never as a second execution path.
 // If a file isn't this / hosting this / authoring for this / proving this — it's gone.
 
@@ -28,10 +29,12 @@
  */
 import { z } from "zod";
 import { enumTypeNameOf } from "./enum_type.js";
-import { voMetaOf, collectPayloadValueObjectDescriptors, collectValueObjectDescriptors, idOfMetaOf, idOfTargetKindOf, refOfMetaOf, versionedRefOfMetaOf, brandedIdMetaOf, NOMOS_UNIT_BRAND } from "./value_object.js";
+import { voMetaOf, collectPayloadValueObjectDescriptors, collectSchemaValueObjectDescriptors, collectValueObjectDescriptors, idOfMetaOf, idOfTargetKindOf, refOfMetaOf, 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 { IndexedVariant } from "./indexed_variant.js";
+import { emitDartIndexedVariant } from "./codegen_dart_indexed_variant.js";
 import type { RelationTypeDecl } from "./relation_schema.js";
 import { isGitObjectIdSchema, isSha256DigestSchema, type Field, type FieldKind, type ValueObjectDescriptor, type ValueObjectFieldDescriptor } from "./fields.js";
 import { admitsNull, nullMetaOf, nullDocLine } from "./null_meta.js";
@@ -953,6 +956,8 @@ function unwrapProjectionReturn(zt: z.ZodTypeAny): z.ZodTypeAny {
 }
 
 function projectionReturnDartBaseType(schema: z.ZodTypeAny): string {
+  const valueObject = voMetaOf(schema);
+  if (valueObject !== undefined) return valueObject.name;
   const inner = unwrapProjectionReturn(schema);
   switch (zodTypeName(inner)) {
     case "ZodString":
@@ -978,6 +983,10 @@ function projectionReturnDartType(schema: z.ZodTypeAny): string {
 }
 
 function parseProjectionReturnField(field: string, schema: z.ZodTypeAny): string {
+  const valueObject = voMetaOf(schema);
+  if (valueObject !== undefined) {
+    return `(() { final v = data['${field}']; return v == null ? null : ${valueObject.name}.fromProjected((v as Map).cast<String, Object?>()); })()`;
+  }
   const inner = unwrapProjectionReturn(schema);
   switch (zodTypeName(inner)) {
     case "ZodString":
@@ -1828,25 +1837,7 @@ function emitAggregate(
     `    );`,
     `  }`,
     ``,
-    ...(attributedFields.length > 0
-      ? [
-          [
-            ...attributedFields.flatMap((f) => [
-              `  /// Author provenance of [${f}] (who wrote the current value + whether a`,
-              `  /// concurrent competing write was auto-merged away). Null when the field`,
-              `  /// has no folded provenance yet (pre-attribution rows).`,
-              `  FieldProvenance? get ${f}Provenance => \$provenance['${f}'];`,
-            ]),
-            `  /// The last verified author per attributed field (fields with an unknown`,
-            `  /// author are omitted) — the "who last touched this row" convenience.`,
-            `  Map<String, String> get lastAuthors => {`,
-            `        for (final e in \$provenance.entries)`,
-            `          if (e.value.author != null) e.key: e.value.author!,`,
-            `      };`,
-          ].join("\n"),
-          ``,
-        ]
-      : []),
+    ...emitProvenanceAccessors(attributedFields),
     `  @override`,
     `  bool operator ==(Object other) =>`,
     `      other is ${className} &&`,
@@ -2034,8 +2025,9 @@ export function unionArmClassName(unionName: string, armKey: string): string {
 
 /** The Dart type of one VO descriptor field. `voName`/`fieldName` name the field's
  * generated enum type (`<VoName><FieldName>Enum`) — threaded through arrays. */
-function dartTypeOfVoField(f: ValueObjectFieldDescriptor, voName: string, fieldName: string): string {
-  switch (f.type) {
+export function dartTypeOfVoField(f: ValueObjectFieldDescriptor, voName: string, fieldName: string): string {
+  const value = (() => {
+    switch (f.type) {
     case "string":
       return f.idOf !== undefined
         ? `NomosRef<${f.idOfContract === true ? contractTypeName(f.idOf) : concreteClassName(f.idOf)}>`
@@ -2058,7 +2050,9 @@ function dartTypeOfVoField(f: ValueObjectFieldDescriptor, voName: string, fieldN
     case "object":
     case "geometry":
       return f.ref; // the named VO class (emitted alongside / imported)
-  }
+    }
+  })();
+  return f.nullable === true ? `${value}?` : value;
 }
 
 /** A Dart expression converting the RAW decoded json value `expr` to the field's typed
@@ -2201,7 +2195,7 @@ function emitCopyWith(
   );
   const args = fields.map((x) =>
     x.optional
-      ? `        ${x.member}: identical(${x.member}, _voUnset) ? this.${x.member} : ${x.member} as ${x.dartType}?,`
+      ? `        ${x.member}: identical(${x.member}, _voUnset) ? this.${x.member} : ${x.member} as ${x.dartType}${x.dartType.endsWith("?") ? "" : "?"},`
       : `        ${x.member}: ${x.member} ?? this.${x.member},`,
   );
   return [
@@ -2275,20 +2269,22 @@ function emitUnionClasses(d: ValueObjectDescriptor): string {
     const literalGetters = armLiterals.map((x) => `  String get ${x.member} => '${(x.f as { value: string }).value}';`);
     const literalToLines = armLiterals.map((x) => `        '${x.wireName}': '${(x.f as { value: string }).value}',`);
     const decls = [
-      ...armFields.filter((x) => x.f.type !== "literal").map((x) => `  final ${dartTypeOfVoField(x.f, cls, x.wireName)}${x.optional ? "?" : ""} ${x.member};`),
+      ...armFields.filter((x) => x.f.type !== "literal").map((x) => `  final ${dartTypeOfVoField(x.f, cls, x.wireName)}${x.optional && x.f.nullable !== true ? "?" : ""} ${x.member};`),
       ...literalGetters,
     ];
     const ctor = fields.length === 0
       ? [`  const ${cls}();`]
       : [`  const ${cls}({`, ...fields.map((x) => (x.optional ? `    this.${x.member},` : `    required this.${x.member},`)), `  });`];
     const fromLines = fields.map((x) =>
-      x.optional
+      x.optional || x.f.nullable === true
         ? `      ${x.member}: m['${x.wireName}'] == null ? null : ${voFromExpr(x.f, `m['${x.wireName}']!`, cls, x.wireName)},`
         : `      ${x.member}: ${voFromExpr(x.f, `m['${x.wireName}']!`, cls, x.wireName)},`,
     );
     const toLines = fields.map((x) =>
       x.optional
         ? `        if (${x.member} != null) '${x.wireName}': ${voToJsonExpr(x.f, `${x.member}!`)},`
+        : x.f.nullable === true
+          ? `        '${x.wireName}': ${x.member} == null ? null : ${voToJsonExpr(x.f, `${x.member}!`)},`
         : `        '${x.wireName}': ${voToJsonExpr(x.f, x.member)},`,
     );
     return [
@@ -2306,7 +2302,7 @@ function emitUnionClasses(d: ValueObjectDescriptor): string {
       ...toLines,
       `      };`,
       ``,
-      ...emitCopyWith(cls, fields.map((x) => ({ member: x.member, dartType: dartTypeOfVoField(x.f, cls, x.wireName), optional: x.optional }))),
+      ...emitCopyWith(cls, fields.map((x) => ({ member: x.member, dartType: dartTypeOfVoField(x.f, cls, x.wireName), optional: x.optional || x.f.nullable === true }))),
       `  @override`,
       `  bool operator ==(Object other) => other is ${cls} && _voJsonEq(other.toJson(), toJson());`,
       `  @override`,
@@ -2450,17 +2446,19 @@ function emitValueObjectClass(d: ValueObjectDescriptor): string {
     (x) => `        '${x.wireName}': '${(x.f as { value: string }).value}',`,
   );
   const decls = fields.map(
-    (x) => `  final ${dartTypeOfVoField(x.f, d.name, x.wireName)}${x.optional ? "?" : ""} ${x.member};`,
+    (x) => `  final ${dartTypeOfVoField(x.f, d.name, x.wireName)}${x.optional && x.f.nullable !== true ? "?" : ""} ${x.member};`,
   );
   const ctor = fields.map((x) => (x.optional ? `    this.${x.member},` : `    required this.${x.member},`));
   const fromLines = fields.map((x) =>
-    x.optional
+    x.optional || x.f.nullable === true
       ? `      ${x.member}: m['${x.wireName}'] == null ? null : ${voFromExpr(x.f, `m['${x.wireName}']!`, d.name, x.wireName)},`
       : `      ${x.member}: ${voFromExpr(x.f, `m['${x.wireName}']!`, d.name, x.wireName)},`,
   );
   const toLines = fields.map((x) =>
     x.optional
       ? `        if (${x.member} != null) '${x.wireName}': ${voToJsonExpr(x.f, `${x.member}!`)},`
+      : x.f.nullable === true
+        ? `        '${x.wireName}': ${x.member} == null ? null : ${voToJsonExpr(x.f, `${x.member}!`)},`
       : `        '${x.wireName}': ${voToJsonExpr(x.f, x.member)},`,
   );
   return [
@@ -2487,7 +2485,7 @@ function emitValueObjectClass(d: ValueObjectDescriptor): string {
     ...toLines,
     `      };`,
     ``,
-    ...emitCopyWith(d.name, fields.map((x) => ({ member: x.member, dartType: dartTypeOfVoField(x.f, d.name, x.wireName), optional: x.optional }))),
+    ...emitCopyWith(d.name, fields.map((x) => ({ member: x.member, dartType: dartTypeOfVoField(x.f, d.name, x.wireName), optional: x.optional || x.f.nullable === true }))),
     ``,
     `  @override`,
     `  bool operator ==(Object other) =>`,
@@ -2757,7 +2755,7 @@ function emitDartActivityArm(e: PackageActivityEntry): string[] {
  * The full source of the shared `activity_registry.dart` file — the PURE per-directive activity registry
  * + `renderActivity(rawRow) => ActivityEvent?`, emitted ONCE per package into the TYPES package (both the
  * flat + layered emit). References only nomos_types (`ActivityEvent`/`ActivityRef`/`ActivitySeverity`/
- * `renderActivityTemplate`), so the file is PURE (frontend-safe, no bridge). A raw row is
+ * `renderActivityTemplate`), so the file is PURE (frontend-safe, no session). A raw row is
  * `{ intentId, domain, directiveId, actorSubject, occurredAt, payload }` (the runtime's per-committed-intent
  * shape); `renderActivity` returns null only for work outside the generated public business package.
  */
@@ -2779,23 +2777,20 @@ export function generateDartActivityRegistry(entries: readonly PackageActivityEn
     ``,
     `import 'package:nomos_client/src/nms_generated_runtime.dart';`,
     ``,
-    `/// One business-readable difference found while proving a candidate model against history.`,
-    `enum NomosModelDifferenceKind { rules, outcome, evidence }`,
+    `/// One business-readable difference found at the current model frontier.`,
+    `enum NomosModelDifferenceKind { compatibility, frontier }`,
     ``,
     `class NomosModelDifference {`,
     `  final NomosModelDifferenceKind kind;`,
     `  final String? area;`,
-    `  final String? action;`,
     `  final String summary;`,
-    `  const NomosModelDifference({required this.kind, this.area, this.action, required this.summary});`,
+    `  const NomosModelDifference({required this.kind, this.area, required this.summary});`,
     `}`,
     ``,
     `class NomosModelReview {`,
-    `  final int checkedActions;`,
-    `  final int candidateActions;`,
-    `  final bool? sameOutcome;`,
+    `  final bool? ready;`,
     `  final List<NomosModelDifference> differences;`,
-    `  const NomosModelReview({required this.checkedActions, required this.candidateActions, required this.sameOutcome, required this.differences});`,
+    `  const NomosModelReview({required this.ready, required this.differences});`,
     `}`,
     ``,
     `enum NomosModelAdoptionStatus { adopted, needsStaging, needsDecision, blocked }`,
@@ -2827,7 +2822,7 @@ export function generateDartActivityRegistry(entries: readonly PackageActivityEn
     `    if (status != NomosModelAdoptionStatus.needsDecision || acceptDecision == null) {`,
     `      throw StateError('This model change is not waiting for a business decision.');`,
     `    }`,
-    `    if (reason.isEmpty) throw ArgumentError('accept(reason) needs the business reason for changing prior outcomes');`,
+    `    if (reason.isEmpty) throw ArgumentError('accept(reason) needs the business reason for changing stable identities');`,
     `    return acceptDecision(reason);`,
     `  }`,
     `}`,
@@ -3100,7 +3095,7 @@ function foreignRefExpr(s: AggFieldSpec, aggregate: string): string {
   // workspace resolves to not-found, never throws).
   const wsExpr = `(readStrOrNull(data, '${wsField}') ?? '')`;
   const build = (idVar: string): string =>
-    `NmsInternalForeignRefs.create<${target}>(id: ${idVar}, workspace: ${wsExpr}, type: '${s.foreignRefAggregateType ?? target}', fromJson: ${target}.fromJson)`;
+    `NmsInternalForeignRefs.create<${target}>(id: ${idVar}, workspace: ${wsExpr}, type: '${s.foreignRefAggregateType ?? target}')`;
   return s.optional
     ? `() { final v = ${idReader}; return v == null ? null : ${build("v")}; }()`
     : build(idReader);
@@ -3251,7 +3246,7 @@ function slotDecodeCallback(s: AggFieldSpec, mode: "aggregate" | "readModel"): s
       // read through the normal field path). A plain ref keeps its typed-id decode.
       if (s.foreignRefTarget !== undefined) {
         const t = s.foreignRefTarget;
-        return `(v) => NmsInternalForeignRefs.create<${t}>(id: v as String, workspace: '', type: '${t}', fromJson: ${t}.fromJson)`;
+        return `(v) => NmsInternalForeignRefs.create<${t}>(id: v as String, workspace: '', type: '${t}')`;
       }
       return s.refIdClass !== undefined
         ? `(v) => NmsInternalNomosRefs.create<${s.refIdClass}>(workspace: _location, type: '${s.refAggregateType}', id: v as String)`
@@ -3614,6 +3609,24 @@ function emitFulfilmentSealed(
   return { code, consumed, accessorType: base, accessorName: decl.name };
 }
 
+/** Pure metadata accessors shared by aggregate values and their generated read models. */
+function emitProvenanceAccessors(fields: readonly string[]): string[] {
+  if (fields.length === 0) return [];
+  return [
+    ...fields.flatMap((field) => [
+      `  /// Author of the current value and whether concurrent writes competed.`,
+      `  /// Null when this field has no folded provenance yet (pre-attribution rows).`,
+      `  FieldProvenance? get ${field}Provenance => \$provenance['${field}'];`,
+    ]),
+    `  /// Last verified author per attributed field; unknown authors are omitted.`,
+    `  Map<String, String> get lastAuthors => {`,
+    `        for (final e in \$provenance.entries)`,
+    `          if (e.value.author != null) e.key: e.value.author!,`,
+    `      };`,
+    ``,
+  ];
+}
+
 function emitReadModel(
   agg: AggregateHandle,
   enumDartTypes: Map<string, string>,
@@ -3625,6 +3638,9 @@ function emitReadModel(
 ): string {
   const className = readModelClassName(agg.id);
   const wireType = agg.id;
+  // The generated client decodes attribution into read models as well as aggregate
+  // values. These are two views of the same declared member metadata.
+  const attributedFields = agg.attributedFields ?? [];
   const allSpecs = aggregateFieldSpecs(
     agg,
     enumDartTypes,
@@ -3653,6 +3669,10 @@ 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;`,
+    ...(attributedFields.length > 0
+      ? [`  /// Author metadata for the declared attributed fields; absent before attribution.`,
+          `  final Map<String, FieldProvenance> \$provenance;`]
+      : []),
     ...(sealedFulfilment !== null
       ? [
           `  /// How complete this record is. Switch exhaustively — each variant's fields are`,
@@ -3695,6 +3715,7 @@ function emitReadModel(
   ].join("\n");
   const ctorParams = [
     `    required this.ref,`,
+    ...(attributedFields.length > 0 ? [`    this.\$provenance = const {},`] : []),
     ...(sealedFulfilment !== null
       ? [
           // Defaults to Unfulfilled: the projection serves PARTIAL folds, and "nothing claimed
@@ -3724,7 +3745,7 @@ function emitReadModel(
   // SURFACED MERGE CONFLICTS: per-Surfaced-field convenience accessors (the pending seam an app
   // branches on without hand-parsing) — an EXTENSION on the read model, mirroring the ref-traversal
   // accessor pattern (codegen_dart_client.ts P2). They live HERE (the pure types file), not on the
-  // client: they are pure field reads needing no bridge, and in layered-packages mode the types
+  // client: they are pure field reads needing no session, and in layered-packages mode the types
   // package must not depend on the client. A Surfaced-free aggregate emits none (byte-identical).
   const surfacedSpecs = specs.filter((s) => s.surfaced === true);
   const surfacedExtension =
@@ -3747,6 +3768,9 @@ function emitReadModel(
 
   const parseLines = [
     `      ref: NmsInternalNomosRefs.create<${concreteClassName(agg.id)}>(workspace: _location, type: _kind.isEmpty ? '${aggregateWireTypeForAggregate(agg.id)}' : _kind, id: id),`,
+    ...(attributedFields.length > 0
+      ? [`      \$provenance: FieldProvenance.mapFromJson(data['__prov']),`]
+      : []),
     ...(sealedFulfilment !== null
       ? [`      ${dartMemberName(sealedFulfilment.accessorName)}: _decode${sealedFulfilment.accessorType}(data),`]
       : []),
@@ -3798,6 +3822,7 @@ function emitReadModel(
     parseLines,
     `    );`,
     `  }`,
+    ...emitProvenanceAccessors(attributedFields),
     `}`,
     ...surfacedExtension,
   ].join("\n");
@@ -4829,6 +4854,8 @@ export interface DomainModule {
    * additive `nomosValueObjects` USD key (`usd.ts`).
    */
   valueObjects?: readonly ValueObjectDescriptor[];
+  /** Explicit discriminator/value relationships; generated bindings own typed edit construction. */
+  indexedVariants?: readonly IndexedVariant[];
   /**
    * DOMAIN CONTRACTS (`architecture/domain_contracts.md`) — the public DTO shapes this domain declares
    * (`recordContract(id, fields)`), discovered by shape and composed across the domain's modules. ADDITIVE +
@@ -4982,7 +5009,13 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
   const publicAggregateValueObjectsByName = new Map<string, ValueObjectDescriptor>();
   for (const descriptor of [
     ...collectValueObjectDescriptors(publicAggregates),
+    ...collectSchemaValueObjectDescriptors([
+      ...(mod.deriveds ?? []).map((read) => read.returns),
+      ...(mod.combineds ?? []).map((read) => read.returns),
+    ]),
     ...(opts.additionalValueObjects ?? []),
+    ...(mod.workspaceInvariants ?? []).flatMap(rule => rule.refusal ? [rule.refusal.descriptor, ...rule.refusal.dependencies] : []),
+    ...(mod.indexedVariants ?? []).flatMap((binding) => [binding.value.descriptor, ...binding.value.dependencies]),
   ]) {
     const prior = publicAggregateValueObjectsByName.get(descriptor.name);
     if (prior !== undefined && JSON.stringify(prior) !== JSON.stringify(descriptor)) {
@@ -5126,6 +5159,8 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
           ]),
         ]
       : []),
+    ...(mod.indexedVariants ?? []).map(emitDartIndexedVariant),
+    ...dartRefusalUnions(mod),
   ].join("\n\n");
   // The symbols whose Dart surface this file EMITS (framework-shared ones live in the shared file).
   const localAggregates = mod.aggregates.filter((a) => !skipAggregateIds.has(a.id));