@githolon/dsl 0.31.1 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.31.1",
+  "version": "0.32.0",
   "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/compile_package_main.ts

@@ -113,7 +113,8 @@ import {
   type InferredRename,
   type StableIds,
 } from "./stable_ids.js";
-import type { UsdLayer } from "./usd.js";
+import { emitUsd, type UsdLayer } from "./usd.js";
+import { emitLayeredRelationUsda, type RelationLayerInput } from "./relation_composition.js";
 import { generateTsClient, tsClientFactoryName } from "./codegen_ts.js";
 import { generateOpenApiFragment, mergeOpenApiFragments } from "./codegen_openapi.js";
 import { domainInterface, type DomainInterface } from "./shape_compat.js";
@@ -1315,6 +1316,31 @@ async function main(): Promise<void> {
   writeFileSync(pkgPath, text, "utf8");
   const domainHash = sha256HexUtf8(text);
 
+  // ── 2a. the REAL layered RELATION `.usda` set — an additive, deterministic visualization +
+  //        cross-check artifact (usdview / `usdcat --flatten`). One sublayer per domain carrying its
+  //        relation opinions as PRIMS + a root with `subLayers` STRONGEST-FIRST; usdcat composes the
+  //        shared relation types, the compiler's `composeSharedRelationTypes` is the fail-closed guard
+  //        on top. Emitted iff ANY domain declares a relation type. Never feeds the package hash.
+  {
+    const relInputs: RelationLayerInput[] = [];
+    for (const mod of domainModules) {
+      // Per-domain UNCOMPOSED relation types: emit the single module alone (single-domain ⇒ no shared
+      // type ⇒ its own decls, un-unioned — the layers ARE the sublayers usdcat will compose).
+      const one = emitUsd([{ path: `/Nomos/${mod.domain ?? mod.name}`, module: mod }]);
+      const types = one.layers[0]?.nomosRelations?.types;
+      if (types !== undefined && Object.keys(types).length > 0) {
+        relInputs.push({ domain: mod.domain ?? mod.name, types });
+      }
+    }
+    if (relInputs.length > 0) {
+      const emit = emitLayeredRelationUsda(relInputs, cfg.name);
+      const relDir = path.join(outDir, `${cfg.name}.relation-layers`);
+      mkdirSync(relDir, { recursive: true });
+      for (const f of emit.files) writeFileSync(path.join(relDir, f.name), f.text, "utf8");
+      writeFileSync(path.join(relDir, "root.usda"), emit.root, "utf8");
+    }
+  }
+
   // ── 2b. opt-in LAYERED emission — additive artifacts ONLY (the flattened package
   //        above and its domainHash are already written and do not move). The
   //        homomorphism is ASSERTED fail-closed on every layered compile: the

package/src/framework/domain_lifecycle.ts

@@ -28,6 +28,7 @@ export const DOMAIN_INSTALLATION_PHASES = [
   "Disabled",
   "Superseded",
   "Retiring",
+  "Retired",
   "Failed",
 ] as const;
 export type DomainInstallationPhase = (typeof DOMAIN_INSTALLATION_PHASES)[number];
@@ -48,6 +49,7 @@ export const DomainInstallation = aggregate("DomainInstallation", {
   "metadata.generation": t.int().merge(Lww),
   "status.phase": t.enum(DOMAIN_INSTALLATION_PHASES).merge(Lww),
   "status.observedGeneration": t.int().merge(Lww),
+  "status.supersededBy": t.string().merge(Lww).optional(),
   "status.conditions": t.map(t.json()).merge(MapOf(Lww)),
 });
 
@@ -77,6 +79,13 @@ export const installDomain = directive("installDomain")
       authorityScope: z.string().default("workspace/root"),
       dependencies: z.array(z.string()).default([]),
       supersedes: z.string().optional(),
+      // THE FRONTIER TRANSITION (install-lifecycle): `replaces` names a PRIOR install this
+      // deploy makes current UNEQUIVOCALLY — the prior install is flipped out of the served
+      // frontier (`Superseded`, or `Retired` when `retireReplaced`) and gets the reverse
+      // `status.supersededBy` edge to this install. Absent ⇒ install-BESIDE (backward-compat:
+      // byte-identical ops to the pre-lifecycle plan). `replaces` also sets `spec.supersedes`.
+      replaces: z.string().optional(),
+      retireReplaced: z.boolean().default(false),
       finalizers: z.array(z.string()).default([]),
     }),
   )
