@githolon/dsl 0.111.1 → 0.112.0

package/inspect_release.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// 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.
+
+// `githolon inspect-release` launcher — the twin of `compile_package.mjs`: resolve `tsx`
+// (the caller's, else the DSL's own dependency) and run `src/inspect_release_main.ts`
+// through its ESM loader in this process. Resolution goes through Node's
+// resolver (createRequire), NOT node_modules/.bin paths — hoisted/workspace installs
+// put the bin shims elsewhere.
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const DSL_DIR = path.dirname(fileURLToPath(import.meta.url));
+const MAIN = path.join(DSL_DIR, "src", "inspect_release_main.ts");
+
+function resolvePkgDir(name, fromDir) {
+  try {
+    const req = createRequire(pathToFileURL(path.join(fromDir, "noop.js")));
+    return path.dirname(req.resolve(`${name}/package.json`));
+  } catch {
+    return undefined;
+  }
+}
+
+const tsxDir = resolvePkgDir("tsx", process.cwd()) ?? resolvePkgDir("tsx", DSL_DIR);
+if (!tsxDir) {
+  console.error("githolon inspect-release: tsx not found — reinstall @githolon/dsl (tsx is one of its dependencies)");
+  process.exit(1);
+}
+const tsxApi = JSON.parse(readFileSync(path.join(tsxDir, "package.json"), "utf8")).exports?.["./esm/api"];
+const tsxApiEntry = path.join(
+  tsxDir,
+  (typeof tsxApi === "string" ? tsxApi : tsxApi?.import?.default ?? tsxApi?.import ?? tsxApi?.default) ?? "dist/esm/api/index.mjs"
+);
+
+const { register } = await import(pathToFileURL(tsxApiEntry).href);
+register();
+await import(pathToFileURL(MAIN).href);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.111.1",
+  "version": "0.112.0",
   "type": "module",
   "sideEffects": false,
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
@@ -60,7 +60,8 @@
     "compile_proof.d.mts",
     "compile_package.mjs",
     "check_package.mjs",
