@githolon/dsl 0.102.4 → 0.102.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.102.4",
+  "version": "0.102.5",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/check_package_main.ts

@@ -26,6 +26,7 @@ import {
   type EvolveLaw,
   type StableIdLockfile,
 } from "./evolve_preview.js";
+import { parseStableIdLockfile } from "./stable_id_lockfile.js";
 
 interface DomainConfig {
   key: string;
@@ -125,7 +126,7 @@ function loadPriorEvolveLaw(arg: string): { law: EvolveLaw; source: string; note
   const p = parsed as Record<string, unknown>;
   if (p.domains !== undefined && p.interface === undefined && p.packageUsda === undefined) {
     return {
-      law: evolveLawFromLockfile(parsed as StableIdLockfile),
+      law: evolveLawFromLockfile(parseStableIdLockfile(parsed)),
       source: file,
       note: `prior is a lockfile — aggregate/field identity is diffed, but directive payload changes cannot be (deploy.json carries the interface).`,
     };
@@ -149,7 +150,7 @@ function loadCwdLockfile(configArg: string): StableIdLockfile | undefined {
   const lockPath = path.join(cfgDir, "nomos.stable-ids.json");
   if (!existsSync(lockPath)) return undefined;
   try {
-    return JSON.parse(readFileSync(lockPath, "utf8")) as StableIdLockfile;
+    return parseStableIdLockfile(JSON.parse(readFileSync(lockPath, "utf8")));
   } catch {
     return undefined;
   }

package/src/compile_package_main.ts

@@ -152,6 +152,11 @@ import {
   type InferredRename,
   type StableIds,
 } from "./stable_ids.js";
+import {
+  parseStableIdLockfile,
+  serializeStableIdLockfile,
+  type StableIdLockfile,
+} from "./stable_id_lockfile.js";
 import { emitUsd, type UsdLayer } from "./usd.js";
 import { emitLayeredRelationUsda, type RelationLayerInput } from "./relation_composition.js";
 import { assertNoDartBarrelCollisions, type BarrelExportedFile } from "./dart_barrel_guard.js";
@@ -3053,20 +3058,16 @@ async function main(): Promise<void> {
   // 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.
-  interface StableIdLock {
-    v: 1;
-    domains: Record<string, { stableIds: StableIds; schemas: Record<string, WireSchema> }>;
-  }
   const lockPath = path.join(cfgDir, "nomos.stable-ids.json");
-  const priorLock: StableIdLock | undefined = existsSync(lockPath)
-    ? (JSON.parse(readFileSync(lockPath, "utf8")) as StableIdLock)
+  const priorLock: StableIdLockfile | undefined = existsSync(lockPath)
+    ? parseStableIdLockfile(JSON.parse(readFileSync(lockPath, "utf8")))
     : undefined;
   const inferredRenames: { domain: string; renames: InferredRename[] }[] = [];
   // 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: StableIdLock = { v: 1, domains: { ...(priorLock?.domains ?? {}) } };
+  const nextLock: StableIdLockfile = { v: 1, domains: { ...(priorLock?.domains ?? {}) } };
   for (const mod of domainModules) {
     const identityName = mod.name;
     // The CURRENT canonical aggregate schemas (a pre-continuity manifest pass —
@@ -3165,7 +3166,7 @@ async function main(): Promise<void> {
   // 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, JSON.stringify(nextLock, null, 2) + "\n", "utf8");
+  writeFileSync(lockPath, serializeStableIdLockfile(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

package/src/evolve_preview.ts

@@ -34,6 +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 { DomainModule } from "./codegen_dart.js";
 import type { WireSchema } from "./wire.js";
 import { parseUsdaDocument } from "./usd_layers.js";
@@ -92,7 +94,7 @@ function aggregatesFromStableIds(
   for (const [aggLabel, a] of Object.entries(stableIds.aggregates)) {
     const fields: EvolveAggregate["fields"] = {};
     for (const [fLabel, f] of Object.entries(a.fields ?? {})) {
-      const driver = schemas?.[aggLabel]?.[fLabel];
+      const driver = f.driver ?? schemas?.[aggLabel]?.[fLabel];
       fields[f.sid] = {
         sid: f.sid,
         label: fLabel,
@@ -130,12 +132,6 @@ function evolveDomainFromInterface(iface: DomainInterface): EvolveDomain {
   };
 }
 
-/** The committed `nomos.stable-ids.json` lockfile shape (compile_package_main writes it). */
-export interface StableIdLockfile {
-  v: 1;
-  domains: Record<string, { stableIds: StableIds; schemas?: Record<string, WireSchema> }>;
-}
-
 /** A deploy.json body (the subset this preview reads): the per-domain interface + the package
  *  bytes (for the embedded stable-ids/driver schemas when no lockfile rides alongside). */
 export interface DeployJson {
@@ -254,13 +250,19 @@ export function currentEvolveLaw(
     const stableIds = locked?.stableIds;
     const iface = domainInterface(mod, stableIds);
     const dom = evolveDomainFromInterface(iface);
-    // Fold drivers from the lockfile schemas (interface has none).
-    if (locked?.schemas !== undefined) {
+    // Fold drivers from the stable fields. Verbose v1 locks may also carry the
+    // older aggregate-schema copy; compact v2 locks deliberately omit it.
+    if (stableIds !== undefined) {
       for (const agg of Object.values(dom.aggregates)) {
-        const schema = locked.schemas[agg.label];
-        if (schema === undefined) continue;
+        const stableAggregate = Object.values(stableIds.aggregates).find(
+          (candidate) => candidate.sid === agg.sid,
+        );
+        const schema = locked?.schemas?.[agg.label];
         for (const f of Object.values(agg.fields)) {
-          const driver = schema[f.label];
+          const stableField = Object.values(stableAggregate?.fields ?? {}).find(
+            (candidate) => candidate.sid === f.sid,
+          );
+          const driver = stableField?.driver ?? schema?.[f.label];
           if (driver !== undefined) (f as { driver?: string }).driver = JSON.stringify(driver);
         }
       }

package/src/lsp_server.ts

@@ -49,6 +49,7 @@ import {
   type EvolveLaw,
   type StableIdLockfile,
 } from "./evolve_preview.js";
+import { parseStableIdLockfile } from "./stable_id_lockfile.js";
 
 interface DomainConfig {
   key: string;
@@ -192,7 +193,7 @@ function loadPriorEvolveLaw(arg: string, cfgDir: string): EvolveLaw | undefined
   }
   const p = parsed as Record<string, unknown>;
   if (p.domains !== undefined && p.interface === undefined && p.packageUsda === undefined) {
-    return evolveLawFromLockfile(parsed as StableIdLockfile);
+    return evolveLawFromLockfile(parseStableIdLockfile(parsed));
   }
   return evolveLawFromDeployJson(parsed as never);
 }
@@ -202,7 +203,7 @@ function loadCwdLockfile(cfgDir: string): StableIdLockfile | undefined {
   const lockPath = path.join(cfgDir, "nomos.stable-ids.json");
   if (!existsSync(lockPath)) return undefined;
   try {
-    return JSON.parse(readFileSync(lockPath, "utf8")) as StableIdLockfile;
+    return parseStableIdLockfile(JSON.parse(readFileSync(lockPath, "utf8")));
   } catch {
     return undefined;
   }

package/src/stable_id_lockfile.ts

@@ -0,0 +1,144 @@
+import type { StableAggregateId, StableFieldId, StableIds } from "./stable_ids_types.js";
+import type { WireSchema } from "./wire.js";
+
+export interface StableIdLockDomain {
+  stableIds: StableIds;
+  schemas?: Record<string, WireSchema>;
+}
+
+/** The materialized lock shape consumed inside the compiler and authoring tools. */
+export interface StableIdLockfile {
+  v: 1;
+  domains: Record<string, StableIdLockDomain>;
+}
+
+type CompactStableFieldId = Omit<StableFieldId, "contract" | "shape"> & {
+  contract?: string | number;
+};
+
+interface CompactStableAggregateId extends Omit<StableAggregateId, "fields"> {
+  fields: Record<string, CompactStableFieldId>;
+}
+
+interface CompactStableIds extends Omit<StableIds, "aggregates"> {
+  aggregates: Record<string, CompactStableAggregateId>;
+}
+
+interface CompactStableIdLockfile {
+  v: 2;
+  /** [contract hash, canonical contract descriptor], addressed by field.contract. */
+  contracts: readonly (readonly [string, unknown])[];
+  domains: Record<string, { stableIds: CompactStableIds }>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function sortedJson(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortedJson);
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort()
+      .map((key) => [key, sortedJson(value[key])]),
+  );
+}
+
+/**
+ * Read both the original verbose lock and the compact v2 wire shape. Callers always
+ * receive the same fully materialized v1 object, so continuity and evolution logic
+ * never needs to know how the durable file was encoded.
+ */
+export function parseStableIdLockfile(value: unknown): StableIdLockfile {
+  if (!isRecord(value)) throw new Error("stable-id lock must be a JSON object");
+  if (value.v === 1) return value as unknown as StableIdLockfile;
+  if (value.v !== 2 || !Array.isArray(value.contracts) || !isRecord(value.domains)) {
+    throw new Error("unsupported stable-id lock encoding");
+  }
+
+  const compact = value as unknown as CompactStableIdLockfile;
+  const contracts = compact.contracts.map((entry, index) => {
+    if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== "string") {
+      throw new Error(`stable-id lock contract ${index} is malformed`);
+    }
+    return entry;
+  });
+  const domains: StableIdLockfile["domains"] = {};
+
+  for (const [domainName, domain] of Object.entries(compact.domains)) {
+    const aggregates: StableIds["aggregates"] = {};
+    for (const [aggregateName, aggregate] of Object.entries(domain.stableIds.aggregates ?? {})) {
+      const fields: StableAggregateId["fields"] = {};
+      for (const [fieldName, field] of Object.entries(aggregate.fields ?? {})) {
+        const contractRef = field.contract;
+        const { contract: _contractRef, ...fieldWithoutContract } = field;
+        if (typeof contractRef === "number") {
+          const contract = contracts[contractRef];
+          if (contract === undefined) {
+            throw new Error(
+              `stable-id lock field ${domainName}.${aggregateName}.${fieldName} references missing contract ${contractRef}`,
+            );
+          }
+          fields[fieldName] = {
+            ...fieldWithoutContract,
+            contract: contract[0],
+            shape: contract[1],
+          };
+        } else if (typeof contractRef === "string") {
+          fields[fieldName] = { ...fieldWithoutContract, contract: contractRef };
+        } else {
+          fields[fieldName] = fieldWithoutContract;
+        }
+      }
+      aggregates[aggregateName] = { ...aggregate, fields };
+    }
+    domains[domainName] = {
+      stableIds: { ...domain.stableIds, aggregates },
+    };
+  }
+
+  return { v: 1, domains };
+}
+
+/**
+ * Encode the committed lock without repeating identical contract descriptors or
+ * aggregate driver schemas. Fields already retain their canonical merge driver;
+ * the contract table retains the full descriptor needed to prove safe widening.
+ */
+export function serializeStableIdLockfile(lock: StableIdLockfile): string {
+  const contracts: [string, unknown][] = [];
+  const contractIndexes = new Map<string, number>();
+  const domains: CompactStableIdLockfile["domains"] = {};
+
+  for (const [domainName, domain] of Object.entries(lock.domains)) {
+    const aggregates: CompactStableIds["aggregates"] = {};
+    for (const [aggregateName, aggregate] of Object.entries(domain.stableIds.aggregates)) {
+      const fields: CompactStableAggregateId["fields"] = {};
+      for (const [fieldName, field] of Object.entries(aggregate.fields)) {
+        const { shape, ...withoutShape } = field;
+        if (field.contract !== undefined && shape !== undefined) {
+          let index = contractIndexes.get(field.contract);
+          if (index === undefined) {
+            index = contracts.length;
+            contracts.push([field.contract, shape]);
+            contractIndexes.set(field.contract, index);
+          }
+          fields[fieldName] = { ...withoutShape, contract: index };
+        } else {
+          fields[fieldName] = withoutShape;
+        }
+      }
+      aggregates[aggregateName] = { ...aggregate, fields };
+    }
+    domains[domainName] = {
+      stableIds: { ...domain.stableIds, aggregates },
+    };
+  }
+
+  // This is a machine-owned lockfile. Compact JSON is intentional: unlike generated
+  // law and clients, it must be committed so identity survives a clean clone.
+  return JSON.stringify(
+    sortedJson({ v: 2, contracts, domains } satisfies CompactStableIdLockfile),
+  ) + "\n";
+}

package/src/stable_ids.ts

@@ -233,9 +233,14 @@ export function deriveStableIdContinuity(
  * drivers). Returns `undefined` (pair allowed on name-cardinality alone) when no
  * snapshot is available. */
 function priorFieldDriver(
-  resolved: { priorSchema?: WireSchema } | undefined,
+  resolved: {
+    priorFields?: Record<string, StableFieldId>;
+    priorSchema?: WireSchema;
+  } | undefined,
   oldField: string,
 ): string | undefined {
+  const retained = resolved?.priorFields?.[oldField]?.driver;
+  if (retained !== undefined) return JSON.stringify(retained);
   const schema = resolved?.priorSchema;
   if (schema === undefined) return undefined;
   const d = schema[oldField];