@@ -97,8 +106,18 @@ export const installDomain = directive("installDomain")
     if (p.dependencies.length > 0) {
       ops.push(addToSet(install, "spec.dependencies", p.dependencies));
     }
-    if (p.supersedes !== undefined) {
-      ops.push(set(install, "spec.supersedes", p.supersedes));
+    // The predecessor back-link: `supersedes` (explicit) or `replaces` (the actionable form).
+    const supersedes = p.supersedes ?? p.replaces;
+    if (supersedes !== undefined) {
+      ops.push(set(install, "spec.supersedes", supersedes));
+    }
+    // The transition on the PRIOR install: drop it from the served frontier + point it here.
+    if (p.replaces !== undefined) {
+      const replaced = domainInstallationInstance(p.replaces);
+      ops.push(
+        set(replaced, "status.phase", p.retireReplaced ? "Retired" : "Superseded"),
+      );
+      ops.push(set(replaced, "status.supersededBy", p.domainHash));
     }
     if (p.finalizers.length > 0) {
       ops.push(addToSet(install, "spec.finalizers", p.finalizers));

package/src/relation_composition.ts

@@ -0,0 +1,286 @@
+// 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}.
+//
+// COMPILE-TIME USD-LAYER COMPOSITION for SHARED (global) relation types + the
+// fail-closed DIVERGENCE GUARD.
+//
+// THE MODEL. When a package bundles multiple domains, each domain lowers its own
+// `relationType` decls into its own `UsdLayer.nomosRelations`. A NON-global type is
+// auto-qualified by its owning domain (`estate` → `estate__workspace`), so two
+// domains that each declare the same bare type NEVER collide — their qualified ids
+// differ, and they stay separate layers. A `.asGlobal()` type (a kernel-coupled
+// framework type, e.g. governance/read-visibility `workspace`) stays a BARE shared
+// name, so MULTIPLE domains that each contribute to one global type land on the SAME
+// canonical id. That cross-domain merge USED to happen only at the KERNEL (runtime
+// `merge_layers`, a blunt per-type last-wins that SILENTLY DROPS the losing layer's
+// relations — the bug that broke co2's `createSite`). We move it to COMPILE time, in
+// TS, using USD's composition MODEL (LIVRPS sublayer strength):
+//
+//   * COMPOSE (deliverable #1): for each SHARED global type, UNION the relations
+//     across the contributing domains — a prim-set union, so EVERY domain's relations
+//     survive (nothing is dropped). The composed union is written back into every
+//     contributing layer so the downstream kernel merge (union OR last-wins) yields
+//     the full union regardless of its policy. This is idempotent and byte-stable.
+//
+//   * GUARD (deliverable #2): when two or more domains declare the SAME relation on a
+//     SHARED global type with DIVERGENT rewrites (co2's `workspace.admin`: `self()` in
+//     estate/platform vs `union(self, computed(creator))` in home), REFUSE AT COMPILE
+//     with a scalpel message naming the type, the relation, and each domain's rewrite.
+//     Single-owner relations and byte-identical agreeing opinions PASS (union). This
+//     turns the kernel's blunt `None` / "no-relation-schema" into a precise compile
+//     refusal — the era rule ("the law is the era") is preserved because a package with
+//     no shared global type composes to itself, byte-identical.
+//
+// SUBLAYER STRENGTH ORDER (documented, deliverable #1): the package's domain order is
+// WEAK → STRONG (Nomos module-fold notation — later wins), which maps onto USD
+// `subLayers` STRONGEST-FIRST by reversal (the same left-biased monoid, opposite list
+// notation — the convention `usd_layers.ts::layeredRootUsda` already records). For a
+// NON-divergent shared type the union is order-INDEPENDENT (every domain's opinion on a
+// given relation is identical, so which layer "wins" is immaterial); order matters ONLY
+// to the visualization flatten, never to the composed IR.
+
+import type { UsdLayer } from "./usd.js";
+
+/** A single relation's definition as it rides in `nomosRelations` (`{rewrite, allowed}`). */
+type RelDef = NonNullable<UsdLayer["nomosRelations"]>["types"][string]["relations"][string];
+/** One relation TYPE's spec (`{relations, caps?}`). */
+type RelSpec = NonNullable<UsdLayer["nomosRelations"]>["types"][string];
+
+/** Strip the `/Nomos/` prim-scope prefix to recover the owning domain key from a layer path. */
+export function domainOfLayerPath(path: string): string {
+  return path.startsWith("/Nomos/") ? path.slice("/Nomos/".length) : path;
+}
+
+/**
+ * Render a rewrite AST to the author-facing surface syntax (`self()` / `computed(x)` /
+ * `union(...)` / `via(t, c)` / …) — the readable form the scalpel message + the layered
+ * `.usda` provenance attr carry. A `null`/absent rewrite is a pure-direct relation (`this`).
+ */
+export function renderRewrite(rw: unknown): string {
+  if (rw === null || rw === undefined) return "this";
+  const r = rw as { kind?: string; [k: string]: unknown };
+  switch (r.kind) {
+    case "this":
+      return "self()";
+    case "computed":
+      return `computed(${String(r.relation)})`;
+    case "ttu":
+      return `${r.all ? "viaAll" : "via"}(${String(r.tupleset)}, ${String(r.computed)})`;
+    case "union":
+      return `union(${(r.children as unknown[]).map(renderRewrite).join(", ")})`;
+    case "intersection":
+      return `intersection(${(r.children as unknown[]).map(renderRewrite).join(", ")})`;
+    case "exclusion":
+      return `exclusion(${renderRewrite(r.base)}, ${renderRewrite(r.subtract)})`;
+    default:
+      return JSON.stringify(rw);
+  }
+}
+
+/** A per-relation divergence, gathered for the scalpel message. */
+interface RelationConflict {
+  readonly type: string;
+  readonly relation: string;
+  /** Each contributing domain's opinion, in package (weak→strong) order. */
+  readonly opinions: { readonly domain: string; readonly rewrite: string }[];
+}
+
+/** Format the accumulated divergences into the fail-closed refusal (mirrors `failclosed_check.py`). */
+function scalpelMessage(conflicts: readonly RelationConflict[]): string {
+  const lines: string[] = [
+    `Refusing to compose the package: shared relation type(s) carry DIVERGENT rewrites across ` +
+      `domains — the composed flatten would SILENTLY take the strongest layer's opinion (LIVRPS ` +
+      `last-wins), so this is a fail-closed compile refusal, not a silent pick.`,
+    ``,
+  ];
+  for (const c of conflicts) {
+    lines.push(`  relation type "${c.type}" relation "${c.relation}" — ${c.opinions.length} divergent opinions:`);
+    const w = Math.max(...c.opinions.map((o) => o.domain.length));
+    for (const o of c.opinions) lines.push(`      · ${o.domain.padEnd(w)}  ${o.rewrite}`);
+  }
+  lines.push(
+    ``,
+    `Fix: give the type ONE canonical definition of each divergent relation (the domains must ` +
+      `agree, byte-for-byte), or use DISTINCT / domain-qualified relation types (drop \`.asGlobal()\` ` +
+      `so each domain's type auto-qualifies and never shares an id).`,
+  );
+  return lines.join("\n");
+}
+
+/**
+ * Compose the SHARED (global, bare-id) relation types across a package's layers — UNION the
+ * relations per shared type, GUARD divergent rewrites fail-closed, and write the union back into
+ * every contributing layer. Non-shared (single-owner / auto-qualified) types are untouched, so a
+ * package with no shared global type returns byte-identical layers (the era rule). Deterministic:
+ * sorted keys, sorted diagnostics.
+ *
+ * @throws a scalpel `Error` naming the type, relation, and each domain's rewrite on any divergence.
+ */
+export function composeSharedRelationTypes(layers: readonly UsdLayer[]): UsdLayer[] {
+  // type id → the layers (domains) that contribute it, in package (weak→strong) order.
+  const contributors = new Map<string, { domain: string; spec: RelSpec }[]>();
+  for (const layer of layers) {
+    const rels = layer.nomosRelations;
+    if (rels === undefined) continue;
+    for (const [type, spec] of Object.entries(rels.types)) {
+      const arr = contributors.get(type) ?? [];
+      arr.push({ domain: domainOfLayerPath(layer.path), spec });
+      contributors.set(type, arr);
+    }
+  }
+
+  const composed = new Map<string, RelSpec>();
+  const conflicts: RelationConflict[] = [];
+  for (const type of [...contributors.keys()].sort()) {
+    const contribs = contributors.get(type)!;
+    // A type contributed by ONE domain is single-owner — nothing to compose (untouched).
+    if (contribs.length < 2) continue;
+
+    // caps must agree across the contributing domains (a divergent bound is a hard error).
+    let caps: RelSpec["caps"];
+    for (const c of contribs) {
+      if (c.spec.caps === undefined) continue;
+      if (caps === undefined) caps = c.spec.caps;
+      else if (caps.maxDepth !== c.spec.caps.maxDepth || caps.maxFanout !== c.spec.caps.maxFanout) {
+        throw new Error(
+          `Refusing to compose the package: shared relation type "${type}" is declared with ` +
+            `CONFLICTING caps across domains (${contribs.map((x) => x.domain).join(", ")}). Give the ` +
+            `type one canonical \`caps\`.`,
+        );
+      }
+    }
+
+    // Gather every domain's opinion on each relation (in package order).
+    const opinions = new Map<string, { domain: string; def: RelDef }[]>();
+    for (const c of contribs) {
+      for (const [rel, def] of Object.entries(c.spec.relations)) {
+        const arr = opinions.get(rel) ?? [];
+        arr.push({ domain: c.domain, def });
+        opinions.set(rel, arr);
+      }
+    }
+
+    const unioned: Record<string, RelDef> = {};
+    for (const rel of [...opinions.keys()].sort()) {
+      const ops = opinions.get(rel)!;
+      const distinct = new Set(ops.map((o) => JSON.stringify(o.def)));
+      if (distinct.size > 1) {
+        conflicts.push({
+          type,
+          relation: rel,
+          opinions: ops.map((o) => ({ domain: o.domain, rewrite: renderRewrite((o.def as { rewrite: unknown }).rewrite) })),
+        });
+      } else {
+        unioned[rel] = ops[0]!.def; // agreeing opinions / single-owner relation — keep it
+      }
+    }
+    // Sorted relation keys (byte-determinism against the per-layer emission).
+    const relations: Record<string, RelDef> = {};
+    for (const k of Object.keys(unioned).sort()) relations[k] = unioned[k]!;
+    composed.set(type, { relations, ...(caps !== undefined ? { caps } : {}) });
+  }
+
+  if (conflicts.length > 0) throw new Error(scalpelMessage(conflicts));
+  if (composed.size === 0) return [...layers]; // nothing shared — byte-identical (era rule)
+
+  // Write the composed union back into every contributing layer, keeping type keys sorted.
+  return layers.map((layer) => {
+    const rels = layer.nomosRelations;
+    if (rels === undefined) return layer;
+    let touched = false;
+    const merged: Record<string, RelSpec> = {};
+    for (const [type, spec] of Object.entries(rels.types)) {
+      const c = composed.get(type);
+      if (c !== undefined) {
+        merged[type] = c;
+        touched = true;
+      } else {
+        merged[type] = spec;
+      }
+    }
+    if (!touched) return layer;
+    const sorted: Record<string, RelSpec> = {};
+    for (const k of Object.keys(merged).sort()) sorted[k] = merged[k]!;
+    return { ...layer, nomosRelations: { v: 1 as const, types: sorted } };
+  });
+}
+
+// ── the REAL layered `.usda` emission (deliverable #3 — for usdview / usdcat --flatten) ──────────
+
+/** One domain's contribution to the layered relation emission: its bare-id relation types. */
+export interface RelationLayerInput {
+  readonly domain: string;
+  /** The domain's `nomosRelations.types` (UNCOMPOSED — the layers ARE the sublayers usdcat composes). */
+  readonly types: Record<string, RelSpec>;
+}
+
+/** `"a"` → escaped USDA string literal (minimal — relation/rewrite tokens are `[A-Za-z0-9_.,()]`). */
+function usda(s: string): string {
+  return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * Emit ONE domain's relation opinions as a real `.usda` sublayer: `def "<Type>" { def "<relation>"
+ * { custom string nomos:rewrite = "…"; custom string nomos:from = "<domain>" } }`. Structured so
+ * `usdcat --flatten` composes the relation prims across sublayers (a stronger layer's `nomos:rewrite`
+ * wins; the relation SET is the union). Deterministic: types + relations sorted.
+ */
+export function emitRelationSublayerUsda(input: RelationLayerInput): string {
+  const lines: string[] = [`#usda 1.0`, `(`, `    doc = "Nomos relation layer — domain ${input.domain}"`, `)`, ``];
+  for (const type of Object.keys(input.types).sort()) {
+    lines.push(`def ${usda(type)}`, `{`);
+    const relations = input.types[type]!.relations;
+    for (const rel of Object.keys(relations).sort()) {
+      const def = relations[rel]! as { rewrite: unknown };
+      lines.push(
+        `    def ${usda(rel)}`,
+        `    {`,
+        `        custom string nomos:rewrite = ${usda(renderRewrite(def.rewrite))}`,
+        `        custom string nomos:from = ${usda(input.domain)}`,
+        `    }`,
+      );
+    }
+    lines.push(`}`, ``);
+  }
+  return lines.join("\n");
+}
+
+/** The result of {@link emitLayeredRelationUsda}: a root document + one sublayer file per domain. */
+export interface LayeredRelationEmit {
+  /** The root `.usda` (`subLayers = [...]`, STRONGEST-FIRST) that usdcat --flatten composes. */
+  readonly root: string;
+  /** Per-domain sublayer files (`name` is a bare filename; write beside the root). */
+  readonly files: { readonly name: string; readonly text: string }[];
+}
+
+/**
+ * Emit a REAL layered relation `.usda` set: one sublayer per domain (its relation opinions as prims)
+ * + a root with `subLayers` STRONGEST-FIRST, so `usdcat --flatten <root>` composes the package's
+ * shared relation types. `inputs` are in package order (WEAK → STRONG); the root reverses them to
+ * strongest-first (the documented convention). Deterministic (sorted within each layer, stable file
+ * names). Additive build artifact — never feeds the package hash.
+ */
+export function emitLayeredRelationUsda(inputs: readonly RelationLayerInput[], packageName: string): LayeredRelationEmit {
+  const safe = (s: string) => s.replace(/[^A-Za-z0-9._-]/g, "_");
+  const files = inputs.map((input) => ({
+    name: `${safe(input.domain)}.usda`,
+    text: emitRelationSublayerUsda(input),
+  }));
+  // subLayers is STRONGEST-FIRST → reverse the weak→strong package order.
+  const strongestFirst = [...files].reverse();
+  const root = [
+    `#usda 1.0`,
+    `(`,
+    `    doc = """Nomos relation-composition layers for package ${packageName}. subLayers are`,
+    `STRONGEST-FIRST (USD layer-stack order); the Nomos domain list composes weak→strong (later`,
+    `wins). \`usdcat --flatten\` composes the shared relation types; the compiler's TS composition`,
+    `(composeSharedRelationTypes) is the fail-closed guard layered on top."""`,
+    `    subLayers = [`,
+    ...strongestFirst.map((f, i) => `        @./${f.name}@${i < strongestFirst.length - 1 ? "," : ""}`),
+    `    ]`,
+    `)`,
+    ``,
+  ].join("\n");
+  return { root, files };
+}

package/src/usd.ts

@@ -44,6 +44,7 @@ import type { DomainModule } from "./codegen_dart.js";
 import { domainInterface } from "./shape_compat.js";
 import { relationType, user, key, anyUser, qualifiedTypeId, qualifyRelationType } from "./relation_schema.js";
 import { harvestPrincipalFlows } from "./wire_encode.js";
+import { composeSharedRelationTypes } from "./relation_composition.js";
 
 /** The referential marker of a directive prim (kernel `RefMode` wire string). */
 export type RefMode = WireRefMode;
@@ -1060,7 +1061,11 @@ export function emitUsd(
       };
     })
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
-  return { layers: out };
+  // COMPILE-TIME COMPOSITION + fail-closed GUARD for SHARED (global) relation types across the
+  // package's per-domain layers: UNION every domain's relations on a shared bare-id type (so nothing
+  // is silently dropped) and REFUSE on a divergent shared rewrite (the scalpel). Non-shared /
+  // auto-qualified types are untouched → a package with no shared global type is byte-identical.
+  return { layers: composeSharedRelationTypes(out) };
 }
 
 /** Two aggregate prims at the same path are identical iff same type + same schema. */

package/src/usd_layers.ts

@@ -70,6 +70,7 @@ import {
   type UsdPrim,
   type UsdQuery,
 } from "./usd.js";
+import { composeSharedRelationTypes } from "./relation_composition.js";
 
 /** The layer-file format marker (customLayerData `nomos:format`). */
 export const NOMOS_USD_LAYER_FORMAT = "nomos.usd-layer.v1";
@@ -865,7 +866,10 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
     };
   });
 
-  return { layers: out };
+  // Apply the SAME cross-layer shared-relation composition + guard the composed emission
+  // (`usd.ts::emitUsd`) applies, so the layered fold stays byte-homomorphic with it (a divergent
+  // shared global type refuses identically on both paths).
+  return { layers: composeSharedRelationTypes(out) };
 }
 
 // ── usda → IR (the round-trip parser for the pxr/usdcat conformance lane) ──────────