@githolon/dsl 0.45.0 → 0.47.0

package/dart/test/test_harness_test.dart

@@ -1,75 +1,103 @@
-// NomosTestHarness: unit coverage for the identity/jwt plumbing, plus the LIVE ephemeral fixture loop
-// (birth a throwaway ws → deploy real law → two client replicas → write on one, converge on the other).
-// The live test needs a `githolon login --agent` session (or NOMOS_PRINCIPAL) and is opt-in via NOMOS_LIVE=1.
+// NomosTestHarness — the EPHEMERAL, FULLY-OFFLINE fixture loop: install real tenant law into a fresh local
+// workspace (no cloud), drive one directive + one read through the REAL githolon over the node runner, and
+// tear down deterministically. This is the headless app-test lane: the same bridge + generated-client surface
+// the app UI uses, under `dart test` / `flutter test`, with no network.
+//
+// Prerequisites (skipped-with-reason when absent, so CI stays green either way): `node` on PATH; the
+// in-repo runner; a warm `~/.holon/runtime` cache (holon.wasm + packages.json — one `githolon` run fills it);
+// and the compiled `examples/guestbook/build/guestbook.deploy.json` (`cd examples/guestbook && npx nomos-compile`).
 @TestOn('vm')
 library;
 
-import 'dart:convert';
 import 'dart:io';
 
 import 'package:nomos_client/nomos_headless.dart';
 import 'package:test/test.dart';
 
-String _repoEntry() =>
+String get _repoEntry =>
     '${Directory.current.path}/../../cloud/web-client/runner/node-entry.mjs';
-
-String _guestbookDeployJson() =>
+String get _guestbookDeployJson =>
     '${Directory.current.path}/../../examples/guestbook/build/guestbook.deploy.json';
