@githolon/dsl 0.102.2 → 0.102.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.102.2",
+  "version": "0.102.4",
   "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/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

@@ -31,6 +31,7 @@ import {
 } from "./framework/framework_aggregates.js";
 import { isBusinessIntent } from "./intent.js";
 import { contractTypeName } from "./contract.js";
+import { admitsNull } from "./null_meta.js";
 import type {
   WorkspaceSharingPolicy,
   WorkspaceSharingReceipt,
@@ -720,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);
@@ -734,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);`,
           `  }`,
           ``,
         );
@@ -743,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,`,
           `  );`,
           ``,
         ]);
@@ -789,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;`,
@@ -832,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;`,
@@ -854,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,`,
           `    );`,
           `  }`,
           ``,
@@ -1027,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 &&
@@ -1051,7 +1112,10 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           ? sourceFieldMember.slice(0, -2)
           : `${sourceFieldMember}Ref`;
         const method = member(stem);
-        const memberNullable = field.isFromBirth !== true;
+        const memberNullable = admitsNull(field) || field.isFromBirth !== true;
+        const sourceFieldValue = admitsNull(field)
+          ? `record.${sourceFieldMember}.valueOrNull`
+          : `record.${sourceFieldMember}`;
         const isSameDomain = sameDomainRefs.some(([name]) => name === fieldName);
         const isCrossDomain = crossDomainRefs.some(([name]) => name === fieldName);
         if (!isSameDomain && !isCrossDomain) continue;
@@ -1064,7 +1128,7 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
             `  Future<${targetModel}?> ${method}(${sourceModel} record) async {`,
             ...(memberNullable
               ? [
-                  `    final id = record.${sourceFieldMember};`,
+                  `    final id = ${sourceFieldValue};`,
                   `    if (id == null) return null;`,
                   `    final rows = await _client.${targetById}(NmsInternalNomosRefs.id(id));`,
                 ]
@@ -1095,7 +1159,7 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           `  Future<${targetModel}?> ${method}(${sourceModel} record) async {`,
           ...(memberNullable
             ? [
-                `    final id = record.${sourceFieldMember};`,
+                `    final id = ${sourceFieldValue};`,
                 `    if (id == null) return null;`,
                 `    final application = await ${opener}(`,
                 `      _client.bridge,`,
@@ -1107,7 +1171,7 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
                 `    );`,
               ]
             : [
-                `    final id = record.${sourceFieldMember};`,
+                `    final id = ${sourceFieldValue};`,
                 `    final application = await ${opener}(`,
                 `      _client.bridge,`,
                 `      id,`,
@@ -1126,7 +1190,7 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
           `  Future<${targetApplication}?> ${applicationMethod}(${sourceModel} record) {`,
           ...(memberNullable
             ? [
-                `    final id = record.${sourceFieldMember};`,
+                `    final id = ${sourceFieldValue};`,
                 `    if (id == null) return Future<${targetApplication}?>.value(null);`,
                 `    return ${opener}(`,
                 `      _client.bridge,`,
@@ -1151,12 +1215,15 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
         ? contractTypeName(foreign.targetAggregateId)
         : concreteClassName(foreign.targetAggregateId);
       const fieldMember = member(fieldName);
+      const fieldValue = admitsNull(field)
+        ? `record.${fieldMember}.valueOrNull`
+        : `record.${fieldMember}`;
       const stem = fieldMember.endsWith("Id") ? fieldMember.slice(0, -2) : fieldMember;
       const method = member(`${stem}Of`);
       addCollectionMember(aggregate.id, method, [
         `  /// Follow [record]'s ${fieldName} to its typed business record.`,
         `  Future<${target}?> ${method}(${sourceModel} record) async {`,
-        `    final reference = record.${fieldMember};`,
+        `    final reference = ${fieldValue};`,
         `    if (reference == null) return null;`,
         `    final target = await NmsInternalForeignRefs.resolve(reference, _client.bridge.foreignReader());`,
         `    if (target == null) return null;`,
@@ -1179,7 +1246,7 @@ export function generateDartApplication(mod: DomainModule, opts: DartApplication
         addCollectionMember(aggregate.id, applicationMethod, [
           `  /// Open the business application containing [record]'s ${fieldName}.`,
           `  Future<${targetApplication}?> ${applicationMethod}(${sourceModel} record) {`,
-          `    final reference = record.${fieldMember};`,
+          `    final reference = ${fieldValue};`,
           `    if (reference == null) return Future<${targetApplication}?>.value(null);`,
           `    return ${opener}(`,
           `      _client.bridge,`,
@@ -1294,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_dart_client.ts

@@ -62,6 +62,7 @@ import { buildNomosDescribeModel, type NomosDescribeModel } from "./describe_mod
 import { assertModelClientMemberAvailable } from "./generated_client_names.js";
 import { ownedRecordActionDirectiveId } from "./framework/owned_custody.js";
 import { contractTypeName } from "./contract.js";
+import { admitsNull } from "./null_meta.js";
 
 const camel = (s: string) => s.replace(/[_\s-]+(\w)/g, (_m, c: string) => c.toUpperCase());
 const lcFirst = (s: string) => (s.length ? s[0]!.toLowerCase() + s.slice(1) : s);
@@ -1268,14 +1269,15 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       // the DSL schema's `.optional()` — a partial fold decodes every scalar `null` when absent
       // (`emitReadModel`'s own doc: "PARTIAL folds"), so the member is nullable UNLESS the field is
       // `.fromBirth()` (birth-presence law — the ONE case the projection types non-null).
-      const memberNullable = f.isFromBirth !== true;
+      const memberNullable = admitsNull(f) || f.isFromBirth !== true;
+      const memberValue = admitsNull(f) ? `${member}.valueOrNull` : member;
       lines.push(
         `  /// Resolve \`${fieldName}\` (${agg.id}.${fieldName} -> ${targetType}) by dispatching to`,
         `  /// [${className}.${byIdMethod}] — the existing by-id read lane, never a second one.`,
         `  Future<${targetModel}?> ${method}(${className} client) async {`,
         ...(memberNullable
           ? [
-              `    final id = ${member};`,
+              `    final id = ${memberValue};`,
               `    if (id == null) return null;`,
               `    final rows = await client.${byIdMethod}(NmsInternalNomosRefs.id(id));`,
             ]
@@ -1301,7 +1303,8 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       const member = dartMemberName(fieldName);
       const methodStem = member.length > 2 && member.endsWith("Id") ? member.slice(0, -2) : `${member}Ref`;
       const method = safeMethod(methodStem);
-      const memberNullable = f.isFromBirth !== true;
+      const memberNullable = admitsNull(f) || f.isFromBirth !== true;
+      const memberValue = admitsNull(f) ? `${member}.valueOrNull` : member;
       lines.push(
         `  /// Resolve \`${fieldName}\` (${agg.id}.${fieldName} -> ${targetType}, a CROSS-DOMAIN ref) by`,
         `  /// dispatching to [${targetClient}.${byIdMethod}] on the target domain's client — same by-id`,
@@ -1310,7 +1313,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
         `  Future<${targetModel}?> ${method}(${targetClient} client) async {`,
         ...(memberNullable
           ? [
-              `    final id = ${member};`,
+              `    final id = ${memberValue};`,
               `    if (id == null) return null;`,
               `    final rows = await client.${byIdMethod}(NmsInternalNomosRefs.id(id));`,
             ]
@@ -1341,6 +1344,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       }
       const targetConcrete = concreteClassName(targetType);
       const member = dartMemberName(fieldName);
+      const memberValue = admitsNull(f) ? `${member}.valueOrNull` : member;
       // The stored locator member is a typed `ForeignRef<Target>?` getter, so the resolver takes a
       // `remote…` name to avoid colliding with it (and to read as "the far side of the reference").
       const method = safeMethod(`remote${cap(camel(member))}`);
@@ -1350,7 +1354,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
         `  /// implementation opens the foreign workspace on demand; tenant code sees only this business method.`,
         `  /// Null locator (absent / empty id or workspace) ⇒ null.`,
         `  Future<${targetConcrete}?> ${method}(NomosEngine engine, {String? cloud}) {`,
-        `    final ref = ${member};`,
+        `    final ref = ${memberValue};`,
         `    if (ref == null) return Future<${targetConcrete}?>.value(null);`,
         `    return NmsInternalForeignRefs.resolve(ref, engine.foreignReader(cloud: cloud));`,
         `  }`,

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/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/law_check.ts

@@ -729,7 +729,7 @@ function dottedQueryKeyFindings(mod: DomainModule, aggById: ReadonlyMap<string,
 // admits before a null is lawful (t.optional / t.clearable / t.nullable / t.json({null})). These
 // twins pre-fire the three refusals the gate would raise: (a) a payload field that ADMITS null with
 // no null-admitting receiver; (b) a null-admitting field used where a null is structurally illegal
-// (authority gate, identity ref, spatial index, read key); (c) a plan op writing literal null into a
+// (authority gate, spatial index, read key); (c) a plan op writing literal null into a
 // field that never declared null a meaning. All PAYLOAD-INDEPENDENT (pure declarations) ⇒ REFUSE.
 
 /** The verbatim null-semantics guidance (`null_semantics.md`) — the `fix` on twin N-a/N-c. */
@@ -843,7 +843,10 @@ function nullBanFindings(mod: DomainModule, aggById: ReadonlyMap<string, Aggrega
     });
   };
 
-  // Facet gates (authority/standing) + identity refs — a null in these breaks the very thing they decide.
+  // Facet gates (authority/standing) — a null in these breaks the very thing they decide. A plain
+  // typed ref is an association, not structural identity: clearing `asset.spaceId`, for example,
+  // means the asset is no longer in a space. If a ref participates in a query/group/spatial key the
+  // corresponding structural check below still refuses it.
   for (const agg of mod.aggregates) {
     for (const [name, f0] of Object.entries(agg.fields)) {
       const f = f0 as Field;
@@ -851,9 +854,6 @@ function nullBanFindings(mod: DomainModule, aggById: ReadonlyMap<string, Aggrega
       if (f.facet === "authority" || f.facet === "standing") {
         ban(agg.id, name, "an authority/standing gate", "drop the null semantic — an authority sink must always resolve to a subject.");
       }
-      if (f.kind === "ref") {
-        ban(agg.id, name, "an identity reference", "an identity ref must always point somewhere — model absence with a separate presence flag, not a null ref.");
-      }
     }
   }
   // Read keys / group-bys / spatial indexes — a null key row is a silent dead index.

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" };
     }