@githolon/dsl 0.1.0

package/src/compile_package_main.ts

@@ -0,0 +1,496 @@
+// 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} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * `nomos-compile` — ONE COMMAND: TS DSL domains → a deployable `.package.usda` (#M4).
+ *
+ * Run from a package that depends on `@githolon/dsl` (esbuild + tsx ride along as its
+ * dependencies — no devDependency setup), next to a `nomos.package.mjs` config:
+ *
+ *     export default {
+ *       name: "guestbook",                       // → build/guestbook.package.usda
+ *       domains: [
+ *         { key: "guestbook", modules: ["./domains/guestbook.ts"] },
+ *       ],
+ *     };
+ *
+ * Per domain: `key` is the engine dispatch key AND the identity-manifest name
+ * (`name` overrides the latter); `modules` is the ORDERED module list (later wins on
+ * a name collision — the framework `identity` union pattern). Read-side declarations
+ * (queries / counts / spatials / deriveds / combineds) are AUTO-DISCOVERED from the
+ * merged module exports by SHAPE (both individual decls and exported arrays of them,
+ * deduped); anything undiscoverable can be passed explicitly as EXPORT NAMES, e.g.
+ * `{ sums: ["GUESTBOOK_SUMS"], extraAggregates: ["SomeFrameworkHandle"] }`.
+ * Reports: `{ reports: { my_report_v1: "./report/my_report.ts#myReportV1" } }`.
+ *
+ * It emits into `outDir` (default `<config dir>/build`):
+ *   * `<name>.package.usda`            — the deployable package (engine bundle + USD IR);
+ *     its sha256 IS the deploy `domainHash` (`policy:{hash}`).
+ *   * `domain_manifests.json`          — the READ manifest (field kinds + query routes).
+ *   * `domain_identity_manifests.json` + `domain_identity_hashes.json` (+ excluded
+ *     sidecar) — the per-domain IDENTITY artifacts (admission gates).
+ *   * `<name>.deploy.json`             — `{packageUsda, readManifest, identityManifests,
+ *     identityHashes}`: the EXACT body `POST /v1/workspaces/:ws/domains` accepts as
+ *     `application/json` on Nomos Cloud (package + per-workspace manifest overlay in
+ *     one deploy).
+ *
+ * The engine entry is GENERATED (imports + one `registerEngine` call — the machinery
+ * lives in `@githolon/dsl/engine-entry`), bundled with the SAME deterministic esbuild
+ * settings as every existing package (`--bundle --format=iife --target=es2020
+ * --platform=neutral --charset=utf8`, no minify), and refused if it does not assign
+ * `globalThis.plan`.
+ */
+import { execFileSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import type { AggregateHandle } from "./aggregate.js";
+import { generateDartDomain, type DomainModule } from "./codegen_dart.js";
+import type { AnyCount } from "./count.js";
+import type { QueryDecl } from "./query.js";
+import type { SpatialDecl } from "./spatial.js";
+import type { AnySum } from "./sum.js";
+import type { DerivedDecl } from "./derived.js";
+import type { CombinedDecl } from "./combined.js";
+import type { ImpureCapabilityDecl } from "./codegen_provider_dart.js";
+import {
+  buildIdentity,
+  buildReadManifest,
+  composeDomainModule,
+  emitUsdJsonForModules,
+  packageUsda,
+  sha256HexUtf8,
+  writeIdentity,
+  type Mod,
+} from "./build_package.js";
+import { generateTsClient } from "./codegen_ts.js";
+
+const DSL_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+interface DomainConfig {
+  readonly key: string;
+  readonly name?: string;
+  readonly modules: readonly string[];
+  // Explicit EXPORT-NAME escape hatches (resolved on the merged module exports):
+  readonly queries?: readonly string[];
+  readonly counts?: readonly string[];
+  readonly sums?: readonly string[];
+  readonly spatials?: readonly string[];
+  readonly deriveds?: readonly string[];
+  readonly combineds?: readonly string[];
+  readonly impureCapabilities?: readonly string[];
+  readonly extraAggregates?: readonly string[];
+  readonly readModelAggregates?: readonly string[];
+}
+
+interface PackageConfig {
+  readonly name: string;
+  readonly domains: readonly DomainConfig[];
+  /** reportId → "modulePath#exportName" (the export is `(actor) => Report`). */
+  readonly reports?: Record<string, string>;
+  readonly outDir?: string;
+  /**
+   * Typed DART frontend (the Flutter sibling of the generated TS client; #codegen_dart).
+   * `false`/absent = skip (default). `true` = emit into `<outDir>/dart/`;
+   * `{ out: "relative/dir" }` = emit there (resolved against the config dir).
+   * Per composed domain one `<name>.dart` (payload classes + read models + typed read
+   * accessors via the SAME `generateDartDomain` the co2 tenant emit uses), PLUS the
+   * framework `nomos_dsl` Dart support files vendored alongside (the generated files'
+   * `package:nomos_dsl/...` import is rewritten to a relative one) — so a Flutter app
+   * can vendor the directory as-is, no pub deps.
+   */
+  readonly dart?: boolean | { readonly out?: string };
+}
+
+function fail(msg: string): never {
+  console.error(`nomos-compile: ${msg}`);
+  process.exit(1);
+}
+
+// ── decl auto-discovery (by SHAPE, mirroring the engine entry's duck-types) ───────
+
+function isQueryDecl(v: unknown): v is QueryDecl {
+  return (
+    !!v &&
+    typeof v === "object" &&
+    typeof (v as { id?: unknown }).id === "string" &&
+    Array.isArray((v as { key?: unknown }).key) &&
+    ((v as { key: unknown[] }).key as unknown[]).every((k) => typeof k === "string") &&
+    typeof (v as { returns?: unknown }).returns === "string" &&
+    typeof (v as { fn?: unknown }).fn !== "function"
+  );
+}
+
+function isSpatialDecl(v: unknown): v is SpatialDecl {
+  return (
+    !!v &&
+    typeof v === "object" &&
+    typeof (v as { id?: unknown }).id === "string" &&
+    typeof (v as { of?: unknown }).of === "string" &&
+    typeof (v as { on?: unknown }).on === "string" &&
+    typeof (v as { fn?: unknown }).fn !== "function"
+  );
+}
+
+function isDerivedDecl(v: unknown): v is DerivedDecl {
+  return (
+    !!v &&
+    typeof v === "object" &&
+    typeof (v as { id?: unknown }).id === "string" &&
+    typeof (v as { of?: unknown }).of === "string" &&
+    typeof (v as { fn?: unknown }).fn === "function" &&
+    (v as { returns?: unknown }).returns !== undefined &&
+    typeof (v as { refField?: unknown }).refField !== "string" &&
+    typeof (v as { reads?: unknown }).reads !== "string"
+  );
+}
+
+function isCombinedDecl(v: unknown): v is CombinedDecl {
+  return (
+    !!v &&
+    typeof v === "object" &&
+    typeof (v as { id?: unknown }).id === "string" &&
+    typeof (v as { of?: unknown }).of === "string" &&
+    typeof (v as { refField?: unknown }).refField === "string" &&
+    typeof (v as { reads?: unknown }).reads === "string" &&
+    typeof (v as { fn?: unknown }).fn === "function" &&
+    (v as { returns?: unknown }).returns !== undefined
+  );
+}
+
+/** A count decl/builder — `{id, of}` with NONE of the other decl families' marks. */
+function isCountDecl(v: unknown): v is AnyCount {
+  if (!v || typeof v !== "object") return false;
+  const o = v as Record<string, unknown>;
+  return (
+    typeof o.id === "string" &&
+    typeof o.of === "string" &&
+    typeof o.on !== "string" && // spatial
+    typeof o.fn !== "function" && // derived/combined
+    !Array.isArray(o.key) && // query
+    !("field" in o) && // sum / extremum
+    !("orderBy" in o) && // ordered read
+    !("_existsMarker" in o) && // exists
+    typeof o.refField !== "string" && // combined
+    o.__isAggregateHandle !== true && // aggregate
+    typeof o.aggregateId !== "string" && // directive
+    typeof o.plan !== "function"
+  );
+}
+
+/** Scan merged exports for decls matching `match`: individual exports AND exported arrays. */
+function discover<T>(merged: Mod, match: (v: unknown) => v is T): T[] {
+  const seen = new Set<string>();
+  const out: T[] = [];
+  const push = (v: T) => {
+    const key = JSON.stringify(v, (_k, val) => (typeof val === "function" ? "<fn>" : val));
+    if (!seen.has(key)) {
+      seen.add(key);
+      out.push(v);
+    }
+  };
+  for (const v of Object.values(merged)) {
+    if (match(v)) push(v);
+    else if (Array.isArray(v)) for (const el of v) if (match(el)) push(el);
+  }
+  return out;
+}
+
+/** Resolve explicit EXPORT NAMES (the config escape hatch) on the merged exports. */
+function resolveNamed<T>(merged: Mod, names: readonly string[] | undefined, what: string): T[] {
+  const out: T[] = [];
+  for (const n of names ?? []) {
+    const v = merged[n];
+    if (v === undefined) fail(`config names ${what} export '${n}', which the modules do not export`);
+    if (Array.isArray(v)) out.push(...(v as T[]));
+    else out.push(v as T);
+  }
+  return out;
+}
+
+// ── Dart emission (the Flutter sibling of the TS client; reuses generateDartDomain) ──
+
+/**
+ * The generated files' support import, exactly as `generateDartDomain` emits it.
+ * Vendored output rewrites it to the relative barrel so the directory is
+ * self-contained (no pub path-dependency on the framework package).
+ */
+const DART_PACKAGE_IMPORT = `import 'package:nomos_dsl/nomos_dsl.dart';`;
+const DART_RELATIVE_IMPORT = `import 'nomos_dsl.dart';`;
+
+/**
+ * The framework `nomos_dsl` Dart support files the generated code resolves through
+ * the barrel (`dsl/dart/lib/`). `schema_validation.dart` is deliberately NOT
+ * vendored: nothing the codegen emits references it, and it would drag the external
+ * `json_schema` pub dependency into every vendoring app.
+ */
+const DART_SUPPORT_SRC = [
+  "wire.dart",
+  "driver.dart",
+  "dispatch.dart",
+  "subscriptions.dart",
+  "provider.dart",
+] as const;
+
+/**
+ * Emit the typed Dart for the composed domain modules into `dartOut`: one
+ * `<name>.dart` per domain (the SAME `generateDartDomain` path the co2 tenant's
+ * `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[] {
+  mkdirSync(path.join(dartOut, "src"), { recursive: true });
+
+  // 1. the vendored framework support (barrel + src/), copied byte-for-byte except
+  //    the barrel's schema_validation export (see DART_SUPPORT_SRC).
+  const libDir = path.join(DSL_DIR, "dart", "lib");
+  const barrel = readFileSync(path.join(libDir, "nomos_dsl.dart"), "utf8")
+    .split("\n")
+    .filter((line) => !line.includes("src/schema_validation.dart"))
+    .join("\n");
+  writeFileSync(path.join(dartOut, "nomos_dsl.dart"), barrel, "utf8");
+  for (const f of DART_SUPPORT_SRC) {
+    copyFileSync(path.join(libDir, "src", f), path.join(dartOut, "src", f));
+  }
+
+  // 2. one generated file per composed domain.
+  const written: string[] = [];
+  for (const mod of modules) {
+    const src = generateDartDomain(mod);
+    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`,
+      );
+    }
+    const p = path.join(dartOut, `${mod.name}.dart`);
+    writeFileSync(p, src.replace(DART_PACKAGE_IMPORT, DART_RELATIVE_IMPORT), "utf8");
+    written.push(p);
+  }
+  return written;
+}
+
+// ── main ──────────────────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  const configArg = process.argv[2] ?? "nomos.package.mjs";
+  const configPath = path.resolve(process.cwd(), configArg);
+  if (!existsSync(configPath)) fail(`config not found: ${configPath}`);
+  const cfgDir = path.dirname(configPath);
+
+  const cfgModule = (await import(pathToFileURL(configPath).href)) as { default?: PackageConfig };
+  const cfg = cfgModule.default;
+  if (!cfg || typeof cfg.name !== "string" || !Array.isArray(cfg.domains) || cfg.domains.length === 0) {
+    fail(`config must default-export { name, domains: [{ key, modules }, ...] }`);
+  }
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(cfg.name)) fail(`package name '${cfg.name}' is not a safe basename`);
+
+  const outDir = path.resolve(cfgDir, cfg.outDir ?? "build");
+  mkdirSync(outDir, { recursive: true });
+
+  // ── import + compose each domain ──
+  const entryImports: string[] = [];
+  const entryDomains: string[] = [];
+  const domainModules: DomainModule[] = [];
+  let importSeq = 0;
+
+  for (const d of cfg.domains) {
+    if (typeof d.key !== "string" || !Array.isArray(d.modules) || d.modules.length === 0) {
+      fail(`each domain needs { key, modules: [path, ...] }; got ${JSON.stringify(d)}`);
+    }
+    const mods: Mod[] = [];
+    const varNames: string[] = [];
+    for (const rel of d.modules) {
+      const abs = path.resolve(cfgDir, rel);
+      if (!existsSync(abs)) fail(`domain '${d.key}': module not found: ${abs}`);
+      const m = (await import(pathToFileURL(abs).href)) as Mod;
+      mods.push(m);
+      const v = `m${importSeq++}`;
+      varNames.push(v);
+      entryImports.push(`import * as ${v} from ${JSON.stringify(abs)};`);
+    }
+    entryDomains.push(`    ${JSON.stringify(d.key)}: [${varNames.join(", ")}],`);
+
+    let merged: Mod = {};
+    for (const m of mods) merged = { ...merged, ...m };
+
+    const queries = [
+      ...discover<QueryDecl>(merged, isQueryDecl),
+      ...resolveNamed<QueryDecl>(merged, d.queries, "queries"),
+    ];
+    const counts = [
+      ...discover<AnyCount>(merged, isCountDecl),
+      ...resolveNamed<AnyCount>(merged, d.counts, "counts"),
+    ];
+    const spatials = [
+      ...discover<SpatialDecl>(merged, isSpatialDecl),
+      ...resolveNamed<SpatialDecl>(merged, d.spatials, "spatials"),
+    ];
+    const deriveds = [
+      ...discover<DerivedDecl>(merged, isDerivedDecl),
+      ...resolveNamed<DerivedDecl>(merged, d.deriveds, "deriveds"),
+    ];
+    const combineds = [
+      ...discover<CombinedDecl>(merged, isCombinedDecl),
+      ...resolveNamed<CombinedDecl>(merged, d.combineds, "combineds"),
+    ];
+    const sums = resolveNamed<AnySum>(merged, d.sums, "sums");
+    const impureCapabilities = resolveNamed<ImpureCapabilityDecl>(
+      merged,
+      d.impureCapabilities,
+      "impureCapabilities",
+    );
+    const extraAggregates = resolveNamed<AggregateHandle>(merged, d.extraAggregates, "extraAggregates");
+
+    domainModules.push(
+      composeDomainModule({
+        name: d.name ?? d.key,
+        domain: d.key,
+        modules: mods,
+        ...(extraAggregates.length > 0 ? { extraAggregates } : {}),
+        ...(queries.length > 0 ? { queries } : {}),
+        ...(counts.length > 0 ? { counts } : {}),
+        ...(d.readModelAggregates !== undefined
+          ? { readModelAggregates: d.readModelAggregates }
+          : {}),
+        ...(deriveds.length > 0 ? { deriveds } : {}),
+        ...(combineds.length > 0 ? { combineds } : {}),
+        ...(impureCapabilities.length > 0 ? { impureCapabilities } : {}),
+        ...(sums.length > 0 ? { sums } : {}),
+        ...(spatials.length > 0 ? { spatials } : {}),
+      }),
+    );
+  }
+
+  // ── reports ──
+  const entryReports: string[] = [];
+  for (const [reportId, ref] of Object.entries(cfg.reports ?? {})) {
+    const [rel, exportName] = ref.split("#");
+    if (!rel || !exportName) fail(`report '${reportId}' must be "modulePath#exportName"; got '${ref}'`);
+    const abs = path.resolve(cfgDir, rel);
+    if (!existsSync(abs)) fail(`report '${reportId}': module not found: ${abs}`);
+    const v = `r${importSeq++}`;
+    entryImports.push(`import * as ${v} from ${JSON.stringify(abs)};`);
+    entryReports.push(`    ${JSON.stringify(reportId)}: ${v}.${exportName},`);
+  }
+
+  // ── 1. generate + bundle the engine entry ──
+  const entrySource = [
+    `// AUTO-GENERATED by nomos-compile from ${path.basename(configPath)} — do not edit.`,
+    ...entryImports,
+    `import { registerEngine } from "@githolon/dsl/engine-entry";`,
+    ``,
+    `registerEngine({`,
+    `  domains: {`,
+    ...entryDomains,
+    `  },`,
+    ...(entryReports.length > 0 ? [`  reports: {`, ...entryReports, `  },`] : []),
+    `});`,
+    ``,
+  ].join("\n");
+  const entryPath = path.join(outDir, ".nomos_entry.ts");
+  writeFileSync(entryPath, entrySource, "utf8");
+
+  // Resolve esbuild through Node's resolver (caller's copy first, else the DSL's
+  // own dependency) — NOT node_modules/.bin paths, which hoisted/workspace
+  // installs relocate. The pinned dependency keeps the engine-lump bytes (and so
+  // the content-addressed domainHash) reproducible across machines.
+  const esbuildPkgJson = [cfgDir, DSL_DIR]
+    .map((dir) => {
+      try {
+        return createRequire(pathToFileURL(path.join(dir, "noop.js"))).resolve("esbuild/package.json");
+      } catch {
+        return undefined;
+      }
+    })
+    .find((p): p is string => p !== undefined);
+  if (!esbuildPkgJson) fail(`esbuild not found — reinstall @githolon/dsl (esbuild is one of its dependencies)`);
+  const esbuildPkg = JSON.parse(readFileSync(esbuildPkgJson, "utf8")) as { bin?: string | Record<string, string> };
+  const esbuildBinRel = typeof esbuildPkg.bin === "string" ? esbuildPkg.bin : esbuildPkg.bin?.["esbuild"];
+  // Exec the bin DIRECTLY (not via `node`): esbuild's postinstall replaces the
+  // JS shim with the platform-native binary, which only an exec can run.
+  const esbuildBin = path.join(path.dirname(esbuildPkgJson), esbuildBinRel ?? "bin/esbuild");
+
+  const javascript =
+    execFileSync(
+      esbuildBin,
+      [entryPath, "--bundle", "--format=iife", "--target=es2020", "--platform=neutral", "--charset=utf8"],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], cwd: cfgDir, maxBuffer: 256 * 1024 * 1024 },
+    ).trimEnd() + "\n";
+  if (!/globalThis\.plan\s*=/.test(javascript) && !/globalThis\["plan"\]\s*=/.test(javascript)) {
+    fail(`bundled engine entry does not assign globalThis.plan — refusing to package`);
+  }
+
+  // ── 2. USD IR + the package envelope ──
+  const usdJson = emitUsdJsonForModules(domainModules);
+  const text = packageUsda(usdJson, javascript);
+  const pkgPath = path.join(outDir, `${cfg.name}.package.usda`);
+  writeFileSync(pkgPath, text, "utf8");
+  const domainHash = sha256HexUtf8(text);
+
+  // ── 3. the READ manifest + IDENTITY artifacts ──
+  const readManifest = buildReadManifest(domainModules);
+  const readPath = path.join(outDir, "domain_manifests.json");
+  writeFileSync(readPath, JSON.stringify(readManifest, null, 2) + "\n", "utf8");
+
+  const identity = buildIdentity(domainModules);
+  const { manifestsPath } = writeIdentity(identity, outDir);
+
+  // ── 4. the one-call deploy body (package + per-workspace manifest overlay) ──
+  const deployBody = {
+    packageUsda: text,
+    readManifest,
+    identityManifests: identity.manifests,
+    identityHashes: identity.hashes,
+  };
+  const deployPath = path.join(outDir, `${cfg.name}.deploy.json`);
+  writeFileSync(deployPath, JSON.stringify(deployBody) + "\n", "utf8");
+
+  // ── 5. the typed TS client (#10 — the web sibling of codegen_dart), with the
+  //       deployed law's content hash baked in (emitted AFTER the package is hashed) ──
+  const clientPath = path.join(outDir, `${cfg.name}.client.ts`);
+  writeFileSync(clientPath, generateTsClient(domainModules, { packageName: cfg.name, domainHash }), "utf8");
+
+  // ── 6. the typed Dart frontend (opt-in; the Flutter sibling of step 5, emitted
+  //       after the package hash like the TS client) ──
+  const dartCfg = cfg.dart ?? false;
+  if (dartCfg !== false && dartCfg !== true && (typeof dartCfg !== "object" || dartCfg === null)) {
+    fail(`config key 'dart' must be false, true, or { out: "relative/dir" }; got ${JSON.stringify(dartCfg)}`);
+  }
+  let dartOut: string | undefined;
+  let dartFiles: string[] = [];
+  if (dartCfg !== false) {
+    dartOut = path.resolve(
+      cfgDir,
+      typeof dartCfg === "object" && dartCfg.out !== undefined ? dartCfg.out : path.join(outDir, "dart"),
+    );
+    dartFiles = emitDart(domainModules, dartOut);
+  }
+
+  // ── summary ──
+  const rel = (p: string) => path.relative(process.cwd(), p);
+  console.log(`nomos-compile: ${cfg.name}`);
+  console.log(`  package    ${rel(pkgPath)} (${text.length} bytes)`);
+  console.log(`  domainHash ${domainHash}`);
+  console.log(`  read       ${rel(readPath)} (${Object.keys(readManifest.aggregateFieldKinds).length} aggregate(s), ${readManifest.queries.length} quer(y/ies), ${readManifest.counts.length} count(s))`);
+  console.log(`  identity   ${rel(manifestsPath)} (${Object.keys(identity.manifests).length} domain(s)${identity.excluded.length ? `, ${identity.excluded.length} EXCLUDED (palette gap)` : ""})`);
+  for (const [dom, h] of Object.entries(identity.hashes)) console.log(`             ${dom.padEnd(20)} ${h}`);
+  for (const ex of identity.excluded) console.log(`             EXCLUDED ${ex.domain}: ${ex.reason}`);
+  console.log(`  client     ${rel(clientPath)} (typed TS client — payloads, read models, query accessors)`);
+  if (dartOut !== undefined) {
+    console.log(`  dart       ${rel(dartOut)}${path.sep} (${dartFiles.length} domain file(s) + vendored nomos_dsl support — typed Dart for Flutter)`);
+  }
+  console.log(`  deploy     ${rel(deployPath)}`);
+  console.log(``);
+  console.log(`deploy (Nomos Cloud):`);
+  console.log(`  curl -X POST -H 'content-type: application/json' \\`);
+  console.log(`    --data-binary @${rel(deployPath)} \\`);
+  console.log(`    https://nomos.captainapp.co.uk/v1/workspaces/<ws>/domains`);
+}
+
+await main();