-    "lsp_server.mjs"
+    "lsp_server.mjs",
+    "inspect_release.mjs"
   ],
   "publishConfig": {
     "access": "public"
@@ -72,7 +73,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@githolon/runtime": "^0.111.1",
+    "@githolon/runtime": "^0.112.0",
     "@bufbuild/protobuf": "^2.13.0",
     "@bufbuild/protoc-gen-es": "^2.13.0",
     "esbuild": "0.24.2",

package/src/client_inventory_metadata.ts

@@ -0,0 +1,9 @@
+import { createHash } from 'node:crypto';
+
+/** Hash the exact generated consumer requirement bytes, independently of installed law. */
+export function dartClientInventoryMetadata(requirementsUsda: string): string {
+  const digest = createHash('sha256').update(requirementsUsda, 'utf8').digest('hex');
+  return `// GENERATED by nomos-compile. Observation identity only; not rollout approval.\n` +
+    `/// SHA-256 of this generated package's complete reception compatibility requirements.\n` +
+    `const String nomosReceptionRequirementsSha256 = '${digest}';\n`;
+}

package/src/compile_package_main.ts

@@ -337,6 +337,7 @@ import {
   encodeOpenUsdUsdc,
   flattenOpenUsdToUsda,
 } from "./openusd_compiled_layer.js";
+import { dartClientInventoryMetadata } from "./client_inventory_metadata.js";
 import { emitApplicationCompatibilityUsda } from "./compatibility_usda.js";
 
 const DSL_DIR = path.resolve(
@@ -2545,7 +2546,7 @@ const NOMOS_TYPES_DEP = "^0.11.3";
 //         DomainNotInstalledForSession, engine.follow, pendingConflicts lanes) — the generated client
 //         REQUIRES this surface. 0.48.1 fixes NomosSession.watchPendingConflicts delegation.
 const NOMOS_CLIENT_DEP = "^0.66.9";
-const NOMOS_FLUTTER_DEP = "^0.65.13";
+const NOMOS_FLUTTER_DEP = "^0.65.14";
 // DRIFT TRIPWIRE: pubspec_pins.test.ts asserts these equal the CURRENT versions in the Dart and Flutter
 // package pubspecs — a release without this bump fails the suite, so tenants never
 // land back in dependency_overrides (the exact co2 report this closes, third occurrence).
@@ -3836,6 +3837,9 @@ function emitDartPackages(
     );
     written.push(packageApplicationPath);
   }
+  const inventoryMetadata = path.join(clientGen, "client_inventory_metadata.dart");
+  writeFileSync(inventoryMetadata, dartClientInventoryMetadata(emitApplicationCompatibilityUsda(packageInterface)), "utf8");
+  written.push(inventoryMetadata);
   const clientBarrel = [
     "// GENERATED by nomos-compile — the CLIENT package's public entrypoint. DO NOT EDIT.",
     `/// The generated business application for ${describePackageName}.`,
@@ -3852,6 +3856,7 @@ function emitDartPackages(
     `/// are deliberately not exported here.`,
     "library;",
     "",
+    `export '${genRel}/client_inventory_metadata.dart' show nomosReceptionRequirementsSha256;`,
     `export 'package:${packages.types}/${genRel}/${businessSharedFile}';`,
     `export 'package:nomos_client/src/workspace_open_progress.dart' show ApplicationWorkspaceOpenProgress;`,
     `export 'package:nomos_client/src/write_progress.dart' show NomosWrite, NomosWriteProgress, NomosWritePhase;`,

package/src/inspect_release_main.ts

@@ -0,0 +1,17 @@
+import { inspectReleaseBaseline } from './release_inspection.js';
+const args = process.argv.slice(2);
+if (args.includes('--help')) {
+  console.log('githolon inspect-release --identity nomos.identity.usda --units build/app.units [--against prior.identity.usda] [--installed workspace.json]\nRead-only comparison. JSON to stdout; no admission or publication approval.');
+} else {
+  try {
+    const options: Record<string, string> = {};
+    for (let i = 0; i < args.length; i += 2) {
+      const key = args[i]?.replace(/^--/, '');
+      if (!key || !['identity', 'units', 'against', 'installed'].includes(key) || !args[i + 1] || options[key]) throw new Error('Invalid arguments; use --help');
+      options[key] = args[i + 1]!;
+    }
+    if (!options.identity || !options.units) throw new Error('--identity and --units are required');
+    console.log(JSON.stringify(inspectReleaseBaseline({ identity: options.identity, units: options.units,
+      ...(options.against ? { against: options.against } : {}), ...(options.installed ? { installed: options.installed } : {}) }), null, 2));
+  } catch (error) { console.error(`inspect-release: ${(error as Error).message}`); process.exitCode = 2; }
+}

package/src/law_units.ts

@@ -255,7 +255,7 @@ export function lawUnitHash(
   return hash.digest("hex");
 }
 
-function unitManifestUsda(unit: Omit<LawUnit, "manifest">): string {
+export function unitManifestUsda(unit: Omit<LawUnit, "manifest">): string {
   return [
     "#usda 1.0",
     "(",

package/src/release_inspection.ts

@@ -0,0 +1,147 @@
+/** Read-only evidence, not an evolution/admission judge. No compile, mint or network calls. */
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { parseIdentityUsda } from './identity_usda.js';
+import { identityRegistryFromModel } from './identity_model.js';
+import { canonicalJson } from './canonical_json.js';
+import { lawUnitHash, unitManifestUsda, type LawUnit } from './law_units.js';
+
+const sha = (bytes: string | Uint8Array) => createHash('sha256').update(bytes).digest('hex');
+const literal = '("(?:[^"\\\\]|\\\\.)*")';
+function attribute(source: string, name: string): string {
+  const values = [...source.matchAll(new RegExp(`nomos:${name} = ${literal}`, 'g'))];
+  if (values.length !== 1) throw new Error(`Expected one nomos:${name}`);
+  return JSON.parse(values[0]![1]!);
+}
+function files(directory: string, root = directory): string[] {
+  return readdirSync(directory).sort().flatMap(name => {
+    const file = path.join(directory, name);
+    const stat = lstatSync(file);
+    if (stat.isSymbolicLink()) throw new Error(`Symlinks are not accepted in unit exports: ${file}`);
+    return stat.isDirectory() ? files(file, root) : [path.relative(root, file).split(path.sep).join('/')];
+  });
+}
+/** Accept the compiler's canonical manifest dialect, verify every byte with the existing hasher,
+ * and round-trip the manifest through its existing emitter. Never interpret a general USD stage. */
+export function readInspectionUnits(directory: string): LawUnit[] {
+  const keys = new Set<string>();
+  const units = readdirSync(directory).sort().map(name => {
+    const root = path.join(directory, name);
+    if (!lstatSync(root).isDirectory() || lstatSync(root).isSymbolicLink()) throw new Error('Expected unit directories');
+    const allFiles = files(root);
+    const source = readFileSync(path.join(root, 'unit.usda'), 'utf8');
+    const key = attribute(source, 'unit');
+    const kind = attribute(source, 'unitKind') as LawUnit['kind'];
+    const hash = attribute(source, 'unitHash');
+    if (!['domain', 'framework', 'composition'].includes(kind) || keys.has(key)) throw new Error('Invalid or duplicate unit key');
+    keys.add(key);
+    const domain = kind === 'domain' ? attribute(source, 'domain') : undefined;
+    if (key !== (domain === undefined ? kind : `domain:${domain}`)) throw new Error('Unit key/kind disagreement');
+    const assets = [...source.matchAll(/def NomosLawAsset "[^"]+"\s*\{([^}]+)\}/g)].map(match => {
+      const logicalPath = attribute(match[1]!, 'logicalPath');
+      if (logicalPath.startsWith('/') || logicalPath.split('/').some(p => p === '..' || p === '.' || !p) || logicalPath.includes('\\')) throw new Error('Unsafe unit asset path');
+      const file = path.join(root, logicalPath);
+      if (!realpathSync(file).startsWith(realpathSync(root) + path.sep)) throw new Error('Asset escaped unit');
+      const bytes = readFileSync(file);
+      const sha256 = attribute(match[1]!, 'sha256');
+      if (sha(bytes) !== sha256) throw new Error(`Asset digest mismatch: ${key}/${logicalPath}`);
+      return { logicalPath, sha256, bytes };
+    });
+    const routes = [...source.matchAll(/def NomosLawRoute "[^"]+"\s*\{([^}]+)\}/g)].map(match => ({
+      selector: attribute(match[1]!, 'selector'), planSha256: attribute(match[1]!, 'plan'),
+    }));
+    if (new Set(assets.map(a => a.logicalPath)).size !== assets.length || new Set(routes.map(r => r.selector)).size !== routes.length) throw new Error('Duplicate manifest entry');
+    if (JSON.stringify(allFiles) !== JSON.stringify([...assets.map(a => a.logicalPath), 'unit.usda'].sort())) throw new Error('Manifest file inventory mismatch');
+    const unit = { key, kind, ...(domain === undefined ? {} : { domain }), hash, assets, routes };
+    if (lawUnitHash(key, assets, routes) !== hash) throw new Error(`Unit digest mismatch: ${key}`);
+    if (Buffer.from(unitManifestUsda(unit)).toString('utf8') !== source) throw new Error('Unsupported noncanonical unit manifest');
+    return { ...unit, manifest: Buffer.from(source) };
+  });
+  if (!units.length) throw new Error('No compiled units');
+  return units;
+}
+
+export function inspectReleaseBaseline(input: { identity: string; units: string; against?: string; installed?: string }) {
+  const identityBytes = readFileSync(input.identity, 'utf8');
+  const model = parseIdentityUsda(identityBytes);
+  const registry = identityRegistryFromModel(model);
+  const units = readInspectionUnits(input.units);
+  const changes: { entity: string; change: string }[] = [];
+  let baseline: { sha256: string; hasIdentityRegistry: boolean } | null = null;
+  if (input.against) {
+    const bytes = readFileSync(input.against, 'utf8');
+    const priorModel = parseIdentityUsda(bytes);
+    baseline = { sha256: sha(bytes), hasIdentityRegistry: priorModel.identity !== undefined };
+    const prior = identityRegistryFromModel(priorModel);
+    for (const key of [...new Set([...Object.keys(prior.entities), ...Object.keys(registry.entities)])].sort()) {
+      const before = prior.entities[key], after = registry.entities[key];
+      if (!before) changes.push({ entity: key, change: 'added' });
+      else if (!after) changes.push({ entity: key, change: 'missing-continuity' });
+      else if (canonicalJson(before) !== canonicalJson(after)) changes.push({ entity: key, change: 'changed-identity-metadata' });
+    }
+  }
+  // Evidence from the compiler's emitted declarations only. Structural anonymous fields may have
+  // different prim prefixes from their registry kind, so operation fields match by SID + wire key.
+  const declarations = new Map<string, { label?: string; wire?: string; aliases?: string[] }[]>();
+  for (const unit of units) for (const asset of unit.assets) {
+    if (!/^domains\/.*\.usda$/.test(asset.logicalPath) && asset.logicalPath !== 'framework.usda') continue;
+    const source = Buffer.from(asset.bytes).toString('utf8');
+    for (const match of source.matchAll(/def \w+ "([a-z]_([a-f0-9]{16}))"\s*\{([\s\S]*?)(?=\n\s*(?:def |over |\}))/g)) {
+      const attrs = match[3]!;
+      const label = /nomos:label = ("(?:[^"\\]|\\.)*")/.exec(attrs);
+      const wire = /nomos:wireKey = ("(?:[^"\\]|\\.)*")/.exec(attrs);
+      const aliases = /nomos:wireAliases = (\[[^\n]*\])/.exec(attrs);
+      const item = { ...(label ? { label: JSON.parse(label[1]!) as string } : {}),
+        ...(wire ? { wire: JSON.parse(wire[1]!) as string } : {}),
+        ...(aliases ? { aliases: JSON.parse(aliases[1]!) as string[] } : {}) };
+      for (const key of [match[1]!, ...(wire ? [`u_${match[2]!}`] : [])]) {
+        declarations.set(key, [...(declarations.get(key) ?? []), item]);
+      }
+    }
+  }
+  const compiledIdentity = { observed: 0, unobserved: 0, differences: [] as { entity: string; reason: string }[] };
+  for (const [key, entity] of Object.entries(registry.entities)) {
+    const seen = declarations.get(key);
+    if (!seen) { compiledIdentity.unobserved++; continue; }
+    compiledIdentity.observed++;
+    if (!seen.some(row => row.label === entity.label || entity.priorLabels?.includes(row.label ?? ''))) {
+      compiledIdentity.differences.push({ entity: key, reason: 'label-disagreement' });
+    }
+    const wire = entity.operationFieldWire?.protobuf;
+    if (wire && !seen.some(row => row.wire === wire.canonical && canonicalJson([...(row.aliases ?? [])].sort()) === canonicalJson([...(wire.aliases ?? [])].sort()))) {
+      compiledIdentity.differences.push({ entity: key, reason: 'wire-allocation-disagreement' });
+    }
+  }
+  let installed: null | { sha256: string; workspace: string; head: string; declarationCoverage: 'unknown' | 'observed'; comparisons: { closure: string; units: { key: string; status: string; compiled: string; installed: string | null }[] }[] | null } = null;
+  if (input.installed) {
+    const bytes = readFileSync(input.installed, 'utf8');
+    const value = JSON.parse(bytes);
+    // A console /v1/universe/workspaces/:name export. Identity is an observation of that response,
+    // not an attestation. Never confuse a client assertion with verified kernel custody.
+    const view = value.workspace ?? value;
+    const closures = view.law?.closures;
+    if (typeof view.name !== 'string' || typeof view.head !== 'string' || !view.head || (closures !== null && !Array.isArray(closures))) throw new Error('Expected a console workspace export with head and law.closures');
+    installed = { sha256: sha(bytes), workspace: view.name, head: view.head,
+      declarationCoverage: closures === null ? 'unknown' : 'observed',
+      comparisons: closures === null ? null : closures.map((closure: { closureIdentity: string; unitSet?: { units: { key: string; hash: string }[] } | null }) => {
+        if (typeof closure.closureIdentity !== 'string') throw new Error('Invalid closure');
+        const known = new Map((closure.unitSet?.units ?? []).map(row => {
+          if (typeof row.key !== 'string' || !/^[a-f0-9]{64}$/.test(row.hash)) throw new Error('Invalid installed unit');
+          return [row.key, row.hash];
+        }));
+        return { closure: closure.closureIdentity, units: units.map(unit => ({ key: unit.key, compiled: unit.hash,
+          installed: known.get(unit.key) ?? null,
+          status: !known.has(unit.key) ? 'unknown' : known.get(unit.key) === unit.hash ? 'identical' : 'different' })) };
+      }) };
+  }
+  return { schema: 'nomos.release-inspection.v1', admission: 'not-evaluated',
+    identity: { sha256: sha(identityBytes), hasIdentityRegistry: model.identity !== undefined,
+      active: Object.values(registry.entities).filter(e => e.status === 'active').length,
+      retired: Object.values(registry.entities).filter(e => e.status === 'retired').length },
+    baseline, changes, compiledIdentity,
+    units: units.map(({ key, hash }) => ({ key, hash })), installed,
+    unknown: ['Installed law does not establish complete authoring lineage (prior names, generations and all retirements).',
+      'Unobserved declarations may be out of package scope or structurally interned; absence is not a compatibility refusal.',
+      'Consumer compatibility, state evolution and publication provenance are not certified by this report.'] };
+}