@githolon/dsl 0.102.5 → 0.103.0

package/compile_package.mjs

@@ -13,14 +13,54 @@
 // Resolution goes through Node's resolver (createRequire), NOT node_modules/.bin
 // paths — hoisted/workspace installs put the bin shims elsewhere.
 import { execFileSync } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  compileInputs,
+  compileProofPath,
+  readCompileProof,
+} from "./compile_proof.mjs";
 
 const DSL_DIR = path.dirname(fileURLToPath(import.meta.url));
 const MAIN = path.join(DSL_DIR, "src", "compile_package_main.ts");
 
+const args = process.argv.slice(2);
+const configArg = args.find((argument) => !argument.startsWith("--")) ?? "nomos.project.ts";
+const configPath = path.resolve(process.cwd(), configArg);
+const cacheable =
+  existsSync(configPath) &&
+  !args.includes("--preflight") &&
+  !args.includes("--analyze") &&
+  process.env.NOMOS_PREFLIGHT !== "1" &&
+  process.env.NOMOS_ANALYZE !== "1";
+const argumentIdentity = [
+  ...args,
+  `NOMOS_COMPACT=${process.env.NOMOS_COMPACT ?? ""}`,
+  `NOMOS_REQUIRE_USDCAT=${process.env.NOMOS_REQUIRE_USDCAT ?? ""}`,
+  `NOMOS_USDCAT=${process.env.NOMOS_USDCAT ?? ""}`,
+].join("\n");
+if (cacheable) {
+  const proofPath = compileProofPath(process.cwd(), configPath);
+  const inputs = compileInputs({
+    cwd: process.cwd(),
+    dslDir: DSL_DIR,
+    configPath,
+    argumentIdentity,
+  });
+  const proof = readCompileProof({ proofPath, inputs });
+  if (proof !== undefined) {
+    console.log(`nomos-compile: ${proof.name} unchanged`);
+    console.log(`  law        ${path.relative(process.cwd(), proof.law)}`);
+    console.log(`  domainHash ${proof.domainHash}`);
+    console.log(`  verify     ✓ typed USDA content proof covers compiler, authored inputs and ${proof.outputCount} generated artifacts`);
+    process.exit(0);
+  }
+  process.env.NOMOS_COMPILE_PROOF_PATH = proofPath;
+  process.env.NOMOS_COMPILE_ARGUMENT_IDENTITY = argumentIdentity;
+}
+
 /** Resolve a dependency's package dir from `fromDir`, walking Node's resolver. */
 function resolvePkgDir(name, fromDir) {
   try {
@@ -41,9 +81,10 @@ const tsxBinRel = typeof tsxPkg.bin === "string" ? tsxPkg.bin : tsxPkg.bin?.tsx;
 const tsxCli = path.join(tsxDir, tsxBinRel ?? "dist/cli.mjs");
 
 try {
-  execFileSync(process.execPath, [tsxCli, MAIN, ...process.argv.slice(2)], {
+  execFileSync(process.execPath, [tsxCli, MAIN, ...args], {
     stdio: "inherit",
     cwd: process.cwd(),
+    env: process.env,
   });
 } catch (e) {
   process.exit(e.status ?? 1);

package/compile_proof.d.mts

@@ -0,0 +1,47 @@
+export interface CompileProofInputs {
+  readonly authoring: readonly { readonly path: string; readonly sha256: string }[];
+  readonly compiler: readonly { readonly path: string; readonly sha256: string }[];
+  readonly authoringIdentity: string;
+  readonly compilerIdentity: string;
+  readonly argumentIdentity: string;
+}
+
+export function compileInputs(options: {
+  cwd: string;
+  dslDir: string;
+  configPath: string;
+  argumentIdentity: string;
+}): CompileProofInputs;
+export function compileProofPath(cwd: string, configPath: string): string;
+export function generatedOutputFiles(
+  outDir: string,
+  additional?: readonly string[],
+): readonly { readonly path: string; readonly sha256: string }[];
+export function writeCompileProof(options: {
+  proofPath: string;
+  inputs: CompileProofInputs;
+  outputs: readonly { readonly path: string; readonly sha256: string }[];
+  name: string;
+  domainHash: string;
+  law: string;
+}): void;
+export function readCompileProof(options: {
+  proofPath: string;
+  inputs: CompileProofInputs;
+}): { name: string; domainHash: string; law: string; outputCount: number } | undefined;
+export function writePlanCompileProof(options: {
+  proofPath: string;
+  baseIdentity: string;
+  runtimeSha256: string;
+  plan: string;
+  planSha256: string;
+  inputs: readonly { readonly path: string; readonly sha256: string }[];
+}): void;
+export function readPlanCompileProof(options: {
+  proofPath: string;
+  baseIdentity: string;
+  runtimeSha256: string;
+  digestFile?: (file: string) => string;
+}): { javascript: string; sha256: string } | undefined;
+export function writeKeyProofUsda(file: string, format: string, key: string): void;
+export function readKeyProofUsda(file: string, format: string): string | undefined;

package/compile_proof.mjs

@@ -0,0 +1,343 @@
+// A content-addressed compiler proof expressed as USDA, not a parallel JSON manifest.
+// It is disposable build cache metadata under node_modules/.cache: law and custody
+// remain the emitted typed USDA closure.
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const INPUT_EXTENSIONS = new Set([
+  ".ts", ".mts", ".cts", ".js", ".mjs", ".cjs", ".json", ".yaml", ".yml",
+]);
+const EXCLUDED_DIRECTORIES = new Set([
+  ".dart_tool", ".git", ".nomos-cache", "coverage", "node_modules",
+]);
+const HASH = /^[0-9a-f]{64}$/u;
+
+const compareText = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const usdaString = (value) => `"${String(value)
+  .replaceAll("\\", "\\\\")
+  .replaceAll("\"", "\\\"")
+  .replaceAll("\n", "\\n")
+  .replaceAll("\r", "\\r")}"`;
+
+function walk(root, predicate, { excludeDefaultBuild = false } = {}) {
+  const files = [];
+  const visit = (directory) => {
+    let entries;
+    try {
+      entries = readdirSync(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        if (EXCLUDED_DIRECTORIES.has(entry.name)) continue;
+        if (excludeDefaultBuild && entry.name === "build" && directory === root) continue;
+        visit(path.join(directory, entry.name));
+      } else if (entry.isFile()) {
+        const file = path.join(directory, entry.name);
+        if (predicate(file)) files.push(file);
+      }
+    }
+  };
+  visit(path.resolve(root));
+  return files;
+}
+
+function inventory(files) {
+  return [...new Set(files.map((file) => path.resolve(file)))]
+    .sort(compareText)
+    .map((file) => ({ path: file, sha256: existsSync(file) ? sha256(readFileSync(file)) : "missing" }));
+}
+
+function inventoryIdentity(kind, entries) {
+  const hash = createHash("sha256").update(`nomos-compile-${kind}-v1\0`);
+  for (const entry of entries) hash.update(entry.path).update("\0").update(entry.sha256).update("\0");
+  return hash.digest("hex");
+}
+
+function dependencyPackageFiles(dslDir, cwd) {
+  const files = [];
+  for (const name of ["esbuild", "tsx", "typescript", "zod"]) {
+    for (const base of [cwd, dslDir]) {
+      try {
+        const request = createRequire(pathToFileURL(path.join(base, "noop.js")));
+        files.push(request.resolve(`${name}/package.json`));
+        break;
+      } catch {
+        // The real compiler names a missing dependency after a proof miss.
+      }
+    }
+  }
+  return files;
+}
+
+export function compileInputs({ cwd, dslDir, configPath, argumentIdentity }) {
+  const authoring = inventory([
+    configPath,
+    ...walk(cwd, (file) => INPUT_EXTENSIONS.has(path.extname(file)), { excludeDefaultBuild: true }),
+  ]);
+  const compiler = inventory([
+    ...walk(path.join(dslDir, "src"), (file) => INPUT_EXTENSIONS.has(path.extname(file))),
+    ...walk(path.join(dslDir, "runtime"), (file) => INPUT_EXTENSIONS.has(path.extname(file))),
+    path.join(dslDir, "package.json"),
+    path.join(dslDir, "compile_package.mjs"),
+    path.join(dslDir, "compile_proof.mjs"),
+    ...dependencyPackageFiles(dslDir, cwd),
+  ]);
+  return {
+    authoring,
+    compiler,
+    authoringIdentity: inventoryIdentity("authoring", authoring),
+    compilerIdentity: inventoryIdentity("implementation", compiler),
+    argumentIdentity: sha256(`nomos-compile-arguments-v1\0${argumentIdentity}`),
+  };
+}
+
+export function compileProofPath(cwd, configPath) {
+  const key = sha256(path.resolve(configPath)).slice(0, 24);
+  return path.join(cwd, "node_modules", ".cache", "nomos", `${key}.compile-proof.usda`);
+}
+
+function artifactPrim(kind, entry, proofDir) {
+  const id = sha256(`${kind}\0${entry.path}`).slice(0, 24);
+  const relative = path.relative(proofDir, entry.path).replaceAll(path.sep, "/");
+  const type = kind === "input" ? "NomosCompileInput" : "NomosCompileArtifact";
+  return {
+    id: `${kind[0]}_${id}`,
+    lines: [
+      `        def ${type} "${kind[0]}_${id}"`,
+      "        {",
+      `            custom uniform asset nomos:path = @${relative}@`,
+      `            custom uniform string nomos:sha256 = "${entry.sha256}"`,
+      "        }",
+    ],
+  };
+}
+
+function emitCompileProof({ proofPath, inputs, outputs, name, domainHash, law }) {
+  const proofDir = path.dirname(proofPath);
+  const inputPrims = [...inputs.authoring, ...inputs.compiler].map((entry) => artifactPrim("input", entry, proofDir));
+  const outputPrims = outputs.map((entry) => artifactPrim("output", entry, proofDir));
+  const relationships = (scope, prims) => prims.map((prim) => `        </CompileProof/${scope}/${prim.id}>`);
+  return [
+    "#usda 1.0",
+    "(",
+    "    customLayerData = {",
+    '        string "nomos:format" = "nomos.compile-proof.v1"',
+    "    }",
+    ")",
+    "",
+    'def NomosCompileProof "CompileProof"',
+    "{",
+    `    custom uniform string nomos:package = ${usdaString(name)}`,
+    `    custom uniform string nomos:domainHash = "${domainHash}"`,
+    `    custom uniform asset nomos:law = @${path.relative(proofDir, law).replaceAll(path.sep, "/")}@`,
+    `    custom uniform string nomos:authoringIdentity = "${inputs.authoringIdentity}"`,
+    `    custom uniform string nomos:compilerIdentity = "${inputs.compilerIdentity}"`,
+    `    custom uniform string nomos:argumentIdentity = "${inputs.argumentIdentity}"`,
+    "    custom rel nomos:inputs = [",
+    ...relationships("Inputs", inputPrims).map((line, index) => `${line}${index + 1 === inputPrims.length ? "" : ","}`),
+    "    ]",
+    "    custom rel nomos:outputs = [",
+    ...relationships("Outputs", outputPrims).map((line, index) => `${line}${index + 1 === outputPrims.length ? "" : ","}`),
+    "    ]",
+    "",
+    '    def Scope "Inputs"',
+    "    {",
+    ...inputPrims.flatMap((prim) => [...prim.lines, ""]),
+    "    }",
+    "",
+    '    def Scope "Outputs"',
+    "    {",
+    ...outputPrims.flatMap((prim) => [...prim.lines, ""]),
+    "    }",
+    "}",
+    "",
+  ].join("\n");
+}
+
+export function generatedOutputFiles(outDir, additional = []) {
+  return inventory([
+    ...walk(outDir, (file) => {
+      const name = path.basename(file);
+      return !file.split(path.sep).some((segment) => segment.includes(".nomos-bak")) &&
+        !name.startsWith(".nomos_") &&
+        !name.startsWith(".nomos-mountability-proof.");
+    }),
+    ...additional,
+  ]);
+}
+
+export function writeCompileProof({ proofPath, inputs, outputs, name, domainHash, law }) {
+  if (!HASH.test(domainHash) || outputs.some((entry) => !HASH.test(entry.sha256))) {
+    throw new Error("compile proof requires content-addressed law and generated artifacts");
+  }
+  mkdirSync(path.dirname(proofPath), { recursive: true });
+  const temporary = `${proofPath}.tmp-${process.pid}`;
+  writeFileSync(temporary, emitCompileProof({ proofPath, inputs, outputs, name, domainHash, law }), "utf8");
+  renameSync(temporary, proofPath);
+}
+
+function property(text, name) {
+  const match = new RegExp(`custom uniform string nomos:${name} = "([0-9a-f]{64})"`, "u").exec(text);
+  return match?.[1];
+}
+
+function proofOutputs(text, proofPath) {
+  const outputsScope = /def Scope "Outputs"\s*\{([\s\S]*)\n    \}/u.exec(text)?.[1];
+  if (outputsScope === undefined) return undefined;
+  const entries = [];
+  const pattern = /def NomosCompileArtifact "[^"]+"\s*\{\s*custom uniform asset nomos:path = @([^@]+)@\s*custom uniform string nomos:sha256 = "([0-9a-f]{64})"\s*\}/gu;
+  for (const match of outputsScope.matchAll(pattern)) {
+    entries.push({ path: path.resolve(path.dirname(proofPath), match[1]), sha256: match[2] });
+  }
+  return entries.length === 0 ? undefined : entries;
+}
+
+export function readCompileProof({ proofPath, inputs }) {
+  let text;
+  try {
+    text = readFileSync(proofPath, "utf8");
+  } catch {
+    return undefined;
+  }
+  if (!text.includes('string "nomos:format" = "nomos.compile-proof.v1"')) return undefined;
+  if (
+    property(text, "authoringIdentity") !== inputs.authoringIdentity ||
+    property(text, "compilerIdentity") !== inputs.compilerIdentity ||
+    property(text, "argumentIdentity") !== inputs.argumentIdentity
+  ) return undefined;
+  const outputs = proofOutputs(text, proofPath);
+  if (outputs === undefined) return undefined;
+  for (const output of outputs) {
+    if (!existsSync(output.path) || !statSync(output.path).isFile()) return undefined;
+    if (sha256(readFileSync(output.path)) !== output.sha256) return undefined;
+  }
+  const packageMatch = /custom uniform string nomos:package = "([^"\\]*)"/u.exec(text);
+  const domainHash = property(text, "domainHash");
+  const lawMatch = /custom uniform asset nomos:law = @([^@]+)@/u.exec(text);
+  if (packageMatch === null || domainHash === undefined || lawMatch === null) return undefined;
+  return {
+    name: packageMatch[1],
+    domainHash,
+    law: path.resolve(path.dirname(proofPath), lawMatch[1]),
+    outputCount: outputs.length,
+  };
+}
+
+function emitPlanCompileProof({ proofPath, baseIdentity, runtimeSha256, plan, planSha256, inputs }) {
+  const proofDir = path.dirname(proofPath);
+  const inputPrims = inputs.map((entry) => artifactPrim("input", entry, proofDir));
+  return [
+    "#usda 1.0",
+    "(",
+    "    customLayerData = {",
+    '        string "nomos:format" = "nomos.plan-compile-proof.v1"',
+    "    }",
+    ")",
+    "",
+    'def NomosPlanCompileProof "PlanCompileProof"',
+    "{",
+    `    custom uniform string nomos:baseIdentity = "${baseIdentity}"`,
+    `    custom uniform string nomos:runtimeSha256 = "${runtimeSha256}"`,
+    `    custom uniform asset nomos:plan = @${path.relative(proofDir, plan).replaceAll(path.sep, "/")}@`,
+    `    custom uniform string nomos:planSha256 = "${planSha256}"`,
+    "    custom rel nomos:inputs = [",
+    ...inputPrims.map((prim, index) =>
+      `        </PlanCompileProof/Inputs/${prim.id}>${index + 1 === inputPrims.length ? "" : ","}`),
+    "    ]",
+    "",
+    '    def Scope "Inputs"',
+    "    {",
+    ...inputPrims.flatMap((prim) => [...prim.lines, ""]),
+    "    }",
+    "}",
+    "",
+  ].join("\n");
+}
+
+export function writePlanCompileProof({ proofPath, baseIdentity, runtimeSha256, plan, planSha256, inputs }) {
+  if (![baseIdentity, runtimeSha256, planSha256, ...inputs.map((entry) => entry.sha256)].every((value) => HASH.test(value))) {
+    throw new Error("plan compile proof requires content-addressed identities");
+  }
+  mkdirSync(path.dirname(proofPath), { recursive: true });
+  const temporary = `${proofPath}.tmp-${process.pid}`;
+  writeFileSync(
+    temporary,
+    emitPlanCompileProof({ proofPath, baseIdentity, runtimeSha256, plan, planSha256, inputs }),
+    "utf8",
+  );
+  renameSync(temporary, proofPath);
+}
+
+export function readPlanCompileProof({ proofPath, baseIdentity, runtimeSha256, digestFile }) {
+  let text;
+  try {
+    text = readFileSync(proofPath, "utf8");
+  } catch {
+    return undefined;
+  }
+  if (!text.includes('string "nomos:format" = "nomos.plan-compile-proof.v1"')) return undefined;
+  if (property(text, "baseIdentity") !== baseIdentity || property(text, "runtimeSha256") !== runtimeSha256) {
+    return undefined;
+  }
+  const inputsScope = /def Scope "Inputs"\s*\{([\s\S]*)\n    \}/u.exec(text)?.[1];
+  if (inputsScope === undefined) return undefined;
+  const inputs = [];
+  const inputPattern = /def NomosCompileInput "[^"]+"\s*\{\s*custom uniform asset nomos:path = @([^@]+)@\s*custom uniform string nomos:sha256 = "([0-9a-f]{64})"\s*\}/gu;
+  for (const match of inputsScope.matchAll(inputPattern)) {
+    inputs.push({ path: path.resolve(path.dirname(proofPath), match[1]), sha256: match[2] });
+  }
+  if (inputs.length === 0) return undefined;
+  for (const input of inputs) {
+    if (!existsSync(input.path) || (digestFile ?? ((file) => sha256(readFileSync(file))))(input.path) !== input.sha256) {
+      return undefined;
+    }
+  }
+  const planMatch = /custom uniform asset nomos:plan = @([^@]+)@/u.exec(text);
+  const planSha256 = property(text, "planSha256");
+  if (planMatch === null || planSha256 === undefined) return undefined;
+  const plan = path.resolve(path.dirname(proofPath), planMatch[1]);
+  if (!existsSync(plan)) return undefined;
+  const javascript = readFileSync(plan, "utf8");
+  if (sha256(javascript) !== planSha256) return undefined;
+  return { javascript, sha256: planSha256 };
+}
+
+export function writeKeyProofUsda(file, format, key) {
+  if (!HASH.test(key)) throw new Error(`invalid ${format} proof identity`);
+  const text = [
+    "#usda 1.0",
+    "(",
+    "    customLayerData = {",
+    `        string "nomos:format" = ${usdaString(format)}`,
+    `        string "nomos:proofIdentity" = "${key}"`,
+    "    }",
+    ")",
+    "",
+  ].join("\n");
+  writeFileSync(file, text, "utf8");
+}
+
+export function readKeyProofUsda(file, format) {
+  try {
+    const text = readFileSync(file, "utf8");
+    if (!text.includes(`string "nomos:format" = ${usdaString(format)}`)) return undefined;
+    return /string "nomos:proofIdentity" = "([0-9a-f]{64})"/u.exec(text)?.[1];
+  } catch {
+    return undefined;
+  }
+}

package/dart/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.64.2
+
+- Execute generated applications through the typed USDA-native kernel boundary, including native read
+  recipes, sealed offer diagnostics and lawful self-serve birth retries after typed kernel refusals.
+- Remove the legacy JSON deployment and bridge paths so tenant type errors continue to originate at the
+  kernel boundary used in production.
+
 ## 0.64.1
 
 - Resolve a compiled OpenUSD application as one ordered package set in generated offline and connected

package/dart/lib/src/dev_cloud.dart

@@ -5,7 +5,7 @@
 //
 // ```dart
 // final cloud = await NomosTestCloud.start(serverEntry: devServerPath);   // spawns the dev cloud + proxy
-// final harness = await NomosTestHarness.cloudBound(cloud: cloud, deployJsonPaths: [...], platformWorkspace: 'co2-platform', subject: 'user:test');
+// final harness = await NomosTestHarness.cloudBound(cloud: cloud, lawUsdzPaths: [...], platformWorkspace: 'co2-platform', subject: 'user:test');
 // // ... author offline ...
 // cloud.setOnline(false);              // PARTITION — the up leg can't reach custody
 // await harness.session('estate').sync(admit: true);   // stays local; nothing lands remotely
@@ -118,14 +118,14 @@ class NomosTestCloud {
     /// (the old lane — the harness POST-creating the platform — refuses 409 `unborn` by design).
     String? platform,
 
-    /// Optional single platform law to deploy at boot. Prefer [deployJsonPaths] for a composed application.
-    String? deployJsonPath,
+    /// Optional single platform law to deploy at boot. Prefer [lawUsdzPaths] for a composed application.
+    String? lawUsdzPath,
 
     /// Ordered application package set installed by the warranted bootstrap operator before serving.
     /// Reference-only/control packages go first and remain active on the parent; the home payload package
     /// goes last and is retained as the explicit law used to birth a receiving group. A payload package is
     /// not made current on the parent merely to make it available to a child.
-    List<String> deployJsonPaths = const [],
+    List<String> lawUsdzPaths = const [],
     Duration readyTimeout = const Duration(seconds: 30),
     void Function(String line)? onDiagnostic,
   }) async {
@@ -138,10 +138,10 @@ class NomosTestCloud {
       if (dataDir != null) ...['--data', dataDir],
       if (platform != null) ...['--platform', platform],
       for (final deploy in [
-        ...deployJsonPaths,
-        if (deployJsonPath != null && !deployJsonPaths.contains(deployJsonPath))
-          deployJsonPath,
-      ]) ...['--deploy', deploy],
+        ...lawUsdzPaths,
+        if (lawUsdzPath != null && !lawUsdzPaths.contains(lawUsdzPath))
+          lawUsdzPath,
+      ]) ...['--law', deploy],
     ];
     void log(String m) => onDiagnostic?.call('[nomos-test-cloud] $m');
     log('spawning: $node ${args.join(' ')}');

package/dart/lib/src/nms_generated_runtime.dart

@@ -8,6 +8,8 @@ import 'package:meta/meta.dart' show internal;
 
 export 'package:nomos_types/nomos_types.dart';
 export 'package:nomos_types/src/nomos_ref.dart' show NmsInternalNomosRefs;
+export 'package:nomos_types/src/versioned_nomos_ref.dart'
+    show NmsInternalVersionedNomosRefs;
 export 'package:nomos_types/src/invitation.dart'
     show NmsInternalInvitations, NmsInternalRecipients, NmsInternalUsers;
 export 'package:nomos_types/src/foreign_ref.dart'