@githolon/dsl 0.102.3 → 0.102.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.102.3",
+  "version": "0.102.5",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/check_package_main.ts

@@ -26,6 +26,7 @@ import {
   type EvolveLaw,
   type StableIdLockfile,
 } from "./evolve_preview.js";
+import { parseStableIdLockfile } from "./stable_id_lockfile.js";
 
 interface DomainConfig {
   key: string;
@@ -125,7 +126,7 @@ function loadPriorEvolveLaw(arg: string): { law: EvolveLaw; source: string; note
   const p = parsed as Record<string, unknown>;
   if (p.domains !== undefined && p.interface === undefined && p.packageUsda === undefined) {
     return {
-      law: evolveLawFromLockfile(parsed as StableIdLockfile),
+      law: evolveLawFromLockfile(parseStableIdLockfile(parsed)),
       source: file,
       note: `prior is a lockfile — aggregate/field identity is diffed, but directive payload changes cannot be (deploy.json carries the interface).`,
     };
@@ -149,7 +150,7 @@ function loadCwdLockfile(configArg: string): StableIdLockfile | undefined {
   const lockPath = path.join(cfgDir, "nomos.stable-ids.json");
   if (!existsSync(lockPath)) return undefined;
   try {
-    return JSON.parse(readFileSync(lockPath, "utf8")) as StableIdLockfile;
+    return parseStableIdLockfile(JSON.parse(readFileSync(lockPath, "utf8")));
   } catch {
     return undefined;
   }

package/src/codegen_dart.ts

@@ -1707,7 +1707,7 @@ function dartTypeOfVoField(f: ValueObjectFieldDescriptor, voName: string, fieldN
   switch (f.type) {
     case "string":
       return f.idOf !== undefined
-        ? `NomosRef<${concreteClassName(f.idOf)}>`
+        ? `NomosRef<${f.idOfContract === true ? contractTypeName(f.idOf) : concreteClassName(f.idOf)}>`
         : f.brand ?? "String"; // a brandedId(...) → the generated extension-type wrapper
     case "number":
       // a UNIT-tagged number is the generated zero-cost extension type; `.int()` is Dart int.
@@ -1742,7 +1742,7 @@ function voFromExpr(
   switch (f.type) {
     case "string":
       if (f.idOf !== undefined) {
-        const target = concreteClassName(f.idOf);
+        const target = f.idOfContract === true ? contractTypeName(f.idOf) : concreteClassName(f.idOf);
         return `NmsInternalNomosRefs.create<${target}>(workspace: '', type: '${f.idOf}', id: ${expr} as String)`;
       }
       return f.brand !== undefined ? `${f.brand}(${expr} as String)` : `${expr} as String`;

package/src/codegen_dart_application.ts

@@ -721,6 +721,11 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
       const targetFile = owner?.name ?? mod.name;
       const targetApplication = dartApplicationClassName(targetDomain);
       const opener = `nomosInternalOpen${targetApplication}`;
+      const rootAggregate = aggregates.get(birth.aggregateId);
+      const rootType = concreteClassName(birth.aggregateId);
+      const rootCollection = member(plural(rootAggregate === undefined
+        ? birth.aggregateId
+        : concreteClassName(rootAggregate.id)));
       if (targetFile !== mod.name) {
         addSibling(`${targetFile}.application.dart`, targetApplication);
         addSibling(`${targetFile}.application.dart`, opener);
@@ -735,7 +740,9 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           `  /// or call a lower-level client.`,
           `  Future<${targetApplication}> ${method}(${dartActionInputClassName(directive)} facts) async {`,
           `    final reference = await _client.${method}(facts);`,
-          `    return ${opener}(_client.bridge, reference, _client.actor);`,
+          opts.supportImport === "package"
+            ? `    return ${rootCollection}._nmsOpenReference(reference);`
+            : `    return ${opener}(_client.bridge, reference, _client.actor);`,
           `  }`,
           ``,
         );
@@ -744,31 +751,47 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           `  /// Give one ${birth.aggregateId} its own durable life.`,
           `  Future<${targetApplication}> birth(Create${cap(camel(birth.aggregateId))}Input facts) async {`,
           `    final reference = await _client.birth(facts);`,
-          `    return ${opener}(_client.bridge, reference, _client.actor);`,
+          opts.supportImport === "package"
+            ? `    return _nmsOpenReference(reference);`
+            : `    return ${opener}(_client.bridge, reference, _client.actor);`,
           `  }`,
           ``,
         ]);
       }
       if (opts.supportImport === "package") {
         usesWorkspaceName = true;
-        const rootAggregate = aggregates.get(birth.aggregateId);
         const rootModel = rootAggregate === undefined
           ? `${concreteClassName(birth.aggregateId)}ReadModel`
           : readModelClassName(rootAggregate.id);
-        const rootType = concreteClassName(birth.aggregateId);
-        const rootCollection = member(plural(rootAggregate === undefined
-          ? birth.aggregateId
-          : concreteClassName(rootAggregate.id)));
         addCollectionMember(birth.aggregateId, "open", [
+          `  final Map<String, Future<${targetApplication}>> _nmsApplications = {};`,
+          ``,
+          `  Future<${targetApplication}> _nmsOpenReference(NomosRef<${rootType}> reference) {`,
+          `    final workspace = NmsInternalNomosRefs.workspace(reference);`,
+          `    final existing = _nmsApplications[workspace];`,
+          `    if (existing != null) return existing;`,
+          `    late final Future<${targetApplication}> opened;`,
+          `    opened = (() async {`,
+          `      try {`,
+          `        return await ${opener}(_client.bridge, reference, _client.actor);`,
+          `      } catch (_) {`,
+          `        if (identical(_nmsApplications[workspace], opened)) {`,
+          `          _nmsApplications.remove(workspace);`,
+          `        }`,
+          `        rethrow;`,
+          `      }`,
+          `    })();`,
+          `    _nmsApplications[workspace] = opened;`,
+          `    return opened;`,
+          `  }`,
+          ``,
           `  /// Open the ${birth.aggregateId} whose ${birth.keyField} is [key].`,
-          `  Future<${targetApplication}> open(String key) => ${opener}(`,
-          `    _client.bridge,`,
+          `  Future<${targetApplication}> open(String key) => _nmsOpenReference(`,
           `    NmsInternalNomosRefs.create<${rootType}>(`,
           `      workspace: deriveWorkspaceName(${JSON.stringify(birth.namespace)}, key),`,
           `      type: ${JSON.stringify(birth.aggregateId)},`,
           `      id: ${JSON.stringify(birth.rootId)},`,
           `    ),`,
-          `    _client.actor,`,
           `  );`,
           ``,
         ]);
@@ -790,14 +813,9 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           `      if (raw is! Map) continue;`,
           `      final child = (raw['child'] ?? '').toString();`,
           `      if (!child.startsWith(${JSON.stringify(`${birth.namespace}-`)})) continue;`,
-          `      final application = await ${opener}(`,
-          `        _client.bridge,`,
-          `        NmsInternalNomosRefs.create<${rootType}>(workspace: child, type: ${JSON.stringify(birth.aggregateId)}, id: ${JSON.stringify(birth.rootId)}),`,
-          `        _client.actor,`,
-          `      );`,
-          `      final record = await application.${rootCollection}.find(`,
-          `        NmsInternalNomosRefs.create<${rootType}>(workspace: child, type: ${JSON.stringify(birth.aggregateId)}, id: ${JSON.stringify(birth.rootId)}),`,
-          `      );`,
+          `      final reference = NmsInternalNomosRefs.create<${rootType}>(workspace: child, type: ${JSON.stringify(birth.aggregateId)}, id: ${JSON.stringify(birth.rootId)});`,
+          `      final application = await _nmsOpenReference(reference);`,
+          `      final record = await application.${rootCollection}.find(reference);`,
           `      if (record != null) records.add(record);`,
           `    }`,
           `    return records;`,
@@ -833,14 +851,9 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           `          object != 'workspace:self' ||`,
           `          prunedAt.isNotEmpty ||`,
           `          !seen.add(workspace)) continue;`,
-          `      final application = await ${opener}(`,
-          `        _client.bridge,`,
-          `        NmsInternalNomosRefs.create<${rootType}>(workspace: workspace, type: ${JSON.stringify(birth.aggregateId)}, id: ${JSON.stringify(birth.rootId)}),`,
-          `        _client.actor,`,
-          `      );`,
-          `      final record = await application.${rootCollection}.find(`,
-          `        NmsInternalNomosRefs.create<${rootType}>(workspace: workspace, type: ${JSON.stringify(birth.aggregateId)}, id: ${JSON.stringify(birth.rootId)}),`,
-          `      );`,
+          `      final reference = NmsInternalNomosRefs.create<${rootType}>(workspace: workspace, type: ${JSON.stringify(birth.aggregateId)}, id: ${JSON.stringify(birth.rootId)});`,
+          `      final application = await _nmsOpenReference(reference);`,
+          `      final record = await application.${rootCollection}.find(reference);`,
           `      if (record != null) records.add(record);`,
           `    }`,
           `    return records;`,
@@ -855,10 +868,8 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           `  /// Continue working in the business application that produced [record].`,
           `  Future<${targetApplication}> applicationOf(${rootModel} record) {`,
           `    final origin = NmsInternalRecordOrigins.require(record);`,
-          `    return ${opener}(`,
-          `      _client.bridge,`,
+          `    return _nmsOpenReference(`,
           `      NmsInternalNomosRefs.create<${rootType}>(workspace: origin.workspace, type: ${JSON.stringify(birth.aggregateId)}, id: origin.id),`,
-          `      _client.actor,`,
           `    );`,
           `  }`,
           ``,
@@ -1028,6 +1039,55 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
       (candidate as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
   )) {
     const sourceModel = readModelClassName(aggregate.id);
+    for (const contractId of aggregate.implementsContracts ?? []) {
+      const contract = contractTypeName(contractId);
+      const method = member(`as${contract}`);
+      addCollectionMember(aggregate.id, method, [
+        `  /// Use [record] wherever another domain declares [${contract}].`,
+        `  ///`,
+        `  /// Nomos preserves the record's workspace-qualified identity while exposing only`,
+        `  /// the contract that this aggregate explicitly implements. This does not grant access.`,
+        `  NomosRef<${contract}> ${method}(${sourceModel} record) {`,
+        `    final reference = record.ref;`,
+        `    _nmsRequireReference(reference, ${JSON.stringify(aggregate.id)}, '');`,
+        `    return NmsInternalNomosRefs.create<${contract}>(`,
+        `      workspace: reference.workspace,`,
+        `      type: ${JSON.stringify(contractId)},`,
+        `      id: reference.id,`,
+        `    );`,
+        `  }`,
+        ``,
+      ]);
+      const resolveMethod = member(`resolve${contract}`);
+      addCollectionMember(aggregate.id, resolveMethod, [
+        `  /// Resolve [reference] as the concrete ${sourceModel} that implements [${contract}].`,
+        `  ///`,
+        `  /// Use this after following a generated cross-application reference and opening`,
+        `  /// its business application. Nomos checks the declared contract and access on read.`,
+        `  Future<${sourceModel}?> ${resolveMethod}(ForeignRef<${contract}> reference) {`,
+        `    _nmsRequireReference(reference.ref, ${JSON.stringify(contractId)}, '');`,
+        `    return find(NmsInternalNomosRefs.create<${concreteClassName(aggregate.id)}>(`,
+        `      workspace: reference.workspace,`,
+        `      type: ${JSON.stringify(aggregate.id)},`,
+        `      id: reference.id,`,
+        `    ));`,
+        `  }`,
+        ``,
+      ]);
+      const watchMethod = member(`watch${contract}`);
+      addCollectionMember(aggregate.id, watchMethod, [
+        `  /// React when the concrete record behind [reference] changes.`,
+        `  Stream<${sourceModel}?> ${watchMethod}(ForeignRef<${contract}> reference) {`,
+        `    _nmsRequireReference(reference.ref, ${JSON.stringify(contractId)}, '');`,
+        `    return watchOne(NmsInternalNomosRefs.create<${concreteClassName(aggregate.id)}>(`,
+        `      workspace: reference.workspace,`,
+        `      type: ${JSON.stringify(aggregate.id)},`,
+        `      id: reference.id,`,
+        `    ));`,
+        `  }`,
+        ``,
+      ]);
+    }
     const sameDomainRefs = Object.entries(aggregate.fields).filter(([, field]) =>
       field.kind === "ref" &&
       field.foreignRef === undefined &&
@@ -1301,7 +1361,7 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
       `/// a repository or parallel application state.`,
       `final class ${collection} {`,
       `  final ${client} _client;`,
-      `  const ${collection}._(this._client);`,
+      `  ${collection}._(this._client);`,
       ``,
       ...members,
       `}`,

package/src/codegen_ts.ts

@@ -598,7 +598,7 @@ function tsTypeOfVoField(f: ValueObjectFieldDescriptor): string {
   switch (f.type) {
     case "string":
       return f.idOf !== undefined
-        ? `NomosRef<${f.idOf}>`
+        ? `NomosRef<${f.idOfContract === true ? contractTypeName(f.idOf) : f.idOf}>`
         : f.brand ?? "string"; // a brandedId(...) → the emitted branded alias
     case "number":
       return "number"; // `.int()`/units are Dart-side nominal products; TS keeps one number

package/src/compile_package_main.ts

@@ -152,6 +152,11 @@ import {
   type InferredRename,
   type StableIds,
 } from "./stable_ids.js";
+import {
+  parseStableIdLockfile,
+  serializeStableIdLockfile,
+  type StableIdLockfile,
+} from "./stable_id_lockfile.js";
 import { emitUsd, type UsdLayer } from "./usd.js";
 import { emitLayeredRelationUsda, type RelationLayerInput } from "./relation_composition.js";
 import { assertNoDartBarrelCollisions, type BarrelExportedFile } from "./dart_barrel_guard.js";
@@ -3053,20 +3058,16 @@ async function main(): Promise<void> {
   // at first appearance (a leftover disappearance is THE EVOLVE GATE's typed question
   // at deploy — answered in the upgrade intent's disposition). The resolved continuity
   // is attached to the module so the canonical manifest + USD-IR carry it.
-  interface StableIdLock {
-    v: 1;
-    domains: Record<string, { stableIds: StableIds; schemas: Record<string, WireSchema> }>;
-  }
   const lockPath = path.join(cfgDir, "nomos.stable-ids.json");
-  const priorLock: StableIdLock | undefined = existsSync(lockPath)
-    ? (JSON.parse(readFileSync(lockPath, "utf8")) as StableIdLock)
+  const priorLock: StableIdLockfile | undefined = existsSync(lockPath)
+    ? parseStableIdLockfile(JSON.parse(readFileSync(lockPath, "utf8")))
     : undefined;
   const inferredRenames: { domain: string; renames: InferredRename[] }[] = [];
   // The lock is project-wide, not package-local. Several package configs commonly live beside one
   // application stage; compiling one must not erase the stable identity of domains owned by its siblings.
   // Current package domains are replaced below, while absent domains remain only as continuity metadata
   // and never leak into this package's interface, law, clients or deployment.
-  const nextLock: StableIdLock = { v: 1, domains: { ...(priorLock?.domains ?? {}) } };
+  const nextLock: StableIdLockfile = { v: 1, domains: { ...(priorLock?.domains ?? {}) } };
   for (const mod of domainModules) {
     const identityName = mod.name;
     // The CURRENT canonical aggregate schemas (a pre-continuity manifest pass —
@@ -3165,7 +3166,7 @@ async function main(): Promise<void> {
   // identity across clean clones). Existing project-domain order is retained, so once sibling
   // packages are registered, recompiling them in any order rewrites the same bytes without a
   // giant formatting-only diff in an established lock.
-  writeFileSync(lockPath, JSON.stringify(nextLock, null, 2) + "\n", "utf8");
+  writeFileSync(lockPath, serializeStableIdLockfile(nextLock), "utf8");
 
   // ── THE STRUCTURAL INTERFACE (#72) — directives (payload shapes) + aggregates (read
   // shapes, sid-keyed), keyed by DOMAIN. The SAME object is (a) baked into the generated

package/src/evolve_preview.ts

@@ -34,6 +34,8 @@ import type { Finding } from "./law_check.js";
 import type { DirectivePayloadShape, DomainInterface } from "./shape_compat.js";
 import { domainInterface } from "./shape_compat.js";
 import type { StableIds } from "./stable_ids_types.js";
+import type { StableIdLockfile } from "./stable_id_lockfile.js";
+export type { StableIdLockfile } from "./stable_id_lockfile.js";
 import type { DomainModule } from "./codegen_dart.js";
 import type { WireSchema } from "./wire.js";
 import { parseUsdaDocument } from "./usd_layers.js";
@@ -92,7 +94,7 @@ function aggregatesFromStableIds(
   for (const [aggLabel, a] of Object.entries(stableIds.aggregates)) {
     const fields: EvolveAggregate["fields"] = {};
     for (const [fLabel, f] of Object.entries(a.fields ?? {})) {
-      const driver = schemas?.[aggLabel]?.[fLabel];
+      const driver = f.driver ?? schemas?.[aggLabel]?.[fLabel];
       fields[f.sid] = {
         sid: f.sid,
         label: fLabel,
@@ -130,12 +132,6 @@ function evolveDomainFromInterface(iface: DomainInterface): EvolveDomain {
   };
 }
 
-/** The committed `nomos.stable-ids.json` lockfile shape (compile_package_main writes it). */
-export interface StableIdLockfile {
-  v: 1;
-  domains: Record<string, { stableIds: StableIds; schemas?: Record<string, WireSchema> }>;
-}
-
 /** A deploy.json body (the subset this preview reads): the per-domain interface + the package
  *  bytes (for the embedded stable-ids/driver schemas when no lockfile rides alongside). */
 export interface DeployJson {
@@ -254,13 +250,19 @@ export function currentEvolveLaw(
     const stableIds = locked?.stableIds;
     const iface = domainInterface(mod, stableIds);
     const dom = evolveDomainFromInterface(iface);
-    // Fold drivers from the lockfile schemas (interface has none).
-    if (locked?.schemas !== undefined) {
+    // Fold drivers from the stable fields. Verbose v1 locks may also carry the
+    // older aggregate-schema copy; compact v2 locks deliberately omit it.
+    if (stableIds !== undefined) {
       for (const agg of Object.values(dom.aggregates)) {
-        const schema = locked.schemas[agg.label];
-        if (schema === undefined) continue;
+        const stableAggregate = Object.values(stableIds.aggregates).find(
+          (candidate) => candidate.sid === agg.sid,
+        );
+        const schema = locked?.schemas?.[agg.label];
         for (const f of Object.values(agg.fields)) {
-          const driver = schema[f.label];
+          const stableField = Object.values(stableAggregate?.fields ?? {}).find(
+            (candidate) => candidate.sid === f.sid,
+          );
+          const driver = stableField?.driver ?? schema?.[f.label];
           if (driver !== undefined) (f as { driver?: string }).driver = JSON.stringify(driver);
         }
       }

package/src/fields.ts

@@ -171,7 +171,14 @@ export type ValueObjectFieldDescriptor =
   /** A plain string, OR a BRANDED nominal string when `brand` is present (a `brandedId(...)`
    * — the generated TS branded alias / Dart extension-type wrapper's name). Wire-identical
    * to a plain string; the brand is a compile-time nominal tag only. */
-  | { readonly type: "string"; readonly brand?: string; readonly idOf?: string; readonly optional?: true }
+  | {
+      readonly type: "string";
+      readonly brand?: string;
+      readonly idOf?: string;
+      /** Present only for an `idOf(recordContract(...))` target. Aggregate is the default. */
+      readonly idOfContract?: true;
+      readonly optional?: true;
+    }
   /** `int: true` when the zod carried `.int()` (Dart `int`, TS `number`); `unit` when the field
    * was declared through `unit(...)` — the generated Dart extension-type wrapper's name. */
   | { readonly type: "number"; readonly int?: true; readonly unit?: string; readonly optional?: true }

package/src/lsp_server.ts

@@ -49,6 +49,7 @@ import {
   type EvolveLaw,
   type StableIdLockfile,
 } from "./evolve_preview.js";
+import { parseStableIdLockfile } from "./stable_id_lockfile.js";
 
 interface DomainConfig {
   key: string;
@@ -192,7 +193,7 @@ function loadPriorEvolveLaw(arg: string, cfgDir: string): EvolveLaw | undefined
   }
   const p = parsed as Record<string, unknown>;
   if (p.domains !== undefined && p.interface === undefined && p.packageUsda === undefined) {
-    return evolveLawFromLockfile(parsed as StableIdLockfile);
+    return evolveLawFromLockfile(parseStableIdLockfile(parsed));
   }
   return evolveLawFromDeployJson(parsed as never);
 }
@@ -202,7 +203,7 @@ function loadCwdLockfile(cfgDir: string): StableIdLockfile | undefined {
   const lockPath = path.join(cfgDir, "nomos.stable-ids.json");
   if (!existsSync(lockPath)) return undefined;
   try {
-    return JSON.parse(readFileSync(lockPath, "utf8")) as StableIdLockfile;
+    return parseStableIdLockfile(JSON.parse(readFileSync(lockPath, "utf8")));
   } catch {
     return undefined;
   }

package/src/stable_id_lockfile.ts

@@ -0,0 +1,144 @@
+import type { StableAggregateId, StableFieldId, StableIds } from "./stable_ids_types.js";
+import type { WireSchema } from "./wire.js";
+
+export interface StableIdLockDomain {
+  stableIds: StableIds;
+  schemas?: Record<string, WireSchema>;
+}
+
+/** The materialized lock shape consumed inside the compiler and authoring tools. */
+export interface StableIdLockfile {
+  v: 1;
+  domains: Record<string, StableIdLockDomain>;
+}
+
+type CompactStableFieldId = Omit<StableFieldId, "contract" | "shape"> & {
+  contract?: string | number;
+};
+
+interface CompactStableAggregateId extends Omit<StableAggregateId, "fields"> {
+  fields: Record<string, CompactStableFieldId>;
+}
+
+interface CompactStableIds extends Omit<StableIds, "aggregates"> {
+  aggregates: Record<string, CompactStableAggregateId>;
+}
+
+interface CompactStableIdLockfile {
+  v: 2;
+  /** [contract hash, canonical contract descriptor], addressed by field.contract. */
+  contracts: readonly (readonly [string, unknown])[];
+  domains: Record<string, { stableIds: CompactStableIds }>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function sortedJson(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortedJson);
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort()
+      .map((key) => [key, sortedJson(value[key])]),
+  );
+}
+
+/**
+ * Read both the original verbose lock and the compact v2 wire shape. Callers always
+ * receive the same fully materialized v1 object, so continuity and evolution logic
+ * never needs to know how the durable file was encoded.
+ */
+export function parseStableIdLockfile(value: unknown): StableIdLockfile {
+  if (!isRecord(value)) throw new Error("stable-id lock must be a JSON object");
+  if (value.v === 1) return value as unknown as StableIdLockfile;
+  if (value.v !== 2 || !Array.isArray(value.contracts) || !isRecord(value.domains)) {
+    throw new Error("unsupported stable-id lock encoding");
+  }
+
+  const compact = value as unknown as CompactStableIdLockfile;
+  const contracts = compact.contracts.map((entry, index) => {
+    if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== "string") {
+      throw new Error(`stable-id lock contract ${index} is malformed`);
+    }
+    return entry;
+  });
+  const domains: StableIdLockfile["domains"] = {};
+
+  for (const [domainName, domain] of Object.entries(compact.domains)) {
+    const aggregates: StableIds["aggregates"] = {};
+    for (const [aggregateName, aggregate] of Object.entries(domain.stableIds.aggregates ?? {})) {
+      const fields: StableAggregateId["fields"] = {};
+      for (const [fieldName, field] of Object.entries(aggregate.fields ?? {})) {
+        const contractRef = field.contract;
+        const { contract: _contractRef, ...fieldWithoutContract } = field;
+        if (typeof contractRef === "number") {
+          const contract = contracts[contractRef];
+          if (contract === undefined) {
+            throw new Error(
+              `stable-id lock field ${domainName}.${aggregateName}.${fieldName} references missing contract ${contractRef}`,
+            );
+          }
+          fields[fieldName] = {
+            ...fieldWithoutContract,
+            contract: contract[0],
+            shape: contract[1],
+          };
+        } else if (typeof contractRef === "string") {
+          fields[fieldName] = { ...fieldWithoutContract, contract: contractRef };
+        } else {
+          fields[fieldName] = fieldWithoutContract;
+        }
+      }
+      aggregates[aggregateName] = { ...aggregate, fields };
+    }
+    domains[domainName] = {
+      stableIds: { ...domain.stableIds, aggregates },
+    };
+  }
+
+  return { v: 1, domains };
+}
+
+/**
+ * Encode the committed lock without repeating identical contract descriptors or
+ * aggregate driver schemas. Fields already retain their canonical merge driver;
+ * the contract table retains the full descriptor needed to prove safe widening.
+ */
+export function serializeStableIdLockfile(lock: StableIdLockfile): string {
+  const contracts: [string, unknown][] = [];
+  const contractIndexes = new Map<string, number>();
+  const domains: CompactStableIdLockfile["domains"] = {};
+
+  for (const [domainName, domain] of Object.entries(lock.domains)) {
+    const aggregates: CompactStableIds["aggregates"] = {};
+    for (const [aggregateName, aggregate] of Object.entries(domain.stableIds.aggregates)) {
+      const fields: CompactStableAggregateId["fields"] = {};
+      for (const [fieldName, field] of Object.entries(aggregate.fields)) {
+        const { shape, ...withoutShape } = field;
+        if (field.contract !== undefined && shape !== undefined) {
+          let index = contractIndexes.get(field.contract);
+          if (index === undefined) {
+            index = contracts.length;
+            contracts.push([field.contract, shape]);
+            contractIndexes.set(field.contract, index);
+          }
+          fields[fieldName] = { ...withoutShape, contract: index };
+        } else {
+          fields[fieldName] = withoutShape;
+        }
+      }
+      aggregates[aggregateName] = { ...aggregate, fields };
+    }
+    domains[domainName] = {
+      stableIds: { ...domain.stableIds, aggregates },
+    };
+  }
+
+  // This is a machine-owned lockfile. Compact JSON is intentional: unlike generated
+  // law and clients, it must be committed so identity survives a clean clone.
+  return JSON.stringify(
+    sortedJson({ v: 2, contracts, domains } satisfies CompactStableIdLockfile),
+  ) + "\n";
+}

package/src/stable_ids.ts

@@ -233,9 +233,14 @@ export function deriveStableIdContinuity(
  * drivers). Returns `undefined` (pair allowed on name-cardinality alone) when no
  * snapshot is available. */
 function priorFieldDriver(
-  resolved: { priorSchema?: WireSchema } | undefined,
+  resolved: {
+    priorFields?: Record<string, StableFieldId>;
+    priorSchema?: WireSchema;
+  } | undefined,
   oldField: string,
 ): string | undefined {
+  const retained = resolved?.priorFields?.[oldField]?.driver;
+  if (retained !== undefined) return JSON.stringify(retained);
   const schema = resolved?.priorSchema;
   if (schema === undefined) return undefined;
   const d = schema[oldField];

package/src/value_object.ts

@@ -396,12 +396,17 @@ function describeZod(
   switch (zodKind(schema)) {
     case "string": {
       const brandedBrand = (schema as unknown as Record<symbol, unknown>)[NOMOS_BRANDED_ID_BRAND];
-      const idOfAgg = (schema as unknown as Record<symbol, unknown>)[NOMOS_IDOF_BRAND];
+      const idOfTarget = idOfMetaOf(schema);
       // idOf(Agg) REFERENCES the aggregate's canonical `NomosRef<Agg>`. Carry `idOf` in the stable
       // descriptor so every emitter can recover the aggregate type while the wire remains a string.
       // A standalone `brandedId("X")` remains an unrelated nominal string and declares its own wrapper.
-      if (typeof idOfAgg === "string") {
-        return { type: "string", brand: `${idOfAgg}Id`, idOf: idOfAgg };
+      if (idOfTarget !== undefined) {
+        return {
+          type: "string",
+          brand: `${idOfTarget}Id`,
+          idOf: idOfTarget,
+          ...(idOfTargetKindOf(schema) === "contract" ? { idOfContract: true as const } : {}),
+        };
       }
       return typeof brandedBrand === "string" ? { type: "string", brand: brandedBrand } : { type: "string" };
     }