+String get _runtimeDir =>
+    '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
+
+/// The prerequisite that isn't installable in-test (a warm runtime cache + the compiled fixture). Returns a
+/// skip reason, or null when everything the harness needs is present.
+String? _missingPrereq() {
+  if (!File(_repoEntry).existsSync()) return 'in-repo runner not found at $_repoEntry';
+  if (!File(_guestbookDeployJson).existsSync()) {
+    return 'compile the fixture first: cd examples/guestbook && npx nomos-compile';
+  }
+  if (!File('$_runtimeDir/holon.wasm').existsSync() ||
+      !File('$_runtimeDir/packages.json').existsSync()) {
+    return 'warm ~/.holon/runtime first (run any `githolon` command once to cache the runtime)';
+  }
+  return null;
+}
 
 void main() {
-  test('ephemeral without any identity refuses with a named remedy', () async {
-    // isolate from a real ~/.holon by pointing HOME at an empty dir
-    // (can't re-env the current isolate — so only run when no creds file exists).
-    final home = Platform.environment['HOME'] ?? '';
-    if (File('$home/.holon/credentials.json').existsSync()) {
-      markTestSkipped('a githolon session exists — the fallback would find it');
-      return;
-    }
+  test('ephemeral rejects an empty deploy list with a named remedy', () async {
     await expectLater(
-      NomosTestHarness.ephemeral(),
+      NomosTestHarness.ephemeral(deployJsonPaths: const []),
       throwsA(isA<NomosTestHarnessException>()),
     );
   });
 
-  test(
-    'LIVE: ephemeral fixture — birth, deploy law, write on one replica, read it on another',
-    skip: Platform.environment['NOMOS_LIVE'] != '1'
-        ? 'set NOMOS_LIVE=1 (needs a githolon login --agent session)'
-        : null,
-    () async {
-      final harness = await NomosTestHarness.ephemeral(
-        deployJsonPaths: [_guestbookDeployJson()],
-        nodeEntry: _repoEntry(),
-      );
-      try {
-        final writer = await harness.connect(clientId: 'writer');
-        final reader = await harness.connect(clientId: 'reader');
-        final minted = await writer.mintId('Fixture');
-        expect(minted, startsWith('Fixture_'));
-        final outcome = await writer.offerCreates(
-            domain: 'guestbook',
-            directiveId: 'signGuestbook',
-            payload: {
-              'author': 'harness',
-              'message': 'ephemeral fixture green',
-              'mood': 'delighted',
-              'signedAt': DateTime.now().toUtc().toIso8601String(),
-            });
-        expect(outcome.created, hasLength(1));
-        expect(outcome.created.single.type, 'guestbook.GuestbookEntry');
-        await writer.sync(admit: true);
-        await reader.sync(admit: false);
-        final rows = await reader.query('entriesByAuthor', {'author': 'harness'});
-        expect(rows, hasLength(1));
-        expect(rows.first['id'], outcome.created.single.id);
-        expect(
-            (rows.first['data'] as Map)['message'], 'ephemeral fixture green');
-        stdout.writeln(
-            'live harness green: ws=${harness.workspace} rows=${jsonEncode(rows.first['data'])}');
-      } finally {
-        await harness.dispose();
-      }
-    },
-    timeout: const Timeout(Duration(minutes: 5)),
-  );
+  test('OFFLINE: install real law, write one directive, read it back, dispose', () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    final harness = await NomosTestHarness.ephemeral(
+      deployJsonPaths: [_guestbookDeployJson],
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      registerTearDown: addTearDown, // deterministic auto-dispose even if an expect() throws
+    );
+
+    // Drive the REAL law: a create directive + a declared query — the same ops a generated client emits.
+    final outcome = await harness.bridge.offerCreates(
+      domain: 'guestbook',
+      directiveId: 'signGuestbook',
+      payload: {
+        'author': 'harness',
+        'message': 'offline fixture green',
+        'mood': 'happy',
+        'signedAt': DateTime.now().toUtc().toIso8601String(),
+      },
+    );
+    expect(outcome.created, hasLength(1));
+    expect(outcome.created.single.type, 'guestbook.GuestbookEntry');
+
+    final rows = await harness.bridge.query('entriesByAuthor', {'author': 'harness'});
+    expect(rows, hasLength(1));
+    expect(rows.first['id'], outcome.created.single.id);
+    expect((rows.first['data'] as Map)['message'], 'offline fixture green');
+    expect((rows.first['data'] as Map)['moodEmoji'], '😊'); // proves the law's plan ran, not a stub
+
+    stdout.writeln('offline harness green: ws=${harness.workspace}');
+  }, timeout: const Timeout(Duration(minutes: 2)));
+
+  test('OFFLINE: dispose is idempotent and removes the temp dir', () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    final harness = await NomosTestHarness.ephemeral(
+      deployJsonPaths: [_guestbookDeployJson],
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      autoTearDown: false, // drive dispose explicitly to assert its determinism
+    );
+    // A read proves the holon is live before teardown.
+    expect(await harness.bridge.query('entriesByAuthor', {'author': 'nobody'}), isEmpty);
+
+    await harness.dispose();
+    await harness.dispose(); // idempotent: the second call is a no-op, never throws
+    // The bridge is dead after dispose — a call fails rather than silently reaching a leaked runner.
+    await expectLater(
+        harness.bridge.query('entriesByAuthor', {'author': 'x'}), throwsA(anything));
+  }, timeout: const Timeout(Duration(minutes: 2)));
 }

package/package.json

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

