@githolon/dsl 0.105.16 → 0.105.18

package/dart/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.64.33
+
+- Converge arbitrary historical generated-model backlogs while failing a genuinely repeated immutable lifecycle step with a typed stall error.
+
 ## 0.64.32
 
 - Prove a restored generated-application device is enrolled before exposing business APIs, including recovery from an interrupted bootstrap journal.

package/dart/lib/src/session_bound.dart

@@ -240,6 +240,73 @@ class DomainClientModelAdoptionRequired implements Exception {
       '"$expectedDomainKey" ($expectedDomainHash) is $status. $summary';
 }
 
+/// A generated model step repeated without converging after several retries.
+///
+/// The limit is per immutable lifecycle step, not a cap on how many historical
+/// model generations a long-lived workspace may lawfully adopt. That distinction
+/// lets an old workspace catch up across an arbitrary backlog while still making
+/// a genuinely stuck stage/accept loop fail loudly and with useful context.
+final class DomainClientModelLifecycleStalled implements Exception {
+  const DomainClientModelLifecycleStalled({
+    required this.domain,
+    required this.candidateHash,
+    required this.status,
+    required this.attempts,
+  });
+
+  final String domain;
+  final String candidateHash;
+  final String status;
+  final int attempts;
+
+  @override
+  String toString() => 'DomainClientModelLifecycleStalled: generated model for '
+      '"$domain" ($candidateHash) remained $status after $attempts governed '
+      'attempts without progress.';
+}
+
+/// Converge every pending generated-model generation, bounded by repeated work.
+///
+/// A workspace can legitimately be more than a fixed number of generations
+/// behind. Each distinct domain/hash/status tuple is evidence of progress, so it
+/// gets its own retry budget. Only repetition of the same immutable step is a
+/// stall.
+Future<T> nmsInternalConvergeGeneratedModel<T>({
+  required Future<T> Function() attempt,
+  required Future<void> Function(DomainClientModelAdoptionRequired change)
+      handle,
+}) async {
+  const maxAttemptsPerStep = 12;
+  final attemptsByStep = <String, int>{};
+  while (true) {
+    try {
+      return await attempt();
+    } on DomainClientModelAdoptionRequired catch (change) {
+      final step = '${change.expectedDomainKey}\u0000'
+          '${change.expectedDomainHash}\u0000'
+          '${change.status}\u0000'
+          '${change.canStage}\u0000${change.canAccept}';
+      final attempts = (attemptsByStep[step] ?? 0) + 1;
+      attemptsByStep[step] = attempts;
+      if (attempts > maxAttemptsPerStep) {
+        throw DomainClientModelLifecycleStalled(
+          domain: change.expectedDomainKey,
+          candidateHash: change.expectedDomainHash,
+          status: change.status,
+          attempts: attempts,
+        );
+      }
+      try {
+        await handle(change);
+      } on DomainClientModelAdoptionRequired {
+        // A transient preflight/acceptance race re-enters the same typed step.
+        // The per-step budget above prevents a genuine loop without limiting
+        // how many distinct historical generations may converge.
+      }
+    }
+  }
+}
+
 /// The context-rich replacement for the kernel's generic
 /// `no active installed law declares domain 'x' … deploy the domain package first` refusal —
 /// thrown wherever that error used to surface (bridge dispatch, birth lanes) so an app dev sees

package/dart/pubspec.yaml

@@ -7,7 +7,7 @@ repository: https://github.com/Captain-App/nomos2
 description: >-
   Nomos 2 Dart client — generated domain values, intent payloads and application
   lifecycle types over the typed Nomos kernel protocol and USDA custody model.
-version: 0.64.32
+version: 0.64.33
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.105.16",
+  "version": "0.105.18",
   "type": "module",
   "sideEffects": false,
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",

package/src/codegen_dart_client.ts

@@ -2507,16 +2507,12 @@ export function generateDartBridgeClient(
           `      );`,
           `    }`,
         ]),
-    `    for (var modelStep = 0; modelStep < 12; modelStep += 1) {`,
-    `      try {`,
-    `        return await bind(session, actor: actor${
+    `    return nmsInternalConvergeGeneratedModel<${className}>(`,
+    `      attempt: () => bind(session, actor: actor${
       manualEncryptionPresent ? ", keyStore: keyStore" : ""
-    });`,
-    `      } on DomainClientModelAdoptionRequired catch (change) {`,
-    `        await session.nomosInternalHandleModelChange(change);`,
-    `      }`,
-    `    }`,
-    `    throw StateError('Generated model lifecycle did not settle after twelve governed steps.');`,
+    }),`,
+    `      handle: session.nomosInternalHandleModelChange,`,
+    `    );`,
     `  }`,
     ``,
     `  /// The session workspace this client is bound to (from the [NomosSession] handle, when constructed with`,

