@githolon/dsl 0.1.0

package/src/usd.ts

@@ -0,0 +1,563 @@
+// 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} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * TS → USD — the UNIFIED composed-IR document (stage 1, increment 1).
+ *
+ * Two proven-but-isolated pieces become ONE here:
+ *  - `manifest.ts` (#136): encodes a `DomainModule` to a canonical flat manifest —
+ *    aggregates with field→Driver schemas + directive contracts (target / marker /
+ *    requiresCapability / payload-shape), hashed via `canonicalJson` / `domainHash`.
+ *  - `compose.ts` (#137): the typed, MONOTONIC layer composition — `requires`/`scope`
+ *    rules, `covers()`, fail-closed `CompositionViolation`, composed hash.
+ *
+ * The bridge is an OpenUSD-shaped IR document: a real (synthetic) `DomainModule`
+ * encodes into composable typed prims arranged under a layer PATH; multiple layers
+ * COMPOSE via the very same typed rules (`compose.ts`'s `mergeRequiresScope`, reused
+ * — never re-implemented); the composed stage FLATTENS and HASHES. This is the
+ * foundation of the certified-IR document the gate will later seal.
+ *
+ * SYNTHETIC framework units only — paths like `/Nomos/Prelude` and `/Sample/...`;
+ * no tenant/business domain is named or imported. Build-time only (imports
+ * `node:crypto` transitively via `manifest.js`); reachable via the `@githolon/dsl/usd`
+ * subpath, NOT the runtime `index.ts` barrel.
+ */
+import { createHash } from "node:crypto";
+import {
+  canonicalJson,
+  domainManifest,
+  type CanonicalProjectionReturn,
+} from "./manifest.js";
+import {
+  mergeRequiresScope,
+  CompositionViolation,
+  type ComposeOptions,
+} from "./compose.js";
+import type { WireSchema, WireRefMode } from "./wire.js";
+import type { DomainModule } from "./codegen_dart.js";
+
+/** The referential marker of a directive prim (kernel `RefMode` wire string). */
+export type RefMode = WireRefMode;
+
+/**
+ * One prim in the USD IR — a discriminated union UNIFYING #136's manifest content
+ * with #137's composable typed-rule fields.
+ *
+ *  - `aggregate`: an encoded aggregate, carrying its field→`WireDriver` schema (the
+ *    EXACT `manifest.ts` `encodeKernelSchema` output). Aggregates do not compose-merge
+ *    (an aggregate is a single-source schema); they pass through by path.
+ *  - `directive`: a composable law unit. `requires` is the capability set (#137:
+ *    add/narrow, never silently remove); `scope` is the optional composable scope
+ *    path (#137: narrow-not-widen). `payloadRef` is the certified-artifact handle
+ *    — left `undefined` here (stage 2).
+ */
+export type UsdPrim =
+  | {
+      readonly kind: "aggregate";
+      /** e.g. `/Sample/SampleThingAggregate`. */
+      readonly path: string;
+      /** The aggregate type id, e.g. `SampleThingAggregate`. */
+      readonly type: string;
+      /** The encoded field→Driver schema (reused from `manifest.ts`). */
+      readonly schema: WireSchema;
+    }
+  | {
+      readonly kind: "directive";
+      /** e.g. `/Sample/createThing`. */
+      readonly path: string;
+      /** The target aggregate type id. */
+      readonly target: string;
+      readonly marker: RefMode;
+      /** Capability ids that MUST hold (a stronger layer may only ADD). */
+      readonly requires: string[];
+      /**
+       * The composable scope path (#137 narrow-not-widen). `undefined` when the DSL
+       * declares NO static scope today — we do NOT fabricate one.
+       */
+      readonly scope?: string;
+      /**
+       * The directive's DECLARED read boundary (sorted ref types) — the "IR for law
+       * boundaries" carried into the USD IR so `usdHash` reflects it. OMITTED
+       * (`undefined`) when the directive declares no reads, so boundary-free prims are
+       * byte-identical to before this field existed.
+       */
+      readonly reads?: string[];
+      /**
+       * The directive's DECLARED emit boundary: event type → `{ max? }`. OMITTED
+       * (`undefined`) when no emits are declared (omit-when-empty hash invariance).
+       */
+      readonly emits?: Record<string, { max?: number }>;
+      /**
+       * Standard JSON Schema for the directive payload, emitted from TS/Zod into the
+       * IR so cross-language tooling validates against the same schema source.
+       */
+      readonly payloadJsonSchema?: unknown;
+      /** Certified-artifact payload reference — `undefined` for now (stage 2). */
+      readonly payloadRef?: string;
+    };
+
+/** One captured query declaration on a USD layer (read-side closure). `key` is the
+ * index column order, PRESERVED (not sorted). Mirrors `manifest.ts`'s `CanonicalQuery`. */
+export interface UsdQuery {
+  readonly id: string;
+  readonly key: string[];
+  readonly returns: string;
+}
+
+/** One captured derived read projection on a USD layer. */
+export interface UsdDerived {
+  readonly id: string;
+  readonly of: string;
+  readonly returns: CanonicalProjectionReturn;
+}
+
+/** One captured combined read projection on a USD layer. */
+export interface UsdCombined {
+  readonly id: string;
+  readonly of: string;
+  readonly refField: string;
+  readonly reads: string;
+  readonly returns: CanonicalProjectionReturn;
+}
+
+/** One USD layer: a stage path + its prims (canonically sorted by prim path). */
+export interface UsdLayer {
+  readonly path: string;
+  readonly prims: UsdPrim[];
+  /**
+   * The layer's NAMED, INDEXED read declarations (read-side closure step 1), SORTED
+   * by id. OMITTED (`undefined`) when the module declares no query, so a query-free
+   * layer is byte-identical to before this field existed (omit-when-empty hash
+   * invariance). Carried straight from the module's canonical manifest.
+   */
+  readonly queries?: UsdQuery[];
+  /** The layer's engine-projected derived read fields, sorted by id. */
+  readonly deriveds?: UsdDerived[];
+  /** The layer's engine-projected combined read fields, sorted by id. */
+  readonly combineds?: UsdCombined[];
+  /**
+   * The REFERENCE composition arc (LIVRPS: References sit just below Local). Paths of
+   * OTHER layers in the SAME document whose effective prims compose into THIS layer
+   * UNDER (weaker than) its own local prims — local is the stronger opinion. A
+   * first-class declared arc recorded in the IR so the composed identity (`usdHash`)
+   * reflects WHY a prim is present. OMITTED (`undefined`) when a layer references
+   * nothing, so a reference-free layer is byte-identical to before this field existed
+   * (omit-when-empty hash invariance — same discipline as `queries`/`reads`/`emits`).
+   */
+  readonly references?: string[];
+  /**
+   * The VARIANT composition arc (LIVRPS: Variants sit ABOVE References, BELOW Local —
+   * stronger than referenced prims, weaker than this layer's own local prims). A layer
+   * may declare named variant SETS; each set is a family of named ALTERNATIVES, each
+   * alternative ("variant") holding its OWN prims. WHICH variant of each set composes is
+   * NOT baked into the document — it is supplied as `ComposeOptions.variantSelection`
+   * (setName → chosen variantName) at flatten time, so the composed identity is a
+   * function of `(doc, selection)`.
+   *
+   * Shape: setName → variantName → that variant's prims. A reserved variant name `"*"`
+   * within a set declares that set's DEFAULT variant: when the selection names no choice
+   * for the set, the `"*"` variant's prims compose; with neither a selection nor a `"*"`
+   * default, the set contributes NOTHING. A selection naming an unknown set or an unknown
+   * variant fails closed (`variant-unresolved`) — an explicit selection that cannot be
+   * resolved is never silently a no-op.
+   *
+   * OMITTED (`undefined`) when a layer declares no variant set, so a variant-free layer
+   * is byte-identical to before this field existed (omit-when-empty hash invariance —
+   * same discipline as `queries`/`references`/`reads`/`emits`).
+   */
+  readonly variantSets?: Record<string, Record<string, UsdPrim[]>>;
+}
+
+/** The reserved variant name declaring a set's DEFAULT (USD has a default variant). */
+const DEFAULT_VARIANT = "*";
+
+/** The unified USD IR document: ordered (strength) layers. */
+export interface UsdDocument {
+  readonly layers: UsdLayer[];
+}
+
+/** Sort prims by their `path` (canonical structure). */
+function sortPrims(prims: UsdPrim[]): UsdPrim[] {
+  return [...prims].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+
+/**
+ * Encode ONE `DomainModule` into the `UsdPrim`s sitting under `layerPath`. Reuses
+ * `manifest.ts`'s `domainManifest` (and therefore its `encodeKernelSchema` driver encoding)
+ * — no driver-encoding logic is duplicated here. Aggregate prims carry the exact
+ * encoded schema; directive prims map `requiresCapability` → `requires: [cap]`, leave
+ * `scope`/`payloadRef` `undefined` (no static scope today; payload is stage 2).
+ */
+function encodeModuleToPrims(layerPath: string, mod: DomainModule): UsdPrim[] {
+  const manifest = domainManifest(mod);
+  const prims: UsdPrim[] = [];
+
+  for (const agg of manifest.aggregates) {
+    prims.push({
+      kind: "aggregate",
+      path: `${layerPath}/${agg.id}`,
+      type: agg.id,
+      schema: agg.schema,
+    });
+  }
+
+  for (const d of manifest.directives) {
+    prims.push({
+      kind: "directive",
+      path: `${layerPath}/${d.id}`,
+      target: d.target,
+      marker: d.marker,
+      requires: [d.requiresCapability],
+      // Carry the declared law boundary straight from the canonical manifest, which
+      // already applies omit-when-empty: `reads`/`emits` are present here ONLY when the
+      // directive declared them, so a boundary-free prim is byte-identical to before.
+      ...(d.reads !== undefined ? { reads: d.reads } : {}),
+      ...(d.emits !== undefined ? { emits: d.emits } : {}),
+      payloadJsonSchema: d.payloadJsonSchema,
+      // `scope`/`payloadRef` deliberately omitted (undefined): no static scope in
+      // the DSL today, payload is the stage-2 certified artifact.
+    });
+  }
+
+  return sortPrims(prims);
+}
+
+/**
+ * Encode each `{ path, module }` into a `UsdLayer` of prims under that path, returning
+ * the canonical `UsdDocument`: layers SORTED by path, prims SORTED by path.
+ */
+export function emitUsd(
+  layers: { path: string; module: DomainModule }[],
+): UsdDocument {
+  const out: UsdLayer[] = layers
+    .map((l) => {
+      // Carry the domain's declared queries straight from the canonical manifest,
+      // which already applies omit-when-empty: `queries` is present here ONLY when the
+      // module declared them, so a query-free layer is byte-identical to before.
+      const manifest = domainManifest(l.module);
+      return {
+        path: l.path,
+        prims: encodeModuleToPrims(l.path, l.module),
+        ...(manifest.queries !== undefined ? { queries: manifest.queries } : {}),
+        ...(manifest.deriveds !== undefined ? { deriveds: manifest.deriveds } : {}),
+        ...(manifest.combineds !== undefined ? { combineds: manifest.combineds } : {}),
+      };
+    })
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return { layers: out };
+}
+
+/** Two aggregate prims at the same path are identical iff same type + same schema. */
+function aggregateEqual(
+  a: Extract<UsdPrim, { kind: "aggregate" }>,
+  b: Extract<UsdPrim, { kind: "aggregate" }>,
+): boolean {
+  return a.type === b.type && canonicalJson(a.schema) === canonicalJson(b.schema);
+}
+
+/**
+ * Merge a stronger `over` prim onto a `base` prim at the SAME path, per the #137
+ * typed rules — reusing `compose.ts`'s `mergeRequiresScope` for directive prims
+ * (requires add/narrow-not-remove; scope narrow-not-widen; widen/remove need
+ * `authority`). An uncertified payload would always be refused — but `payloadRef`
+ * is unset here (stage 2), so there is nothing to refuse yet.
+ *
+ * Mixing prim KINDS at one path, or redefining an aggregate's schema across layers,
+ * is not a typed monotonic move — it is a structural conflict, surfaced fail-closed.
+ */
+function mergeUsdPrim(base: UsdPrim, over: UsdPrim, opts: ComposeOptions): UsdPrim {
+  if (base.kind !== over.kind) {
+    throw new Error(
+      `USD composition conflict at ${over.path}: cannot merge a ${base.kind} prim ` +
+        `with a ${over.kind} prim.`,
+    );
+  }
+
+  if (base.kind === "aggregate" && over.kind === "aggregate") {
+    // Aggregates are single-source schemas: an identical re-declaration is a no-op
+    // pass-through; a divergent one is a structural conflict (not a monotonic move).
+    if (!aggregateEqual(base, over)) {
+      throw new Error(
+        `USD composition conflict at ${over.path}: aggregate schema redefined ` +
+          `across layers.`,
+      );
+    }
+    return over;
+  }
+
+  // Both directive prims — apply the shared typed requires+scope rule core (#137).
+  if (base.kind === "directive" && over.kind === "directive") {
+    if (base.target !== over.target) {
+      throw new Error(
+        `USD composition conflict at ${over.path}: directive target changed from ` +
+          `"${base.target}" to "${over.target}".`,
+      );
+    }
+    if (base.marker !== over.marker) {
+      throw new Error(
+        `USD composition conflict at ${over.path}: directive marker changed from ` +
+          `"${base.marker}" to "${over.marker}".`,
+      );
+    }
+    if (
+      base.payloadJsonSchema !== undefined &&
+      over.payloadJsonSchema !== undefined &&
+      canonicalJson(base.payloadJsonSchema) !== canonicalJson(over.payloadJsonSchema)
+    ) {
+      throw new Error(
+        `USD composition conflict at ${over.path}: directive payload schema changed.`,
+      );
+    }
+    const merged = mergeRequiresScope(over.path, base, over, opts);
+    const out: Extract<UsdPrim, { kind: "directive" }> = {
+      kind: "directive",
+      path: over.path,
+      target: over.target,
+      marker: over.marker,
+      requires: merged.requires,
+      ...(over.payloadJsonSchema !== undefined
+        ? { payloadJsonSchema: over.payloadJsonSchema }
+        : base.payloadJsonSchema !== undefined
+          ? { payloadJsonSchema: base.payloadJsonSchema }
+          : {}),
+      ...(merged.scope !== undefined ? { scope: merged.scope } : {}),
+      // Preserve the declared law boundary across a monotonic merge (omit-when-empty):
+      // the stronger layer's declaration wins when present, else the base's carries
+      // through; a boundary-free pair stays byte-identical to before this field existed.
+      ...(over.reads !== undefined
+        ? { reads: over.reads }
+        : base.reads !== undefined
+          ? { reads: base.reads }
+          : {}),
+      ...(over.emits !== undefined
+        ? { emits: over.emits }
+        : base.emits !== undefined
+          ? { emits: base.emits }
+          : {}),
+      // payloadRef stays unset (stage 2).
+    };
+    return out;
+  }
+
+  // Unreachable (kinds proven equal above) — exhaustiveness guard.
+  throw new Error(`USD composition: unhandled prim kind at ${over.path}.`);
+}
+
+/** Canonicalize a standalone prim — sort a directive's `requires`. */
+function canonicalizeStandalone(prim: UsdPrim): UsdPrim {
+  if (prim.kind === "directive") {
+    return { ...prim, requires: [...prim.requires].sort() };
+  }
+  return prim;
+}
+
+/**
+ * Fold a stream of prims (already in weak→strong order) into an effective prim map
+ * keyed by path: a path's first contributor passes through (canonicalized); each
+ * later (stronger) contributor MERGES per the #137 typed rules (fail-closed
+ * `CompositionViolation` on any rule it cannot satisfy).
+ */
+function foldPrims(
+  acc: Map<string, UsdPrim>,
+  prims: Iterable<UsdPrim>,
+  opts: ComposeOptions,
+): void {
+  for (const prim of prims) {
+    const existing = acc.get(prim.path);
+    if (existing === undefined) {
+      acc.set(prim.path, canonicalizeStandalone(prim));
+    } else {
+      acc.set(prim.path, mergeUsdPrim(existing, prim, opts));
+    }
+  }
+}
+
+/**
+ * Resolve ONE layer's EFFECTIVE prims (the REFERENCE arc, LIVRPS: References below
+ * Local). Each referenced layer's effective prims are composed FIRST (weaker base),
+ * in declared `references[]` order, then THIS layer's own LOCAL prims fold OVER them
+ * (stronger) via the same typed `mergeUsdPrim`. Resolution is deterministic and
+ * DETECTS CYCLES (A→B→A) via the `stack` of layer paths currently being resolved,
+ * failing closed with a `CompositionViolation`. `byPath` indexes the document's
+ * layers; a reference to an unknown layer path also fails closed.
+ *
+ * VARIANTS (LIVRPS: Variants sit ABOVE References, BELOW Local) resolve AFTER the
+ * reference fold and BEFORE the local fold: the SELECTED variant of each declared set
+ * (or its `"*"` default, else nothing) folds OVER the referenced base (variants are
+ * stronger than references) and UNDER the local prims (local is the strongest), all
+ * through the same monotonic `mergeUsdPrim`. The selection is `opts.variantSelection`,
+ * an explicit flatten input — so the composed identity reflects it. A selection naming
+ * an unknown set or variant fails closed (`variant-unresolved`).
+ */
+function resolveLayerEffective(
+  layer: UsdLayer,
+  byPath: Map<string, UsdLayer>,
+  opts: ComposeOptions,
+  stack: string[],
+): UsdPrim[] {
+  if (stack.includes(layer.path)) {
+    throw new CompositionViolation(
+      "reference-cycle",
+      layer.path,
+      `reference cycle detected: ${[...stack, layer.path].join(" -> ")}`,
+    );
+  }
+
+  const acc = new Map<string, UsdPrim>();
+
+  // References first (weaker), in declared order — each resolved recursively so
+  // transitive references compose and cycles are caught at any depth.
+  if (layer.references !== undefined) {
+    const nextStack = [...stack, layer.path];
+    for (const refPath of layer.references) {
+      const refLayer = byPath.get(refPath);
+      if (refLayer === undefined) {
+        throw new CompositionViolation(
+          "reference-unresolved",
+          layer.path,
+          `references unknown layer path "${refPath}"`,
+        );
+      }
+      foldPrims(acc, resolveLayerEffective(refLayer, byPath, opts, nextStack), opts);
+    }
+  }
+
+  // Variants fold OVER references, UNDER local (LIVRPS variant strength). The selected
+  // variant of each declared set — or its `"*"` default — contributes its prims; an
+  // unselected, default-less set contributes nothing. A selection for an unknown set or
+  // an unknown variant fails closed.
+  foldPrims(acc, selectedVariantPrims(layer, opts), opts);
+
+  // Local prims fold OVER the referenced + variant base (strongest opinion wins).
+  foldPrims(acc, layer.prims, opts);
+
+  return [...acc.keys()].sort().map((path) => acc.get(path)!);
+}
+
+/**
+ * The prims contributed by THIS layer's variant sets under the active selection
+ * (`opts.variantSelection`). For each declared set, in canonical (sorted) set-name
+ * order: if the selection names a variant, that variant's prims are used (unknown set
+ * or unknown variant → `variant-unresolved`, fail-closed); otherwise the set's `"*"`
+ * DEFAULT variant is used when declared, else the set contributes nothing. The
+ * selection is also validated against the layer's declared sets so a selection naming
+ * a set this layer does not declare fails closed too.
+ *
+ * Returns the contributed prims in canonical order (set-name, then prim-path) so the
+ * fold input is deterministic — the fold itself is order-stable for non-overlapping
+ * paths, and any overlap within the variant arc is resolved by the same monotonic rule.
+ */
+function selectedVariantPrims(layer: UsdLayer, opts: ComposeOptions): UsdPrim[] {
+  const sets = layer.variantSets;
+  const selection = opts.variantSelection ?? {};
+
+  if (sets === undefined) return [];
+
+  const out: UsdPrim[] = [];
+  for (const setName of Object.keys(sets).sort()) {
+    const variants = sets[setName]!;
+    const chosen = selection[setName];
+    let variantPrims: UsdPrim[] | undefined;
+    if (chosen !== undefined) {
+      // A selection naming a variant THIS layer's set does not hold fails closed — an
+      // explicit choice that cannot bind to a declared alternative is never silently
+      // dropped to the default / nothing.
+      variantPrims = variants[chosen];
+      if (variantPrims === undefined) {
+        throw new CompositionViolation(
+          "variant-unresolved",
+          layer.path,
+          `variant set "${setName}" has no variant named "${chosen}"`,
+        );
+      }
+    } else {
+      // No explicit choice: the declared default variant, else nothing.
+      variantPrims = variants[DEFAULT_VARIANT];
+    }
+    if (variantPrims !== undefined) {
+      for (const prim of sortPrims(variantPrims)) out.push(prim);
+    }
+  }
+  return out;
+}
+
+/**
+ * Validate the WHOLE selection against the document: each selected set name MUST be
+ * declared by at least ONE layer. A selection naming a set NO layer declares fails
+ * closed (`variant-unresolved`) — an explicit choice that can never bind is never a
+ * silent no-op. (The per-variant check — an unknown variant WITHIN a declared set —
+ * is enforced per-layer in `selectedVariantPrims`, where the set is in scope.) This is
+ * document-scoped because the selection is a single global input to the flatten, while
+ * a given set may be declared on only some of the document's layers.
+ */
+function assertSelectionResolvable(doc: UsdDocument, opts: ComposeOptions): void {
+  const selection = opts.variantSelection;
+  if (selection === undefined) return;
+  const declared = new Set<string>();
+  for (const layer of doc.layers) {
+    if (layer.variantSets !== undefined) {
+      for (const setName of Object.keys(layer.variantSets)) declared.add(setName);
+    }
+  }
+  for (const setName of Object.keys(selection)) {
+    if (!declared.has(setName)) {
+      throw new CompositionViolation(
+        "variant-unresolved",
+        setName,
+        `selection names variant set "${setName}" not declared by any layer`,
+      );
+    }
+  }
+}
+
+/**
+ * Fold the document's layers IN ORDER into the effective flattened prim set.
+ *
+ * Per layer, the REFERENCE arc resolves FIRST (weakest), then the VARIANT arc (the
+ * selected variant of each declared set per `opts.variantSelection`, stronger than
+ * references, weaker than local), then this layer's LOCAL prims (strongest) fold OVER
+ * both (LIVRPS), producing the layer's effective prim set; resolution is deterministic
+ * and fails closed on cycles / unknown reference paths / unresolved variant selections.
+ * Then the existing SUBLAYER fold composes those per-layer
+ * effective prim sets in `layers[]` (strength) order, unchanged: a prim present in
+ * only one layer passes through; a prim a later layer contributes at a path an earlier
+ * layer already defined is MERGED per the #137 typed rules (fail-closed
+ * `CompositionViolation`). Returns the prim set SORTED by path.
+ */
+export function flattenUsd(
+  doc: UsdDocument,
+  opts: ComposeOptions = {},
+): UsdPrim[] {
+  // Fail closed on a selection naming a set NO layer declares (document-scoped — the
+  // selection is a single global input; a set may live on only some layers).
+  assertSelectionResolvable(doc, opts);
+
+  const byPath = new Map<string, UsdLayer>();
+  for (const layer of doc.layers) byPath.set(layer.path, layer);
+
+  const acc = new Map<string, UsdPrim>();
+
+  for (const layer of doc.layers) {
+    const effective = resolveLayerEffective(layer, byPath, opts, []);
+    foldPrims(acc, effective, opts);
+  }
+
+  return [...acc.keys()]
+    .sort()
+    .map((path) => acc.get(path)!);
+}
+
+/**
+ * The composed-IR identity: sha256 hex of `canonicalJson(flattenUsd(doc, opts))`.
+ * Extends #136 (the manifest hash) to a flattened MULTI-LAYER stage, reusing the
+ * same byte-stable canonicalizer.
+ */
+export function usdHash(doc: UsdDocument, opts: ComposeOptions = {}): string {
+  return createHash("sha256")
+    .update(canonicalJson(flattenUsd(doc, opts)), "utf8")
+    .digest("hex");
+}