@githolon/dsl 0.102.3 → 0.102.4

package/package.json

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

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