package/src/codegen_ts.ts

@@ -1598,7 +1598,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     // holon; `resolve`/`watch` use the application's captured shared-plane navigator.
     // The reader is captured by the generated application. Tenant code receives navigation, never a reader.
     `interface _NomosForeignWorkspace { queryById(id: string): Promise<unknown>; watchById?(id: string, cb: (rows: unknown) => void, opts?: { intervalMs?: number }): () => void }`,
-    `interface NomosForeignReader { __nomosOpenChild?(workspace: string): Promise<_NomosForeignWorkspace> }`,
+    `interface NomosForeignReader { readonly workspace?: string; __nomosOpenChild?(workspace: string): Promise<_NomosForeignWorkspace> }`,
     `async function _openForeign(nomos: NomosForeignReader, workspace: string): Promise<_NomosForeignWorkspace> {`,
     `  if (nomos.__nomosOpenChild === undefined) throw new Error("Nomos cannot follow this business reference on the installed runtime");`,
     `  return nomos.__nomosOpenChild(workspace);`,
@@ -2329,8 +2329,16 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
   }
 
   const aggByType = new Map<string, AggregateHandle>();
+  const runtimeTypeByAggregate = new Map<string, string>();
   for (const mod of modules) {
-    for (const agg of mod.aggregates as AggregateHandle[]) aggByType.set(agg.id, agg);
+    const domain = mod.domain ?? mod.name;
+    for (const agg of mod.aggregates as AggregateHandle[]) {
+      aggByType.set(agg.id, agg);
+      runtimeTypeByAggregate.set(
+        agg.id,
+        isNamespacedAggregate(agg) ? qualifyReadProjectionType(domain, agg.id) : agg.id,
+      );
+    }
   }
 
   const anyAutoStamp = modules.some((mod) =>
@@ -2533,6 +2541,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
 
   out.push(`// ── read models (projection \`data\` shapes; partial-fold optional, EXCEPT .fromBirth()`, `//    fields — their presence is gate law, so the type is non-optional) ──`, ``);
   const foreignRefFields: { agg: string; field: string; workspaceField: string; target: string }[] = [];
+  const directRefFields: { agg: string; field: string; target: string; workspace?: string }[] = [];
   const atomicRefFields: { agg: string; field: string }[] = [];
   const versionedRefFields: { agg: string; field: string; currentField: string }[] = [];
   // wrap a read accessor return expression through the foreignRef row-hydrator (identity + byte-identical
@@ -2540,9 +2549,9 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
   // Every read accessor's rows get their canonical `.ref` stamped from `holon.workspace` (additive); a
   // foreignRef-declaring package ALSO hydrates its foreignRef fields into typed locators first.
   const wrapP = (expr: string): string =>
-    `_businessRecordsP(_stampRefsP(holon.workspace, ${foreignRefFields.length + atomicRefFields.length + versionedRefFields.length > 0 ? `_hydrateP(holon, ${expr})` : expr}))`;
+    `_businessRecordsP(_stampRefsP(holon.workspace, ${foreignRefFields.length + directRefFields.length + atomicRefFields.length + versionedRefFields.length > 0 ? `_hydrateP(holon, ${expr})` : expr}))`;
   const wrapRows = (expr: string): string =>
-    `_businessRecords(_stampRefs(holon.workspace, ${foreignRefFields.length + atomicRefFields.length + versionedRefFields.length > 0 ? `_hydrateRows(holon, ${expr})` : expr}))`;
+    `_businessRecords(_stampRefs(holon.workspace, ${foreignRefFields.length + directRefFields.length + atomicRefFields.length + versionedRefFields.length > 0 ? `_hydrateRows(holon, ${expr})` : expr}))`;
   // ATTRIBUTED READS (architecture/field_provenance.md): the shared provenance shape +
   // per-aggregate accessors — emitted ONLY when the package declares ≥1 `.attributed()`
   // field, so a provenance-free package's client is byte-identical (the era rule).
@@ -2571,6 +2580,19 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       out.push(`  ${tsKey(name)}${required ? "" : "?"}: ${tsTypeOfField(field as Field)};`);
       const fr = (field as { foreignRef?: { workspaceField: string; targetAggregateId: string } }).foreignRef;
       if (fr !== undefined) foreignRefFields.push({ agg: typeId, field: name, workspaceField: fr.workspaceField, target: fr.targetAggregateId });
+      if (
+        (field as Field).refAggregateId !== undefined &&
+        (field as Field).foreignRef === undefined &&
+        (field as Field).nomosRef === undefined &&
+        (field as Field).versionedForeignRef === undefined
+      ) {
+        directRefFields.push({
+          agg: typeId,
+          field: name,
+          target: runtimeTypeByAggregate.get((field as Field).refAggregateId!) ?? (field as Field).refAggregateId!,
+          ...((field as Field).refWorkspace === undefined ? {} : { workspace: (field as Field).refWorkspace }),
+        });
+      }
       if ((field as Field).nomosRef !== undefined) atomicRefFields.push({ agg: typeId, field: name });
       const vr = (field as Field).versionedForeignRef;
       if (vr !== undefined) versionedRefFields.push({ agg: typeId, field: name, currentField: vr.currentField });
@@ -2614,7 +2636,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
   // row into a `ForeignRef<TargetAggregate>` — reading the foreign id (the field) + the foreign workspace id (the
   // declared sibling field). The read model stays honest (the field is the raw stored id string); this gives
   // the TYPED locator with resolve/watch on top, without cloning the other holon.
-  if (foreignRefFields.length + atomicRefFields.length + versionedRefFields.length > 0) {
+  if (foreignRefFields.length + directRefFields.length + atomicRefFields.length + versionedRefFields.length > 0) {
     const byAgg = new Map<string, typeof foreignRefFields>();
     for (const f of foreignRefFields) { const l = byAgg.get(f.agg) ?? []; l.push(f); byAgg.set(f.agg, l); }
     out.push(`// ── foreign-ref locators (t.foreignRef): typed cross-workspace edges (resolve/watch on demand) ──`);
@@ -2637,23 +2659,35 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     // `row.data.<field>.id` is still the raw id. Identity for any aggregate without foreignRefs.
     const hydrateSpecs: Record<string, { field: string; wsField: string; target: string }[]> = {};
     for (const f of foreignRefFields) { (hydrateSpecs[f.agg] ??= []).push({ field: f.field, wsField: f.workspaceField, target: f.target }); }
+    const directSpecs: Record<string, { field: string; target: string; workspace?: string }[]> = {};
+    for (const f of directRefFields) {
+      (directSpecs[f.agg] ??= []).push({
+        field: f.field,
+        target: f.target,
+        ...(f.workspace === undefined ? {} : { workspace: f.workspace }),
+      });
+    }
     const atomicSpecs: Record<string, { field: string }[]> = {};
     for (const f of atomicRefFields) { (atomicSpecs[f.agg] ??= []).push({ field: f.field }); }
     const versionedSpecs: Record<string, { field: string; currentField: string }[]> = {};
     for (const f of versionedRefFields) { (versionedSpecs[f.agg] ??= []).push({ field: f.field, currentField: f.currentField }); }
     out.push(
       `const _FOREIGN_REFS: Record<string, { field: string; wsField: string; target: string }[]> = ${JSON.stringify(hydrateSpecs)};`,
+      `const _DIRECT_REFS: Record<string, { field: string; target: string; workspace?: string }[]> = ${JSON.stringify(directSpecs)};`,
       `const _ATOMIC_REFS: Record<string, { field: string }[]> = ${JSON.stringify(atomicSpecs)};`,
       `const _VERSIONED_REFS: Record<string, { field: string; currentField: string }[]> = ${JSON.stringify(versionedSpecs)};`,
       `function _hydrateRows<T>(nomos: NomosForeignReader, rows: Row<T>[]): Row<T>[] {`,
       `  return rows.map((row) => {`,
       `    const raw = row as Row<T> & { type: string };`,
-      `    const specs = _FOREIGN_REFS[raw.type] ?? [];`,
-      `    const atomic = _ATOMIC_REFS[raw.type] ?? [];`,
-      `    const versioned = _VERSIONED_REFS[raw.type] ?? [];`,
-      `    if ((specs.length + atomic.length + versioned.length) === 0 || row.data == null) return row;`,
+      `    const localType = raw.type.slice(raw.type.lastIndexOf(".") + 1);`,
+      `    const specs = _FOREIGN_REFS[raw.type] ?? _FOREIGN_REFS[localType] ?? [];`,
+      `    const direct = _DIRECT_REFS[raw.type] ?? _DIRECT_REFS[localType] ?? [];`,
+      `    const atomic = _ATOMIC_REFS[raw.type] ?? _ATOMIC_REFS[localType] ?? [];`,
+      `    const versioned = _VERSIONED_REFS[raw.type] ?? _VERSIONED_REFS[localType] ?? [];`,
+      `    if ((specs.length + direct.length + atomic.length + versioned.length) === 0 || row.data == null) return row;`,
       `    const data: Record<string, unknown> = { ...(row.data as Record<string, unknown>) };`,
       `    for (const s of specs) { const v = data[s.field]; if (typeof v === "string") data[s.field] = foreignRef(nomos, s.target, v, String(data[s.wsField] ?? "")); }`,
+      `    for (const s of direct) { const v = data[s.field]; if (typeof v === "string") data[s.field] = _nmsRef(s.workspace ?? nomos.workspace ?? "", s.target, v); }`,
       `    for (const s of atomic) { const v = data[s.field] as { workspace: string; type: string; id: string } | undefined; if (v && typeof v === "object") data[s.field] = _nmsRef(v.workspace, v.type, v.id); }`,
       ...(hasVersionedRefs
         ? [`    for (const s of versioned) { const v = data[s.field] as { pinned: _NomosRawAddress; series: _NomosRawAddress } | undefined; if (v && typeof v === "object") data[s.field] = _versionedNomosRef(nomos as NomosHolon, v, s.currentField); }`]

package/src/compile_package_main.ts

@@ -1664,8 +1664,8 @@ const NOMOS_TYPES_DEP = "^0.8.7";
 // 0.48.x: session-bound clients (XClient.bind/NomosClientInterface/DomainClientSessionMismatch/
 //         DomainNotInstalledForSession, engine.follow, pendingConflicts lanes) — the generated client
 //         REQUIRES this surface. 0.48.1 fixes NomosSession.watchPendingConflicts delegation.
-const NOMOS_CLIENT_DEP = "^0.64.32";
-const NOMOS_FLUTTER_DEP = "^0.63.55";
+const NOMOS_CLIENT_DEP = "^0.64.33";
+const NOMOS_FLUTTER_DEP = "^0.63.57";
 // DRIFT TRIPWIRE: pubspec_pins.test.ts asserts these equal the CURRENT versions in dsl/dart/pubspec.yaml
 // and dsl/dart_types/pubspec.yaml — a Dart release without this bump fails the suite, so tenants never
 // land back in dependency_overrides (the exact co2 report this closes, third occurrence).
@@ -3936,12 +3936,26 @@ async function main(): Promise<void> {
       const domainKey = mod.domain ?? mod.name;
       const locked = priorLock.domains[mod.name] ?? priorLock.domains[domainKey];
       if (locked !== undefined) {
+        const currentImplementationDetailAggregateIds = new Set(
+          mod.aggregates
+            .filter(
+              (aggregate) =>
+                (aggregate as { businessBirthInternal?: unknown }).businessBirthInternal === true,
+            )
+            .map((aggregate) => aggregate.id),
+        );
         // Framework aggregates are shared implementation law, reconciled under @framework rather
-        // than owned by this tenant domain. A package may compose a different framework subset as
-        // its topology changes; never instruct a tenant to author a retirement for Nomos internals.
+        // than owned by this tenant domain. Domain-scoped implementation aggregates such as
+        // NomosSourceFrontier deliberately retain the tenant domain's law namespace, but are still
+        // hidden from its structural interface. A package may compose a different framework subset
+        // as its topology changes; never instruct a tenant to author a retirement for Nomos internals.
         const localAggregates = Object.fromEntries(
           Object.entries(locked.stableIds.aggregates)
-            .filter(([, aggregate]) => !frameworkAggregateSids.has(aggregate.sid)),
+            .filter(
+              ([aggregateId, aggregate]) =>
+                !frameworkAggregateSids.has(aggregate.sid) &&
+                !currentImplementationDetailAggregateIds.has(aggregateId),
+            ),
         );
         priorDomainsForPackage[domainKey] = {
           stableIds: { ...locked.stableIds, aggregates: localAggregates },