@githolon/dsl 0.105.5 → 0.105.6

package/src/check_package_main.ts

@@ -10,7 +10,7 @@
  * discovery), runs {@link checkDomainModules}, prints the unified report, and exits
  * non-zero on any REFUSE-level finding. `compile` runs the same twins implicitly.
  */
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
@@ -22,12 +22,14 @@ import { LawSourceMap } from "./law_source_map.js";
 import {
   currentEvolveLaw,
   evolveDiff,
-  evolveLawFromInterface,
   evolveLawFromLockfile,
   type EvolveLaw,
-  type StableIdLockfile,
+  type CompilerIdentityModel,
 } from "./evolve_preview.js";
-import { parseStableIdLockfile } from "./stable_id_lockfile.js";
+import {
+  NOMOS_IDENTITY_FILENAME,
+  parseIdentityUsda,
+} from "./identity_usda.js";
 import {
   validateNomosPackageConfig,
   type NormalizedNomosPackageConfig,
@@ -136,77 +138,46 @@ export async function loadComposedModulesWithSources(
 }
 
 /**
- * Load the PRIOR law surface for `--against <path>` (the evolve preview's baseline). The supported
- * prior is a diagnostic `build/<name>.interface.json`, a BUILD DIR / package dir containing one, or
- * the committed `nomos.stable-ids.json` LOCKFILE (aggregate identity only — no directive payloads).
- * A live `https://…` prior is NOT supported (the installed package's stable-ids aren't retrievable
- * from GET /domains); point `--against` at the deployed source's interface and lock sidecars instead.
+ * Load the PRIOR identity surface for `--against <path>` (the evolve preview's baseline). The one
+ * supported artifact is the committed `nomos.identity.usda` layer, directly or via its package dir.
+ * There is no interface/JSON sidecar lane: prior executable-law inspection belongs to the holon.
  */
 function loadPriorEvolveLaw(arg: string): { law: EvolveLaw; source: string; note?: string } {
   if (/^https?:\/\//.test(arg)) {
     fail(
       `--against does not support a live URL (${arg}) — the installed package's #58 stable-ids are ` +
-        `not retrievable from GET /domains. Point --against at the deployed source's build/<name>.interface.json.`,
+      `not retrievable from GET /domains. Point --against at the deployed source's ${NOMOS_IDENTITY_FILENAME}.`,
     );
   }
   const abs = path.resolve(process.cwd(), arg);
   if (!existsSync(abs)) fail(`--against: prior not found: ${abs}`);
-  // Resolve a directory to its diagnostic interface or stable-id lockfile.
+  // Resolve a directory to its one committed identity layer.
   let file = abs;
   if (statSync(abs).isDirectory()) {
-    const iface = findInterfaceJson(abs);
-    const lock = path.join(abs, "nomos.stable-ids.json");
-    if (iface !== undefined) file = iface;
-    else if (existsSync(lock)) file = lock;
-    else fail(`--against: no *.interface.json or nomos.stable-ids.json under ${abs}`);
+    const identity = path.join(abs, NOMOS_IDENTITY_FILENAME);
+    if (existsSync(identity)) file = identity;
+    else fail(`--against: no ${NOMOS_IDENTITY_FILENAME} under ${abs}`);
   }
-  let parsed: unknown;
+  let lock: CompilerIdentityModel;
   try {
-    parsed = JSON.parse(readFileSync(file, "utf8"));
+    lock = parseIdentityUsda(readFileSync(file, "utf8"));
   } catch (e) {
     fail(`--against: could not parse ${file}: ${(e as Error).message}`);
   }
-  if (path.basename(file) === "nomos.stable-ids.json") {
-    return {
-      law: evolveLawFromLockfile(parseStableIdLockfile(parsed)),
-      source: file,
-      note: `prior is a lockfile — aggregate/field identity is diffed, but directive payload changes require the sibling interface sidecar.`,
-    };
-  }
-  const lockCandidates = [
-    path.join(path.dirname(file), "nomos.stable-ids.json"),
-    path.join(path.dirname(path.dirname(file)), "nomos.stable-ids.json"),
-  ];
-  const lockFile = lockCandidates.find((candidate) => existsSync(candidate));
-  const lock = lockFile === undefined
-    ? undefined
-    : parseStableIdLockfile(JSON.parse(readFileSync(lockFile, "utf8")));
   return {
-    law: evolveLawFromInterface(parsed as Parameters<typeof evolveLawFromInterface>[0], lock),
-    source: lockFile === undefined ? file : `${file} + ${lockFile}`,
-    ...(lockFile === undefined
-      ? { note: `prior has no stable-id lock beside it — directive shapes are checked, but driver and contract evolution evidence is incomplete.` }
-      : {}),
-  };
-}
-
-/** Find a compiler diagnostic `*.interface.json` directly or one level down in `build/`. */
-function findInterfaceJson(dir: string): string | undefined {
-  const scan = (d: string): string | undefined => {
-    if (!existsSync(d)) return undefined;
-    const hit = readdirSync(d).find((f) => f.endsWith(".interface.json"));
-    return hit !== undefined ? path.join(d, hit) : undefined;
+    law: evolveLawFromLockfile(lock),
+    source: file,
+    note: `prior identity is diffed by stable id; directive payload compatibility is negotiated from installed USDA by the holon, never a sidecar.`,
   };
-  return scan(dir) ?? scan(path.join(dir, "build"));
 }
 
-/** Read the committed `nomos.stable-ids.json` lockfile beside the config (the CURRENT identity). */
-function loadCwdLockfile(configArg: string): StableIdLockfile | undefined {
+/** Read the committed typed identity layer beside the config (the CURRENT identity). */
+function loadCwdLockfile(configArg: string): CompilerIdentityModel | undefined {
   const cfgDir = path.dirname(path.resolve(process.cwd(), configArg));
-  const lockPath = path.join(cfgDir, "nomos.stable-ids.json");
+  const lockPath = path.join(cfgDir, NOMOS_IDENTITY_FILENAME);
   if (!existsSync(lockPath)) return undefined;
   try {
-    return parseStableIdLockfile(JSON.parse(readFileSync(lockPath, "utf8")));
+    return parseIdentityUsda(readFileSync(lockPath, "utf8"));
   } catch {
     return undefined;
   }
@@ -233,12 +204,12 @@ async function main(): Promise<void> {
   let evolveDispositions: Record<string, unknown> | undefined;
   if (againstIdx >= 0 || againstArg !== undefined) {
     if (againstArg === undefined || againstArg.startsWith("--")) {
-      fail(`--against needs a path: --against <build/<name>.interface.json | build dir | nomos.stable-ids.json>`);
+      fail(`--against needs a path: --against <${NOMOS_IDENTITY_FILENAME} | package dir>`);
     }
     const lock = loadCwdLockfile(configArg);
     if (lock === undefined && !asJson) {
       console.log(
-        "githolon check: --against — no nomos.stable-ids.json in the config dir; the current law's stable ids " +
+        `githolon check: --against — no ${NOMOS_IDENTITY_FILENAME} in the config dir; the current law's stable ids ` +
           "fall back to NAMES (a rename would read as removal+add). Run `githolon compile` first for a sid-accurate preview.",
       );
     }

package/src/codegen_ts.ts

@@ -4078,6 +4078,13 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       `    (holon, user) => _nomosBind${applicationName}(holon as NomosHolon, user),`,
       `  );`,
       `}`,
+      ...(clientInterface === undefined
+        ? []
+        : [
+            `// Compiler tooling compares the requirement carried by the client that will actually ship.`,
+            `// A global symbol keeps this off tenant autocomplete while avoiding a duplicate sidecar.`,
+            `Object.defineProperty(${applicationOpener}, Symbol.for("nomos.generated-interface"), { value: ${interfaceConstName(opts.packageName)}, enumerable: false });`,
+          ]),
       ``,
     );
   }

package/src/compat_package_main.ts

@@ -5,17 +5,17 @@
 /**
  * `githolon compat <target> [--config …] [--domain …] [--json]` — THE CI GATE (task #31, the compat superpower).
  *
- * Compares the CURRENT build's structural interface (`build/<name>.interface.json`, the client's
- * REQUIREMENT) against a TARGET's installed law (the workspace OFFER), PER MEMBER, via the #72
+ * Compares the CURRENT generated client's carried structural REQUIREMENT against a TARGET's
+ * installed law (the workspace OFFER), PER MEMBER, via the #72
  * subtype relation (`memberVerdicts`). Exits NON-ZERO on any incompatible member — so a client/law
  * mismatch is caught in CI, before it ships. The target is:
- *   • an `.interface.json` (or a build/package DIR containing one) — the diagnostic offer directly;
+ *   • a generated `.client.mjs` (or a build/package DIR containing one);
  *   • a LIVE workspace URL (`https://host/v2/workspaces/<ws>` or `https://host --workspace <ws>`) —
  *     connect()s and reads the on-ledger offer (`holon.interfaceOffer()`).
  *
  * Human report by default; `--json` emits the machine surface (the per-member array + verdict).
  */
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, statSync } from "node:fs";
 import path from "node:path";
 
 import { memberVerdicts, type DomainInterface, type MemberVerdict } from "./shape_compat.js";
@@ -41,7 +41,7 @@ function mergeInterfaces(byDomain: InterfaceMap | undefined): DomainInterface {
   return out;
 }
 
-/** The package name from `nomos.project.ts` (only field we need — to locate `build/<name>.interface.json`). */
+/** The package name from `nomos.project.ts` (only field we need — to locate its generated client). */
 async function loadPackageName(configArg: string): Promise<{ name: string; dir: string }> {
   const configPath = path.resolve(process.cwd(), configArg);
   if (!existsSync(configPath)) fail(`config not found: ${configPath} (pass the package config, or run from the package dir)`);
@@ -51,45 +51,51 @@ async function loadPackageName(configArg: string): Promise<{ name: string; dir:
   return { name: cfg.name, dir: path.dirname(configPath) };
 }
 
-/** The CURRENT build's interface — `build/<name>.interface.json`. Requires a prior `githolon compile`. */
-function loadCurrentInterface(pkgDir: string, name: string): InterfaceMap {
-  const p = path.join(pkgDir, "build", `${name}.interface.json`);
+const GENERATED_INTERFACE = Symbol.for("nomos.generated-interface");
+
+async function loadClientRequirement(file: string): Promise<InterfaceMap> {
+  const { pathToFileURL } = await import("node:url");
+  let generated: Record<string, unknown>;
+  try {
+    generated = await import(`${pathToFileURL(file).href}?compat=${Date.now()}`) as Record<string, unknown>;
+  } catch (error) {
+    fail(`could not load generated client ${file}: ${(error as Error).message}`);
+  }
+  for (const value of Object.values(generated)) {
+    if (typeof value !== "function") continue;
+    const requirement = (value as unknown as Record<PropertyKey, unknown>)[GENERATED_INTERFACE];
+    if (requirement !== null && typeof requirement === "object") return requirement as InterfaceMap;
+  }
+  fail(`generated client ${file} carries no Nomos structural requirement; recompile it with the current @githolon/dsl`);
+}
+
+/** The CURRENT requirement carried by the generated client that will ship. */
+async function loadCurrentInterface(pkgDir: string, name: string): Promise<InterfaceMap> {
+  const p = path.join(pkgDir, "build", `${name}.client.mjs`);
   if (!existsSync(p)) {
     fail(
-      `no current interface at ${p} — run \`githolon compile\` first so the build carries the structural interface this checks.`,
+      `no current generated client at ${p} — run \`githolon compile\` first.`,
     );
   }
-  try {
-    return JSON.parse(readFileSync(p, "utf8")) as InterfaceMap;
-  } catch (e) {
-    fail(`could not parse ${p}: ${(e as Error).message}`);
-  }
+  return loadClientRequirement(p);
 }
 
-/** Read a TARGET diagnostic offer from an interface.json / directory. */
-function loadFileOffer(arg: string): { offer: InterfaceMap; source: string } {
+/** Read a TARGET requirement from the generated client it will ship. */
+async function loadFileOffer(arg: string): Promise<{ offer: InterfaceMap; source: string }> {
   const abs = path.resolve(process.cwd(), arg);
   if (!existsSync(abs)) fail(`target not found: ${abs}`);
   let file = abs;
   if (statSync(abs).isDirectory()) {
     const scan = (d: string): string | undefined => {
       if (!existsSync(d)) return undefined;
-      const hit = readdirSync(d).find((f) => f.endsWith(".interface.json"));
+      const hit = readdirSync(d).find((f) => f.endsWith(".client.mjs"));
       return hit !== undefined ? path.join(d, hit) : undefined;
     };
     const found = scan(abs) ?? scan(path.join(abs, "build"));
-    if (found === undefined) fail(`no *.interface.json under ${abs}`);
+    if (found === undefined) fail(`no *.client.mjs under ${abs}`);
     file = found;
   }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(readFileSync(file, "utf8"));
-  } catch (e) {
-    fail(`could not parse ${file}: ${(e as Error).message}`);
-  }
-  const offer = parsed as InterfaceMap;
-  if (offer === null || typeof offer !== "object") fail(`target ${file} carries no structural interface`);
-  return { offer, source: file };
+  return { offer: await loadClientRequirement(file), source: file };
 }
 
 /** Read a LIVE workspace's on-ledger offer through the compiler-private runtime bundled with the DSL. */
@@ -155,10 +161,10 @@ async function main(): Promise<void> {
   // The positional target = the first non-flag arg that isn't a flag VALUE.
   const flagsWithVals = new Set(["--config", "--workspace", "--domain"]);
   const target = argv.find((a, i) => !a.startsWith("--") && !(i > 0 && flagsWithVals.has(argv[i - 1]!)));
-  if (!target) fail(`usage: githolon compat <workspace-url | interface.json | dir> [--config <cfg>] [--workspace <ws>] [--domain <name,...>] [--json]`);
+  if (!target) fail(`usage: githolon compat <workspace-url | client.mjs | dir> [--config <cfg>] [--workspace <ws>] [--domain <name,...>] [--json]`);
 
   const { name, dir } = await loadPackageName(configArg);
-  const allCurrent = loadCurrentInterface(dir, name);
+  const allCurrent = await loadCurrentInterface(dir, name);
   const requestedDomains = domainFlag?.split(",").map((domain) => domain.trim()).filter(Boolean) ?? [];
   for (const domain of requestedDomains) {
     if (allCurrent[domain] === undefined) fail(`current package '${name}' has no domain '${domain}'`);
@@ -169,7 +175,7 @@ async function main(): Promise<void> {
 
   const { offer, source } = /^https?:\/\//.test(target)
     ? await loadLiveOffer(target, workspaceFlag)
-    : loadFileOffer(target);
+    : await loadFileOffer(target);
 
   // The subtype check is PER MEMBER over the merged interfaces (directives keyed by id, aggregates by label).
   const verdicts = memberVerdicts(mergeInterfaces(current), mergeInterfaces(offer));

package/src/compile_package_main.ts

@@ -145,11 +145,14 @@ import {
   type StableIds,
 } from "./stable_ids.js";
 import {
-  identityRegistryFromStableIdLockfile,
-  parseStableIdLockfile,
-  serializeStableIdLockfile,
-  type StableIdLockfile,
-} from "./stable_id_lockfile.js";
+  identityRegistryFromModel,
+  type CompilerIdentityModel,
+} from "./identity_model.js";
+import {
+  NOMOS_IDENTITY_FILENAME,
+  parseIdentityUsda,
+  serializeIdentityUsda,
+} from "./identity_usda.js";
 import { reconcileStableIdsWithIdentity } from "./stable_id_identity_bridge.js";
 import { discoverLawGraph, type LawGraph } from "./law_graph.js";
 import { emitFrameworkLawUsda, emitSparseLawGraphUsda } from "./law_graph_usda.js";
@@ -657,7 +660,7 @@ function firstLawDifference(expected: unknown, actual: unknown, at = "$law"): st
 // ── decl auto-discovery (by SHAPE, mirroring the engine entry's duck-types) ───────
 // The query/workspace-invariant/spatial/sum/count predicates + `discover` live in the SHARED
 // bundle-safe `decl_shapes.ts` (imported above) — the lump's self-describe verb discovers by the
-// EXACT same shape so the kernel-served OpenAPI matches the compiled `<name>.openapi.json`.
+// EXACT same shape so the kernel-served OpenAPI is a deterministic projection of installed law.
 
 function isDerivedDecl(v: unknown): v is DerivedDecl {
   return (
@@ -1590,8 +1593,8 @@ function emitDart(
     // The generated clients import their runtime support directly. Keeping it out of the public barrel is
     // the surface firewall: a tenant import receives business types and application APIs, never raw runtime.
     supportImport === "vendored"
-      ? `export '${genRel}/src/${VENDORED_TYPES_SHIM}' show NomosRef, NomosOptionalRef, VersionedNomosRef, ReferenceVersionStatus, ReferenceVersionCurrent, ReferenceVersionOutdated, ReferenceVersionUnavailable${sha256DigestExport}${gitObjectIdExport};`
-      : `export 'package:nomos_types/nomos_types.dart' show NomosRef, NomosOptionalRef, VersionedNomosRef, ReferenceVersionStatus, ReferenceVersionCurrent, ReferenceVersionOutdated, ReferenceVersionUnavailable${sha256DigestExport}${gitObjectIdExport};`,
+      ? `export '${genRel}/src/${VENDORED_TYPES_SHIM}' show NomosRef, NomosOptionalRef, NomosSlot, VersionedNomosRef, ReferenceVersionStatus, ReferenceVersionCurrent, ReferenceVersionOutdated, ReferenceVersionUnavailable${sha256DigestExport}${gitObjectIdExport};`
+      : `export 'package:nomos_types/nomos_types.dart' show NomosRef, NomosOptionalRef, NomosSlot, VersionedNomosRef, ReferenceVersionStatus, ReferenceVersionCurrent, ReferenceVersionOutdated, ReferenceVersionUnavailable${sha256DigestExport}${gitObjectIdExport};`,
     ...(contractsImportUri !== undefined
       ? tenantDartExport(`${genRel}/${CONTRACTS_FILE}.dart`, sourceByFile.get(CONTRACTS_FILE) ?? "")
       : []),
@@ -1653,12 +1656,12 @@ const dartTypesImportFor = (generatedSource: string): string => {
  *  just the floor generated code needs — a lagging pin forces tenants into dependency_overrides. */
 // 0.3.0: SurfacedValue<T>/SurfacedObservation/PendingConflictRow — generated Surfaced-field typing +
 //        the pendingConflicts read rows.
-const NOMOS_TYPES_DEP = "^0.8.6";
+const NOMOS_TYPES_DEP = "^0.8.7";
 // 0.48.x: session-bound clients (XClient.bind/NomosClientInterface/DomainClientSessionMismatch/
 //         DomainNotInstalledForSession, engine.follow, pendingConflicts lanes) — the generated client
 //         REQUIRES this surface. 0.48.1 fixes NomosSession.watchPendingConflicts delegation.
-const NOMOS_CLIENT_DEP = "^0.64.20";
-const NOMOS_FLUTTER_DEP = "^0.63.31";
+const NOMOS_CLIENT_DEP = "^0.64.23";
+const NOMOS_FLUTTER_DEP = "^0.63.44";
 // DRIFT TRIPWIRE: pubspec_pins.test.ts asserts these equal the CURRENT versions in dsl/dart/pubspec.yaml
 // and dsl/dart_types/pubspec.yaml — a Dart release without this bump fails the suite, so tenants never
 // land back in dependency_overrides (the exact co2 report this closes, third occurrence).
@@ -2403,7 +2406,7 @@ function emitDartPackages(
     businessSharedPath,
     [
       "// GENERATED by nomos-compile — shared business values and activity; no runtime machinery.",
-      `export 'package:nomos_types/nomos_types.dart' show NomosRef, NomosOptionalRef, VersionedNomosRef, ReferenceVersionStatus, ReferenceVersionCurrent, ReferenceVersionOutdated, ReferenceVersionUnavailable${sha256DigestExport}${gitObjectIdExport}, Identity, User, Recipient, Invitation, ActivityEvent, ActivityRef, ActivitySeverity, SurfacedObservation, SurfacedValue, SurfacedResolved, SurfacedPending, SurfacedEvolutionRequired;`,
+      `export 'package:nomos_types/nomos_types.dart' show NomosRef, NomosOptionalRef, NomosSlot, VersionedNomosRef, ReferenceVersionStatus, ReferenceVersionCurrent, ReferenceVersionOutdated, ReferenceVersionUnavailable${sha256DigestExport}${gitObjectIdExport}, Identity, User, Recipient, Invitation, ActivityEvent, ActivityRef, ActivitySeverity, SurfacedObservation, SurfacedValue, SurfacedResolved, SurfacedPending, SurfacedEvolutionRequired;`,
       ...(sharedBusinessTypeNames.length === 0
         ? []
         : [`export '${FRAMEWORK_FILE}.dart' show ${sharedBusinessTypeNames.join(", ")};`]),
@@ -3021,6 +3024,8 @@ async function main(): Promise<void> {
     `${cfg.name}.layered.usda`,
     `${cfg.name}.law-closure.json`,
     `${cfg.name}.deploy.json`,
+    `${cfg.name}.interface.json`,
+    `${cfg.name}.openapi.json`,
   ]) rmSync(path.join(outDir, retired), { force: true });
   for (const retiredDir of ["layers", "v3-layers", `${cfg.name}.relation-layers`]) {
     rmSync(path.join(outDir, retiredDir), { recursive: true, force: true });
@@ -3069,7 +3074,7 @@ async function main(): Promise<void> {
   // lump's `globalThis.describe` needs that it cannot rediscover by shape alone (mins/maxes are
   // config-named; sharding sums are framework-appended). Plain JSON (finishCount/Sum/Extremum
   // pass finished decls through), serialized into the generated entry as `openapiDecls`, so the
-  // kernel-run describe reproduces THIS compile's `<name>.openapi.json` byte-for-byte.
+  // kernel-run describe reproduces this compile's public description deterministically.
   const openapiDeclsByDomain: Record<string, unknown> = {};
   // A tenant module may import declarations from another configured law module (business-birth
   // composition is the common case). Ordinary ES evaluation then initializes that entire closure
@@ -3738,25 +3743,25 @@ async function main(): Promise<void> {
 
   // ── STABLE-ID CONTINUITY (#58 — names are labels, identity is minted) ──
   // Derive each composed domain's stable ids from the PRIOR compile: the committed
-  // `nomos.stable-ids.json` lockfile beside the config (the durable source — survives
+  // `nomos.identity.usda` layer beside the config (the durable source — survives
   // a clean clone), else the previous build's identity manifests. Match by name;
   // exactly ONE disappeared + ONE appeared name of the same kind/shape is an inferred
   // RENAME (sid carried, lineage recorded, printed below); anything else mints fresh
   // at first appearance (a leftover disappearance is THE EVOLVE GATE's typed question
   // at deploy — answered in the upgrade intent's disposition). The resolved continuity
   // is attached to the module so the canonical manifest + USD-IR carry it.
-  const lockPath = path.join(cfgDir, "nomos.stable-ids.json");
-  const priorLock: StableIdLockfile | undefined = existsSync(lockPath)
-    ? parseStableIdLockfile(JSON.parse(readFileSync(lockPath, "utf8")))
+  const lockPath = path.join(cfgDir, NOMOS_IDENTITY_FILENAME);
+  const priorLock: CompilerIdentityModel | undefined = existsSync(lockPath)
+    ? parseIdentityUsda(readFileSync(lockPath, "utf8"))
     : undefined;
   const inferredRenames: { domain: string; renames: InferredRename[] }[] = [];
-  let nextIdentity = identityRegistryFromStableIdLockfile(priorLock);
+  let nextIdentity = identityRegistryFromModel(priorLock);
   const typedLawGraphs = new Map<string, LawGraph>();
   // The lock is project-wide, not package-local. Several package configs commonly live beside one
   // application stage; compiling one must not erase the stable identity of domains owned by its siblings.
   // Current package domains are replaced below, while absent domains remain only as continuity metadata
   // and never leak into this package's interface, law, clients or deployment.
-  const nextLock: StableIdLockfile = {
+  const nextLock: CompilerIdentityModel = {
     v: 1,
     domains: { ...(priorLock?.domains ?? {}) },
     identity: nextIdentity,
@@ -3790,7 +3795,7 @@ async function main(): Promise<void> {
       // it carries no stable ids either.
       continue;
     }
-    // Continuity source: the committed nomos.stable-ids.json lockfile (the canonical identity ledger).
+    // Continuity source: the committed nomos.identity.usda layer (the canonical identity ledger).
     // (The old "else the prior build's domain_identity_manifests.json" fallback is gone with that sidecar.)
     let prior: StableIds | undefined;
     let priorSchemas: Record<string, WireSchema> | undefined;
@@ -3886,11 +3891,11 @@ async function main(): Promise<void> {
       schemas: Object.fromEntries(currentAggs.map((a) => [a.id, a.schema])),
     };
   }
-  // Persist the lockfile (commit it with the law: it is how a rename keeps its
+  // Persist the typed identity layer (commit it with the law: it is how a rename keeps its
   // identity across clean clones). Existing project-domain order is retained, so once sibling
   // packages are registered, recompiling them in any order rewrites the same bytes without a
   // giant formatting-only diff in an established lock.
-  writeFileSync(lockPath, serializeStableIdLockfile(nextLock), "utf8");
+  writeFileSync(lockPath, serializeIdentityUsda(nextLock), "utf8");
 
   // ── THE STRUCTURAL INTERFACE (#72) — directives (payload shapes) + aggregates (read
   // shapes, sid-keyed), keyed by DOMAIN. The SAME object is (a) baked into the generated
@@ -3938,11 +3943,12 @@ async function main(): Promise<void> {
         }
       : di;
   }
-  writeFileSync(
-    path.join(outDir, `${cfg.name}.interface.json`),
-    JSON.stringify(packageInterface, null, 2) + "\n",
-    "utf8",
-  );
+  // NO INTERFACE SIDECAR. The structural interface is an in-memory codegen model only: it is baked
+  // INTO the generated clients where compiler tooling can inspect the requirement that will ship.
+  // Emitting it as JSON created a second representation of law that DRIFTED: the prior sidecar
+  // omitted `principal` and `bornAt`, two fields the USDA declares
+  // `nomos:required = true`, so anything reading it saw a contract the kernel would refuse.
+  // One fact, one representation: the typed USDA closure is the contract.
 
   // ── RECURSIVE-PAYLOAD NOTES (z.lazy) — a self-referencing tree/JSON payload field is FULLY
   // supported: each codegen layer mints a named recursive type for it (TS `type <Name>`, Dart
@@ -5115,16 +5121,11 @@ async function main(): Promise<void> {
     requiresKernel,
   };
 
-  // ── 3b. public OpenAPI diagnostic/codegen projection. This JSON document is not law, install input,
-  // a runtime route table, or host authority. Kernel execution and current-law description derive from
-  // the installed typed USDA stage; this projection exists only for Swagger, client generators and agent
-  // tooling that consume OpenAPI.
-  const publicOpenapi = mergeOpenApiFragments(
-    presentationDomainModules.map((m) => generateOpenApiFragment(m, { lawHash: domainHash })),
-    { title: `${cfg.name} (nomos package)`, lawHash: domainHash },
-  );
-  const openapiPath = path.join(outDir, `${cfg.name}.openapi.json`);
-  writeFileSync(openapiPath, JSON.stringify(publicOpenapi, null, 2) + "\n", "utf8");
+  // ── 3b. NO OPENAPI SIDECAR. OpenAPI remains the sanctioned standard for describing this package's
+  // API — but it is SERVED, not stored: the kernel derives it from the installed typed USDA IR
+  // (`GET /v2/workspaces/<ws>/openapi.json`), so the description cannot drift from the law it
+  // describes. Writing a build-time copy created exactly the drift the representation rule forbids
+  // — a derived second copy a reader could believe. Ask the holon that runs the law.
 
   // ── 4. human build summary (diagnostic only; never deployment input) ──
   const summary = {
@@ -5886,7 +5887,7 @@ async function main(): Promise<void> {
   // STABLE IDS (#58): the minted/carried identity surface + every INFERRED rename —
   // the silent lane made visible (if an inference is wrong — you meant remove+add —
   // split the edit into two compiles, or answer the evolve gate with a disposition).
-  console.log(`  stable-ids ${rel(lockPath)} (committed lockfile — identity across renames)`);
+  console.log(`  identity   ${rel(lockPath)} (committed typed USDA — identity across renames and retirements)`);
   for (const { domain, renames } of inferredRenames) {
     for (const r of renames) {
       console.log(
@@ -5903,7 +5904,7 @@ async function main(): Promise<void> {
   }
   console.log(`  client     ${rel(clientPath)} (typed TS client — payloads, read models, query accessors)`);
   for (const note of recursiveNotes) console.log(`  note       ${note}`);
-  console.log(`  openapi    ${rel(openapiPath)} (${Object.keys(publicOpenapi.paths).length} operation(s) — public diagnostic sidecar; runtime self-description comes from installed USDA)`);
+  console.log(`  openapi    served by the holon from installed USDA (GET /v2/workspaces/<ws>/openapi.json) — no build-time copy to drift`);
   if (proofPath !== undefined) {
     console.log(`  proof      ${rel(proofPath)} (a runnable e2e GENERATED from your law — run: githolon proof)`);
   } else {

package/src/decl_shapes.ts

@@ -10,7 +10,7 @@
  * Why shared: the kernel-served OpenAPI (G1 — openapi residue removal) is produced by the lump
  * running `generateOpenApiFragment` over the SAME modules it dispatches; if the lump discovered
  * queries/counts/sums/spatials by a DIFFERENT shape than the compiler did when it wrote
- * `<name>.openapi.json`, the kernel-served spec would drift from the compiled one. One predicate
+ * the kernel-served OpenAPI, runtime description would drift from installed law. One predicate
  * set ⇒ one shape ⇒ byte-identity.
  *
  * ENGINE-BUNDLE-SAFE: imports NO node builtin (only DSL types) — it bundles under esbuild

package/src/engine_entry.ts

@@ -175,7 +175,7 @@ export interface EngineEntryConfig {
   readonly openapiDocument?: OpenApiDoc;
   /**
    * The package's OpenAPI document title (the compiler's `"<name> (nomos package)"`). Baked into
-   * the lump so `describe` reproduces the compiler's `<name>.openapi.json` byte-for-byte without
+   * the lump so `describe` reproduces the compiler's public description byte-for-byte without
    * the kernel knowing the package name. The kernel MAY override it (the workspace-level title).
    */
   readonly packageTitle?: string;
@@ -1075,7 +1075,7 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
    * dispatches. The kernel selects the content-addressed describe plan from the native USD
    * package in custody, so the workspace's API surface is a pure,
    * deterministic function of installed law — NOT a host-staged blob. Its public `paths` reproduce
-   * the `<name>.openapi.json` the compiler wrote; describe also carries a private, law-derived
+   * the public description the compiler derived; describe also carries a private, law-derived
    * framework routing manifest which the host consumes internally and never publishes.
    * `opts.lawHash`/`opts.title` are injected by the kernel at describe-time (the version stamp +
    * package title), matching the compiler's `domainHash`/`"<name> (nomos package)"`.

package/src/evolve_preview.ts

@@ -26,7 +26,7 @@
  *                       law get typed 422s until regenerated (directives are not sid-tracked).
  *
  * The preview NEVER needs to emit a `rebinds` fragment: a rename is detected by a MATCHED sid
- * (the compiler carries it via the nomos.stable-ids.json lockfile), so it is already a silent
+ * (the compiler carries it via the nomos.identity.usda lockfile), so it is already a silent
  * admit — rebinds is only for the hand-repair path where the sid was lost, which this preview,
  * reading the carried sids, never produces.
  */
@@ -34,8 +34,8 @@ import type { Finding } from "./law_check.js";
 import type { DirectivePayloadShape, DomainInterface } from "./shape_compat.js";
 import { domainInterface } from "./shape_compat.js";
 import type { StableIds } from "./stable_ids_types.js";
-import type { StableIdLockfile } from "./stable_id_lockfile.js";
-export type { StableIdLockfile } from "./stable_id_lockfile.js";
+import type { CompilerIdentityModel } from "./identity_model.js";
+export type { CompilerIdentityModel } from "./identity_model.js";
 import type { DomainModule } from "./codegen_dart.js";
 import type { WireSchema } from "./wire.js";
 
@@ -137,7 +137,7 @@ function evolveDomainFromInterface(iface: DomainInterface): EvolveDomain {
  * by the kernel; `.law.usdz` is only its lossless one-file transport envelope. */
 export function evolveLawFromInterface(
   ifaces: Record<string, DomainInterface>,
-  lock?: StableIdLockfile,
+  lock?: CompilerIdentityModel,
 ): EvolveLaw {
   const law: EvolveLaw = {};
   for (const [key, iface] of Object.entries(ifaces)) {
@@ -180,10 +180,10 @@ export function evolveLawFromInterface(
   return law;
 }
 
-/** Build an EvolveLaw from a `nomos.stable-ids.json` lockfile — aggregate identity + drivers, but
+/** Build an EvolveLaw from a `nomos.identity.usda` lockfile — aggregate identity + drivers, but
  *  NO directive payloads (a lockfile carries no interface). Directive-level warnings are then
  *  unavailable; the caller notes it. */
-export function evolveLawFromLockfile(lock: StableIdLockfile): EvolveLaw {
+export function evolveLawFromLockfile(lock: CompilerIdentityModel): EvolveLaw {
   const law: EvolveLaw = {};
   for (const [key, d] of Object.entries(lock.domains ?? {})) {
     law[key] = {
@@ -201,7 +201,7 @@ export function evolveLawFromLockfile(lock: StableIdLockfile): EvolveLaw {
  *  pre-#58 fallback) — a rename then reads as removal+add; the caller warns to compile first. */
 export function currentEvolveLaw(
   modules: readonly DomainModule[],
-  lock?: StableIdLockfile,
+  lock?: CompilerIdentityModel,
 ): EvolveLaw {
   const law: EvolveLaw = {};
   for (const mod of modules) {