@@ -810,19 +810,21 @@ function collectEnums(
   // hand-maintained `hide` list on the package barrel. The prefix is the field's
   // semantic home, not an accident of import order.
   const domainPrefix = dartTypeNameFromField(domainKey);
-  const register = (preferredName: string, values: readonly string[]) => {
+  // SEMANTIC ENUM NAMES (co2 feedback): the type is named by its SEMANTIC HOME —
+  // `<Domain><Owner><Field>` (`EstateSiteStatus`, not `EstateStatus5Enum`). The owner is the
+  // aggregate (or the payload's target aggregate / directive) the field lives on. A value-set
+  // shared across owners keeps the FIRST owner's name (one identical type, aggregates register
+  // before payloads so the aggregate's name wins). Numeric suffixes survive only as the
+  // last-resort collision guard — with owner-qualified bases they should never fire.
+  const register = (preferredName: string, values: readonly string[], owner = "") => {
     const key = values.join("|");
     if (dartTypes.has(key)) return;
-    // Two DIFFERENT value-sets WITHIN one domain can prefer the SAME name (e.g.
-    // several `status` fields with distinct literal lists all want `StatusEnum`).
-    // Suffix on collision so each distinct value-set gets a UNIQUE Dart enum
-    // (`EstateStatusEnum`, `EstateStatus2Enum`).
-    const base = `${domainPrefix}${dartTypeNameFromField(preferredName)}Enum`;
+    const base = `${domainPrefix}${dartTypeNameFromField(owner)}${dartTypeNameFromField(preferredName)}`;
     let name = base;
     let n = 1;
     while (usedNames.has(name)) {
       n += 1;
-      name = `${domainPrefix}${dartTypeNameFromField(preferredName)}${n}Enum`;
+      name = `${base}${n}`;
     }
     usedNames.add(name);
     dartTypes.set(key, name);
@@ -846,7 +848,7 @@ function collectEnums(
     )) {
       if (field.kind === "enum") {
         // Unwrap `.optional()` so an optional enum field still registers its options.
-        register(name, zodEnumValues(unwrapZod(field.zod)));
+        register(name, zodEnumValues(unwrapZod(field.zod)), agg.id);
       }
     }
   }
@@ -856,7 +858,7 @@ function collectEnums(
     for (const [name, zt] of Object.entries(shape)) {
       const inner = unwrapZod(zt as z.ZodTypeAny);
       if (zodTypeName(inner) === "ZodEnum") {
-        register(name, zodEnumValues(inner));
+        register(name, zodEnumValues(inner), (d as { aggregateId?: string }).aggregateId ?? d.id);
       }
     }
   }
@@ -1246,7 +1248,8 @@ const geometryCoordsDart: Record<string, string> = {
  * VOs stay separate types (VO names are package-unique, so so are these).
  */
 function voEnumName(voName: string, fieldName: string): string {
-  return `${voName}${dartTypeNameFromField(fieldName)}Enum`;
+  // SEMANTIC NAME (co2 feedback): `<VoName><Field>` — `SiteLocationSource`, not `…SourceEnum`.
+  return `${voName}${dartTypeNameFromField(fieldName)}`;
 }
 
 /** The tolerant-decode SENTINEL case name — dodge a literal enum value that would
@@ -1399,16 +1402,24 @@ function emitVoHelpers(): string {
     `/// Deep json equality for generated value-object classes (toJson-based).`,
     `bool _voJsonEq(Object? a, Object? b) {`,
     `  if (a is Map && b is Map) {`,
-    `    if (a.length != b.length) return false;`,
+    `    if (a.length != b.length) {`,
+    `      return false;`,
+    `    }`,
     `    for (final k in a.keys) {`,
-    `      if (!b.containsKey(k) || !_voJsonEq(a[k], b[k])) return false;`,
+    `      if (!b.containsKey(k) || !_voJsonEq(a[k], b[k])) {`,
+    `        return false;`,
+    `      }`,
     `    }`,
     `    return true;`,
     `  }`,
     `  if (a is List && b is List) {`,
-    `    if (a.length != b.length) return false;`,
+    `    if (a.length != b.length) {`,
+    `      return false;`,
+    `    }`,
     `    for (var i = 0; i < a.length; i++) {`,
-    `      if (!_voJsonEq(a[i], b[i])) return false;`,
+    `      if (!_voJsonEq(a[i], b[i])) {`,
+    `        return false;`,
+    `      }`,
     `    }`,
     `    return true;`,
     `  }`,

package/src/codegen_dart_client.ts

@@ -60,6 +60,9 @@ export const dartHashConstName = (fileBase: string): string => `${lcFirst(camel(
 /** `todo-nomos` → `todoNomosInterfaceJson` — the baked structural-interface JSON const (#72). */
 export const interfaceConstNameDart = (fileBase: string): string => `${lcFirst(camel(fileBase))}InterfaceJson`;
 
+/** `todo-nomos` → `todoNomosCompatJson` — the baked client/law compat manifest JSON const (§5). */
+export const compatConstNameDart = (fileBase: string): string => `${lcFirst(camel(fileBase))}CompatJson`;
+
 /** Emit a Dart RAW triple-quoted string literal of an object's JSON (the interface is JSON-only
  *  data — no `'`/`$`/backslash escaping concerns under `r'''…'''`; JSON never contains `'''`). */
 function dartRawJson(value: unknown): string {
@@ -97,6 +100,9 @@ export interface DartBridgeClientOptions {
    *  (read shapes, sid-keyed). Baked in as JSON so the app can negotiate shape-compatibility
    *  against the workspace's installed offer, NOT by law hash. */
   readonly interface?: unknown;
+  /** The CLIENT/LAW COMPAT MANIFEST (§5) — the law hash + interface hash + generator provenance
+   *  this client was generated against. Baked in as JSON (DIAGNOSIS only, never a gate). */
+  readonly compat?: unknown;
   /** Where the bridge/runtime support types are imported from. */
   readonly supportImport?: "vendored" | "package";
   /**
@@ -137,7 +143,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     // appear — only the actor identity (the bridge owns signing).
     const gate = (d as { requiresRelationGate?: { relation: string } }).requiresRelationGate;
     const gateGuard = gate !== undefined
-      ? `    if (actor == null || actor!.trim().isEmpty) throw MissingOfferAuthority(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, requires: ${dartStr(gate.relation)});`
+      ? `    if (actor == null || actor!.trim().isEmpty) {\n      throw MissingOfferAuthority(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, requires: ${dartStr(gate.relation)});\n    }`
       : "";
     const gateDoc = gate !== undefined
       ? `  /// GATED: needs an \`actor\` (the \`${gate.relation}\` relation) — throws MissingOfferAuthority otherwise.`
@@ -218,6 +224,23 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     );
   }
 
+  // ── declared spatial indexes → typed bbox reads (lane-2 read-serving) ──
+  for (const sp of (mod.spatials ?? []) as { id: string; of: string; on: string }[]) {
+    const model = readModelClassName(sp.of);
+    const m = safeMethod(lcFirst(camel(sp.id)));
+    methods.push(
+      `  /// Declared spatial index \`${sp.id}\` — rows of \`${sp.of}\` whose \`${sp.on}\` geometry`,
+      `  /// intersects [bbox] (an R*Tree probe on the local projection, never a scan).`,
+      `  Future<List<${model}>> ${m}({required NomosBbox bbox}) async =>`,
+      `      (await bridge.spatialWithin(${dartStr(sp.id)}, bbox)).map((r) => ${rowToModel(model, "r")}).toList();`,
+      ``,
+      `  /// Reactive \`${sp.id}\` — re-emits when the probe's rows change locally.`,
+      `  Stream<List<${model}>> watch${cap(camel(sp.id))}({required NomosBbox bbox}) =>`,
+      `      bridge.watchSpatial(${dartStr(sp.id)}, bbox).map((rows) => rows.map((r) => ${rowToModel(model, "r")}).toList());`,
+      ``,
+    );
+  }
+
   // ── counts / sums → O(1) typed reads ──
   for (const c of (mod.counts ?? []).map((raw) => finishCount(raw))) {
     const m = safeMethod(lcFirst(camel(c.id)));
@@ -297,6 +320,15 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
           ``,
         ]
       : []),
+    ...(opts.compat !== undefined
+      ? [
+          `/// The CLIENT/LAW COMPAT MANIFEST (§5) as JSON — the law hash, structural interface hash, and`,
+          `/// generator provenance this client was generated against. A DIAGNOSIS surface for connect-time`,
+          `/// classification (silent / shape-compatible / incompatible); it NEVER gates.`,
+          `const String ${compatConstNameDart(mod.name)} = ${dartRawJson(opts.compat)};`,
+          ``,
+        ]
+      : []),
     `/// Typed async client for the \`${domain}\` domain, bound to a connected [NomosBridge].`,
     `///`,
     `/// Pass \`actor\` (the verified principal uid) to author AS that user — the bridge's \`offerDirective\` op`,