@githolon/dsl 0.11.0 → 0.13.0

package/package.json

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

@@ -1265,7 +1265,7 @@ function parseField(s: AggFieldSpec, aggregate: string): string {
  * `SiteRootAggregate` → `Site`) and append `ReadModel` (`SiteReadModel`,
  * `BuildingReadModel`, `ThingReadModel`, `TrackableThingReadModel`). Pure + deterministic
  * — the same wire type always yields the same name. */
-function readModelClassName(aggregateType: string): string {
+export function readModelClassName(aggregateType: string): string {
   let stem = aggregateType;
   if (stem.endsWith("RootAggregate")) {
     stem = stem.slice(0, -"RootAggregate".length);

package/src/codegen_dart_client.ts

@@ -0,0 +1,219 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * ASYNC DART BRIDGE-CLIENT CODEGEN (#61) — the Flutter sibling of `codegen_ts.ts`.
+ *
+ * `codegen_dart.ts` emits the per-domain TYPES: read-model classes (`…ReadModel.fromProjected`),
+ * typed intent DTOs (`…Payload.toPayloadJson()`), typed ids, enums. Until this file a Flutter app
+ * still hand-typed directive ids + query ids against the raw `NomosBridge` (string + Map). This closes
+ * that: ONE generated `<name>.client.dart` per domain, emitted by `nomos-compile` AFTER the package is
+ * hashed (the deployed law's content hash baked in), carrying a `<Domain>Client` over a connected
+ * [NomosBridge] (the WebView runner) with:
+ *
+ *   * a typed DISPATCH method per directive — takes the generated `…Payload`, serialises via its
+ *     `toPayloadJson()`, auto-stamps omitted `…At` timestamps (the same caller-clock sugar the TS
+ *     client applies), returns the new local head;
+ *   * a typed declared-QUERY accessor per `query(...)` — one-shot `Future<List<…ReadModel>>` + a
+ *     reactive `watch…` `Stream<List<…ReadModel>>`, parsed off the bridge's `{type,id,data}` rows;
+ *   * by-id read/watch + a type-index `list…` per aggregate;
+ *   * typed O(1) count/sum accessors.
+ *
+ * It IMPORTS the sibling `<name>.dart` (for the read-model + payload classes) and the vendored
+ * `nomos_dsl.dart` barrel (for `NomosBridge`). NO manifest/hash impact — pure frontend codegen, exactly
+ * like `codegen_dart.ts`. NO FALLBACK: an unsupported shape throws at compile time.
+ */
+import type { z } from "zod";
+
+import type { AggregateHandle } from "./aggregate.js";
+import type { Field } from "./fields.js";
+import type { Directive } from "./directive.js";
+import type { QueryDecl } from "./query.js";
+import type { DomainModule } from "./codegen_dart.js";
+import { cap, readModelClassName } from "./codegen_dart.js";
+import { finishCount } from "./count.js";
+import { finishSum } from "./sum.js";
+import { autoStampFields } from "./codegen_ts.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);
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyDirective = Directive<any>;
+
+/** Dart reserved words that can't be method names — suffixed `_` if one slips through. */
+const DART_RESERVED = new Set([
+  "assert", "break", "case", "catch", "class", "const", "continue", "default", "do", "else", "enum",
+  "extends", "false", "final", "finally", "for", "if", "in", "is", "new", "null", "rethrow", "return",
+  "super", "switch", "this", "throw", "true", "try", "var", "void", "while", "with", "dynamic",
+]);
+const safeMethod = (s: string): string => (DART_RESERVED.has(s) ? `${s}_` : s);
+
+/** `guestbook` / `tool-library` / `Tool Library` → `GuestbookClient` / `ToolLibraryClient`. */
+export const dartClientClassName = (domain: string): string => `${cap(camel(domain))}Client`;
+/** `guestbook` → `guestbookDomainHash` — the Dart top-level const (lowerCamel by lint). */
+export const dartHashConstName = (fileBase: string): string => `${lcFirst(camel(fileBase))}DomainHash`;
+
+const dartStr = (s: string) => `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+
+/** The Dart param type for a query index key (int-kinded keys → `int`, else `String`). */
+function dartKeyType(agg: AggregateHandle | undefined, key: string): string {
+  const lead = key.includes(".") ? key.split(".")[0]! : key;
+  const f = agg?.fields[lead] as Field | undefined;
+  return f && (f.kind === "int" || f.kind === "counter") ? "int" : "String";
+}
+
+/** A Dart-safe param identifier from a (possibly dotted) index key: `a.b.c` → `aBC`. */
+function dartKeyParam(key: string): string {
+  const parts = key.split(".").filter((p) => p !== "");
+  const id = parts.length === 0 ? "key" : parts[0]! + parts.slice(1).map((p) => cap(p)).join("");
+  const cleaned = id.replace(/[^A-Za-z0-9_]/g, "_");
+  const safe = /^[0-9]/.test(cleaned) ? `v${cleaned}` : cleaned;
+  return safeMethod(safe);
+}
+
+/** Parse ONE bridge row (`{type,id,data}`) into a typed read model. Works for a `Map` (one-shot
+ * `query`/`queryById` rows) or a `dynamic` (`watch` stream rows) — indexing resolves on both. */
+function rowToModel(model: string, rowVar: string): string {
+  return `${model}.fromProjected((${rowVar}['data'] as Map).cast<String, dynamic>(), (${rowVar}['id'] ?? '').toString())`;
+}
+
+export interface DartBridgeClientOptions {
+  /** sha256 of the built `.package.usda` — the law this client dispatches under. */
+  readonly domainHash: string;
+}
+
+/** Generate the `<name>.client.dart` async bridge client for one domain module. */
+export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClientOptions): string {
+  const domain = mod.domain ?? mod.name;
+  const className = dartClientClassName(domain);
+  const hashConst = dartHashConstName(mod.name);
+  const aggById = new Map<string, AggregateHandle>();
+  for (const a of mod.aggregates) aggById.set(a.id, a);
+
+  const methods: string[] = [];
+
+  // ── directives → typed dispatch ──
+  const dirs = (mod.directives as AnyDirective[]).filter(
+    (d) => d && typeof d.id === "string" && typeof (d as { payloadSchema?: unknown }).payloadSchema === "object",
+  );
+  for (const d of dirs) {
+    const payloadClass = `${cap(d.id)}Payload`;
+    const stamps = autoStampFields((d as unknown as { payloadSchema: z.ZodTypeAny }).payloadSchema);
+    const method = safeMethod(d.id);
+    if (stamps.length > 0) {
+      methods.push(
+        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
+        `  /// Omitted ${stamps.map((s) => `\`${s}\``).join(" / ")} auto-stamp(s) ISO now() at dispatch.`,
+        `  Future<String> ${method}(${payloadClass} payload) {`,
+        `    final data = payload.toPayloadJson();`,
+        `    final now = DateTime.now().toUtc().toIso8601String();`,
+        ...stamps.map((s) => `    data.putIfAbsent(${dartStr(s)}, () => now);`),
+        `    return bridge.dispatch(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: data, domainHash: domainHash);`,
+        `  }`,
+        ``,
+      );
+    } else {
+      methods.push(
+        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
+        `  Future<String> ${method}(${payloadClass} payload) =>`,
+        `      bridge.dispatch(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: payload.toPayloadJson(), domainHash: domainHash);`,
+        ``,
+      );
+    }
+  }
+
+  // ── declared queries → one-shot + reactive ──
+  for (const q of (mod.queries ?? []) as QueryDecl[]) {
+    const model = readModelClassName(q.returns);
+    const agg = aggById.get(q.returns);
+    const params = q.key.map((k) => `required ${dartKeyType(agg, k)} ${dartKeyParam(k)}`).join(", ");
+    const argMap = `{${q.key.map((k) => `${dartStr(k)}: ${dartKeyParam(k)}`).join(", ")}}`;
+    const m = safeMethod(lcFirst(camel(q.id)));
+    methods.push(
+      `  /// Declared query \`${q.id}\` (indexed probe — routed by the read manifest).`,
+      `  Future<List<${model}>> ${m}({${params}}) async =>`,
+      `      (await bridge.query(${dartStr(q.id)}, ${argMap})).map((r) => ${rowToModel(model, "r")}).toList();`,
+      ``,
+      `  /// Reactive \`${q.id}\` — re-emits on every local change (cancel the subscription to stop).`,
+      `  Stream<List<${model}>> watch${cap(camel(q.id))}({${params}}) =>`,
+      `      bridge.watch(${dartStr(q.id)}, ${argMap}).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)));
+    methods.push(
+      c.by != null
+        ? `  /// Declared count \`${c.id}\` — the maintained O(1) tally per \`${c.by}\`.\n  Future<int> ${m}(String ${dartKeyParam(c.by)}) => bridge.count(${dartStr(c.id)}, ${dartKeyParam(c.by)});`
+        : `  /// Declared count \`${c.id}\` — the maintained O(1) grand total.\n  Future<int> ${m}() => bridge.count(${dartStr(c.id)});`,
+      ``,
+    );
+  }
+  for (const s of (mod.sums ?? []).map((raw) => finishSum(raw))) {
+    const m = safeMethod(lcFirst(camel(s.id)));
+    methods.push(
+      s.by != null
+        ? `  /// Declared sum \`${s.id}\` — the maintained O(1) total per \`${s.by}\`.\n  Future<int> ${m}(String ${dartKeyParam(s.by)}) => bridge.sum(${dartStr(s.id)}, ${dartKeyParam(s.by)});`
+        : `  /// Declared sum \`${s.id}\` — the maintained O(1) grand total.\n  Future<int> ${m}() => bridge.sum(${dartStr(s.id)});`,
+      ``,
+    );
+  }
+
+  // ── per-aggregate by-id read/watch + type-index list ──
+  for (const agg of mod.aggregates) {
+    const model = readModelClassName(agg.id);
+    const lc = lcFirst(camel(agg.id));
+    const Cap = cap(camel(agg.id));
+    methods.push(
+      `  /// Read one ${agg.id} by aggregate id.`,
+      `  Future<List<${model}>> ${safeMethod(`${lc}ById`)}(String id) async =>`,
+      `      (await bridge.queryById(id)).map((r) => ${rowToModel(model, "r")}).toList();`,
+      ``,
+      `  /// Watch one ${agg.id} by aggregate id (local reactive read).`,
+      `  Stream<List<${model}>> watch${Cap}ById(String id) =>`,
+      `      bridge.watchById(id).map((rows) => rows.map((r) => ${rowToModel(model, "r")}).toList());`,
+      ``,
+      `  /// Every ${agg.id} (the type-index probe — O(result), not a scan).`,
+      `  Future<List<${model}>> ${safeMethod(`list${Cap}s`)}() async =>`,
+      `      (await bridge.query('aggregatesByType', {'__type': ${dartStr(agg.id)}})).map((r) => ${rowToModel(model, "r")}).toList();`,
+      ``,
+    );
+  }
+
+  return [
+    `// AUTO-GENERATED by nomos-compile — typed ASYNC Dart client for domain "${domain}".`,
+    `// Drives the REAL githolon over a NomosBridge (the WebView runner). Regenerated every compile; do`,
+    `// not edit. Construct with a connected bridge:`,
+    `//`,
+    `//   final bridge = NomosBridge(transport);   // transport = your WebViewTransport`,
+    `//   await bridge.ready;`,
+    `//   await bridge.connect(cloud: cloud, workspace: ws, clientId: deviceId);`,
+    `//   final app = ${className}(bridge);`,
+    `//   await app.${dirs[0] ? safeMethod(dirs[0].id) : "someDirective"}(/* typed payload */);`,
+    ``,
+    `import 'nomos_dsl.dart';`,
+    `import '${mod.name}.dart';`,
+    `// Re-export the sibling types (read models + payloads + the bridge runtime) so ONE import of this`,
+    `// client file gives an app the whole typed surface.`,
+    `export '${mod.name}.dart';`,
+    `export 'nomos_dsl.dart' show NomosBridge, BridgeTransport, NomosBridgeError, kWebviewBridgeVersion;`,
+    ``,
+    `/// sha256 of the deployed \`.package.usda\` — the installed law this client dispatches under.`,
+    `const String ${hashConst} = ${dartStr(opts.domainHash)};`,
+    ``,
+    `/// Typed async client for the \`${domain}\` domain, bound to a connected [NomosBridge].`,
+    `class ${className} {`,
+    `  final NomosBridge bridge;`,
+    `  final String domainHash;`,
+    `  ${className}(this.bridge, {this.domainHash = ${hashConst}});`,
+    ``,
+    ...methods,
+    `}`,
+    ``,
+  ].join("\n");
+}

package/src/compile_package_main.ts

@@ -63,6 +63,7 @@ import {
   type DomainModule,
   type PermissionVocabulary,
 } from "./codegen_dart.js";
+import { generateDartBridgeClient } from "./codegen_dart_client.js";
 import type { AnyCount } from "./count.js";
 import type { QueryDecl } from "./query.js";
 import type { SpatialDecl } from "./spatial.js";
@@ -408,6 +409,9 @@ const DART_SUPPORT_SRC = [
   "dispatch.dart",
   "subscriptions.dart",
   "provider.dart",
+  // The async WebView bridge runtime (NomosBridge / BridgeTransport) the generated
+  // `<name>.client.dart` drives — the barrel re-exports it, so it must be vendored too.
+  "webview_bridge.dart",
 ] as const;
 
 /**
@@ -416,7 +420,7 @@ const DART_SUPPORT_SRC = [
  * `emit_dart.ts` drives) + the vendored `nomos_dsl.dart` barrel and its `src/`
  * support files, with the generated files' `package:` import rewritten relative.
  */
-function emitDart(modules: readonly DomainModule[], dartOut: string): string[] {
+function emitDart(modules: readonly DomainModule[], dartOut: string, domainHash: string): string[] {
   mkdirSync(path.join(dartOut, "src"), { recursive: true });
 
   // 1. the vendored framework support (barrel + src/), copied byte-for-byte except
@@ -431,10 +435,18 @@ function emitDart(modules: readonly DomainModule[], dartOut: string): string[] {
     copyFileSync(path.join(libDir, "src", f), path.join(dartOut, "src", f));
   }
 
-  // 2. one generated file per composed domain.
+  // 2. one generated file per composed domain — the TYPES (`<name>.dart`) + the async bridge
+  //    CLIENT (`<name>.client.dart`, the Flutter sibling of `<name>.client.ts`).
   const written: string[] = [];
   for (const mod of modules) {
-    const src = generateDartDomain(mod);
+    // Default the read-model allowlist to EVERY aggregate when the domain didn't pin one, so
+    // `<name>.dart` carries a read model per aggregate — the bridge client imports them. A domain
+    // that pins `readModelAggregates` keeps its choice (byte-identical to before this default).
+    const modForDart: DomainModule =
+      mod.readModelAggregates === undefined
+        ? { ...mod, readModelAggregates: mod.aggregates.map((a) => a.id) }
+        : mod;
+    const src = generateDartDomain(modForDart);
     if (!src.includes(DART_PACKAGE_IMPORT)) {
       fail(
         `generated Dart for domain '${mod.name}' does not carry the expected support import (${DART_PACKAGE_IMPORT}) — codegen_dart header drifted; fix the rewrite in compile_package_main.ts`,
@@ -443,6 +455,11 @@ function emitDart(modules: readonly DomainModule[], dartOut: string): string[] {
     const p = path.join(dartOut, `${mod.name}.dart`);
     writeFileSync(p, src.replace(DART_PACKAGE_IMPORT, DART_RELATIVE_IMPORT), "utf8");
     written.push(p);
+
+    const clientSrc = generateDartBridgeClient(modForDart, { domainHash });
+    const cp = path.join(dartOut, `${mod.name}.client.dart`);
+    writeFileSync(cp, clientSrc, "utf8");
+    written.push(cp);
   }
   return written;
 }
@@ -1351,7 +1368,7 @@ async function main(): Promise<void> {
       cfgDir,
       typeof dartCfg === "object" && dartCfg.out !== undefined ? dartCfg.out : path.join(outDir, "dart"),
     );
-    dartFiles = emitDart(domainModules, dartOut);
+    dartFiles = emitDart(domainModules, dartOut, domainHash);
   }
 
   // ── summary ──