@githolon/dsl 0.1.0

package/src/build_package.ts

@@ -0,0 +1,636 @@
+// 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.
+
+/**
+ * THE GENERIC PACKAGE BUILD SURFACE — `@githolon/dsl/build-package` (#M4).
+ *
+ * BUILD-TIME ONLY (imports `node:crypto` via `./manifest.js`): reached via the
+ * `@githolon/dsl/build-package` subpath, NEVER the runtime barrel — the engine bundle
+ * must stay node-builtin-free (esbuild `--platform=neutral`).
+ *
+ * Hoists, generalized over any tenant's `DomainModule[]`, the machinery the co2
+ * package (`ts_packages/co2-nomos-domains`) hand-rolled:
+ *
+ *   * `composeDomainModule(spec)` — the NAMED-KEYS successor of `emit_dart.ts`'s
+ *     15-positional-parameter `module(...)` helper (dedupe by wire id, the
+ *     impure-capability directive check, default read-models, and the
+ *     HASH-LOAD-BEARING omit-when-empty key discipline).
+ *   * `buildReadManifest(modules)` — the LEVEL-2 read-projection artifact
+ *     (`domain_manifests.json`: aggregateFieldKinds + query/count/spatial/derived/
+ *     combined routing descriptors), hoisted from `emit_manifests.ts`. Field KINDS,
+ *     not drivers — see that file's header for why the split is load-bearing.
+ *   * `buildIdentity(modules)` / `writeIdentity(emit, outDir)` — the per-domain
+ *     IDENTITY manifest + admits_domain_hash registry (#193/#136), hoisted from
+ *     `emit_identity.ts` (palette-gap domains recorded-and-excluded, the
+ *     cross-language sha anchor asserted per emitted domain).
+ *   * `packageUsda(usdJson, javascript)` — the `.package.usda` envelope, byte-exact
+ *     to `build_nomos.mjs` `packageUsda()` == Rust `domain_package_from_js`
+ *     (deterministic-rquickjs/src/domain_package.rs).
+ *   * `emitUsdJsonForModules(modules)` — the one-line USD-IR emit every
+ *     `emit_*_usd_json.ts` wrapped (`emitUsd` over `/Nomos/<domain>` layers).
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { z } from "zod";
+
+import type { AggregateHandle } from "./aggregate.js";
+import type { Directive } from "./directive.js";
+import type { DomainModule, PermissionVocabulary, DartImport } from "./codegen_dart.js";
+import { finishCount, type AnyCount, type CountDecl } from "./count.js";
+import type { QueryDecl } from "./query.js";
+import type { SpatialDecl } from "./spatial.js";
+import type { AnySum } from "./sum.js";
+import type { DerivedDecl } from "./derived.js";
+import type { CombinedDecl } from "./combined.js";
+import type { ImpureCapabilityDecl } from "./codegen_provider_dart.js";
+import { domainHash, emitManifestBytes } from "./manifest.js";
+import { emitUsd } from "./usd.js";
+
+// ─────────────────────────────────────────────────────────────────────────────────
+// composeDomainModule — the named-keys `module(...)`
+// ─────────────────────────────────────────────────────────────────────────────────
+
+/** A domain module's exports bag (scanned by SHAPE, same duck-types as the engine entry). */
+export type Mod = Record<string, unknown>;
+
+/** Collect every exported `AggregateHandle` (dedup is the composer's job). */
+export function aggregatesOf(mod: Mod): AggregateHandle[] {
+  const out: AggregateHandle[] = [];
+  for (const v of Object.values(mod)) {
+    if (
+      v &&
+      typeof v === "object" &&
+      (v as { __isAggregateHandle?: boolean }).__isAggregateHandle === true
+    ) {
+      out.push(v as AggregateHandle);
+    }
+  }
+  return out;
+}
+
+/** Collect every exported `Directive` ({id, plan, aggregateId} duck-type). */
+export function directivesOf(mod: Mod): Directive<any>[] {
+  const out: Directive<any>[] = [];
+  for (const v of Object.values(mod)) {
+    if (
+      v &&
+      typeof v === "object" &&
+      typeof (v as { id?: unknown }).id === "string" &&
+      typeof (v as { plan?: unknown }).plan === "function" &&
+      typeof (v as { aggregateId?: unknown }).aggregateId === "string"
+    ) {
+      out.push(v as Directive<any>);
+    }
+  }
+  return out;
+}
+
+/** The NAMED-KEYS spec for one engine domain (the serialization of `module(...)`). */
+export interface DomainModuleSpec {
+  /** Artifact basename AND (when `domain` is omitted) the engine dispatch key. */
+  readonly name: string;
+  /** The engine dispatch key, when it differs from `name` (e.g. merged `identity`). */
+  readonly domain?: string;
+  /** The ORDERED module list composing this domain (later wins on collision). */
+  readonly modules: readonly Mod[];
+  /** Extra aggregates not exported by the modules (e.g. re-used framework handles). */
+  readonly extraAggregates?: readonly AggregateHandle[];
+  readonly queries?: readonly QueryDecl[];
+  readonly counts?: readonly AnyCount[];
+  readonly readModelAggregates?: readonly string[];
+  readonly deriveds?: readonly DerivedDecl[];
+  readonly combineds?: readonly CombinedDecl[];
+  readonly impureCapabilities?: readonly ImpureCapabilityDecl[];
+  readonly sums?: readonly AnySum[];
+  readonly spatials?: readonly SpatialDecl[];
+  readonly dartImports?: readonly DartImport[];
+  readonly dartRefImports?: DomainModule["dartRefImports"];
+  readonly permissionVocabulary?: PermissionVocabulary;
+}
+
+/**
+ * Compose one `DomainModule` from a spec: spread-merge the module list (the SAME
+ * later-wins merge the engine entry applies, so the manifest lines up 1:1 with what
+ * dispatches), dedupe aggregates by wire id, validate impure capabilities, default
+ * the read-models, and apply the HASH-LOAD-BEARING omit-when-empty key discipline
+ * (an empty optional key must be ABSENT or every domain's canonical manifest hash drifts).
+ */
+export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
+  let merged: Mod = {};
+  for (const m of spec.modules) merged = { ...merged, ...m };
+
+  const byId = new Map<string, AggregateHandle>();
+  for (const a of [...aggregatesOf(merged), ...(spec.extraAggregates ?? [])]) byId.set(a.id, a);
+  const aggregates = [...byId.values()];
+  const directives = directivesOf(merged);
+  const directiveIds = new Set(directives.map((d) => d.id));
+  for (const task of spec.impureCapabilities ?? []) {
+    for (const directive of [task.order, task.complete, task.fail, task.block, task.deadLetter]) {
+      if (!directiveIds.has(directive.id)) {
+        throw new Error(
+          `domain '${spec.domain ?? spec.name}' declares impureCapability '${task.aggregate.id}' ` +
+            `but does not export directive '${directive.id}'`,
+        );
+      }
+    }
+  }
+  const readModels = spec.readModelAggregates ?? aggregates.map((a) => a.id);
+
+  const queries = [...(spec.queries ?? [])];
+  const counts = [...(spec.counts ?? [])];
+  const spatials = [...(spec.spatials ?? [])];
+  const deriveds = [...(spec.deriveds ?? [])];
+  const combineds = [...(spec.combineds ?? [])];
+  const impureCapabilities = [...(spec.impureCapabilities ?? [])];
+  const sums = [...(spec.sums ?? [])];
+  const dartImports = [...(spec.dartImports ?? [])];
+
+  return {
+    name: spec.name,
+    domain: spec.domain ?? spec.name,
+    aggregates,
+    directives,
+    ...(queries.length > 0 ? { queries } : {}),
+    ...(counts.length > 0 ? { counts } : {}),
+    ...(spatials.length > 0 ? { spatials } : {}),
+    ...(deriveds.length > 0 ? { deriveds } : {}),
+    ...(combineds.length > 0 ? { combineds } : {}),
+    ...(readModels.length > 0 ? { readModelAggregates: [...readModels] } : {}),
+    ...(impureCapabilities.length > 0 ? { impureCapabilities } : {}),
+    ...(sums.length > 0 ? { sums } : {}),
+    ...(dartImports.length > 0 ? { dartImports } : {}),
+    ...(spec.dartRefImports !== undefined && spec.dartRefImports.length > 0
+      ? { dartRefImports: [...spec.dartRefImports] }
+      : {}),
+    ...(spec.permissionVocabulary !== undefined
+      ? { permissionVocabulary: spec.permissionVocabulary }
+      : {}),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────────
+// buildReadManifest — domain_manifests.json (hoisted from emit_manifests.ts)
+// ─────────────────────────────────────────────────────────────────────────────────
+
+/** One field's read-projection descriptor: the leaf kind (+ a map's value kind). */
+export interface FieldKindDescriptor {
+  kind: string;
+  mapValueKind?: string;
+}
+export type AggregateSchema = Record<string, FieldKindDescriptor>;
+export type AggregateFieldKinds = Record<string, AggregateSchema>;
+
+export interface QueryKeyField {
+  field: string;
+  kind: string;
+}
+export interface QueryDescriptor {
+  id: string;
+  key: QueryKeyField[];
+  returns: string;
+}
+export interface CountDescriptor {
+  id: string;
+  of: string;
+  by: string | null;
+}
+export interface SpatialDescriptor {
+  id: string;
+  of: string;
+  on: string;
+}
+export interface ProjectionReturnDescriptor {
+  type: string;
+  nullable: boolean;
+  jsonSchema: unknown;
+}
+export interface DerivedDescriptor {
+  id: string;
+  of: string;
+  returns: ProjectionReturnDescriptor;
+}
+export interface CombinedDescriptor {
+  id: string;
+  of: string;
+  refField: string;
+  reads: string;
+  returns: ProjectionReturnDescriptor;
+}
+
+/** The combined read-manifest artifact (the EXACT wire shape the Rust read engine parses). */
+export interface ReadManifest {
+  aggregateFieldKinds: AggregateFieldKinds;
+  queries: QueryDescriptor[];
+  counts: CountDescriptor[];
+  spatials: SpatialDescriptor[];
+  deriveds: DerivedDescriptor[];
+  combineds: CombinedDescriptor[];
+}
+
+type ZodLike = {
+  _def?: { type?: string; innerType?: ZodLike };
+  def?: { type?: string; innerType?: ZodLike };
+};
+
+function zodDef(zt: ZodLike): NonNullable<ZodLike["_def"]> {
+  return zt._def ?? zt.def ?? {};
+}
+
+function zodTypeName(zt: ZodLike): string {
+  return zodDef(zt).type ?? "unknown";
+}
+
+function describeProjectionReturn(schema: z.ZodTypeAny): ProjectionReturnDescriptor {
+  let cur = schema as unknown as ZodLike;
+  let nullable = false;
+  while (
+    zodTypeName(cur) === "optional" ||
+    zodTypeName(cur) === "default" ||
+    zodTypeName(cur) === "nullable"
+  ) {
+    nullable = true;
+    const inner = zodDef(cur).innerType;
+    if (inner === undefined) break;
+    cur = inner;
+  }
+  return {
+    type: zodTypeName(cur),
+    nullable,
+    jsonSchema: z.toJSONSchema(schema),
+  };
+}
+
+/** Capture one aggregate's field KINDS straight off the DSL `Field` objects. */
+function schemaOf(agg: AggregateHandle): AggregateSchema {
+  const fields: AggregateSchema = {};
+  // STORED fields only — virtual `t.hasMany` inverses are partitioned into `agg.hasMany`.
+  for (const [name, field] of Object.entries(agg.fields)) {
+    const descriptor: FieldKindDescriptor = { kind: field.kind };
+    if (field.mapValueKind !== undefined) descriptor.mapValueKind = field.mapValueKind;
+    fields[name] = descriptor;
+  }
+  return fields;
+}
+
+/** Stable JSON for an aggregate schema, to detect a genuine cross-domain divergence. */
+function stable(schema: AggregateSchema): string {
+  const sorted: AggregateSchema = {};
+  for (const k of Object.keys(schema).sort()) sorted[k] = schema[k]!;
+  return JSON.stringify(sorted);
+}
+
+/**
+ * Resolve the routing KIND of one query KEY FIELD against the returns-type's field
+ * schema. NO FALLBACK: an undeclared key field is a declaration bug — THROW.
+ */
+function keyFieldKind(
+  byType: AggregateFieldKinds,
+  queryId: string,
+  returns: string,
+  keyField: string,
+): string {
+  const schema = byType[returns];
+  if (schema === undefined) {
+    throw new Error(
+      `build-package: query '${queryId}' returns '${returns}', which has no field ` +
+        `schema — the returns handle must be an aggregate emitted into the manifest.`,
+    );
+  }
+  // A dotted key indexes a sub-value of a top-level JSON leaf; kind off the leading field.
+  const lookup = keyField.includes(".") ? keyField.split(".")[0]! : keyField;
+  const descriptor = schema[lookup];
+  if (descriptor === undefined) {
+    throw new Error(
+      `build-package: query '${queryId}' is keyed on '${keyField}' (field '${lookup}'), ` +
+        `which '${returns}' does not declare — a query cannot index an undefined field.`,
+    );
+  }
+  return descriptor.kind;
+}
+
+function describeQuery(byType: AggregateFieldKinds, q: QueryDecl): QueryDescriptor {
+  return {
+    id: q.id,
+    key: q.key.map((field) => ({
+      field,
+      kind: keyFieldKind(byType, q.id, q.returns, field),
+    })),
+    returns: q.returns,
+  };
+}
+
+function describeCount(byType: AggregateFieldKinds, c: CountDecl): CountDescriptor {
+  if (byType[c.of] === undefined) {
+    throw new Error(
+      `build-package: count '${c.id}' tallies '${c.of}', which has no field schema — ` +
+        `the of-type must be an aggregate emitted into the manifest.`,
+    );
+  }
+  return { id: c.id, of: c.of, by: c.by ?? null };
+}
+
+function describeSpatial(byType: AggregateFieldKinds, s: SpatialDecl): SpatialDescriptor {
+  const schema = byType[s.of];
+  if (schema === undefined) {
+    throw new Error(
+      `build-package: spatial '${s.id}' covers '${s.of}', which has no field schema — ` +
+        `the of-type must be an aggregate emitted into the manifest.`,
+    );
+  }
+  if (schema[s.on] === undefined) {
+    throw new Error(
+      `build-package: spatial '${s.id}' indexes geometry field '${s.on}' on '${s.of}', ` +
+        `which '${s.of}' does not declare — the geometry field must exist (no fallback).`,
+    );
+  }
+  return { id: s.id, of: s.of, on: s.on };
+}
+
+function describeDerived(byType: AggregateFieldKinds, d: DerivedDecl): DerivedDescriptor {
+  if (byType[d.of] === undefined) {
+    throw new Error(
+      `build-package: derived '${d.id}' derives from '${d.of}', which has no field ` +
+        `schema — the of-type must be an aggregate emitted into the manifest.`,
+    );
+  }
+  return { id: d.id, of: d.of, returns: describeProjectionReturn(d.returns) };
+}
+
+function describeCombined(byType: AggregateFieldKinds, c: CombinedDecl): CombinedDescriptor {
+  if (byType[c.of] === undefined) {
+    throw new Error(
+      `build-package: combined '${c.id}' lives on '${c.of}', which has no field ` +
+        `schema — the of-type must be an aggregate emitted into the manifest.`,
+    );
+  }
+  if (byType[c.reads] === undefined) {
+    throw new Error(
+      `build-package: combined '${c.id}' reads '${c.reads}', which has no field ` +
+        `schema — the queried type must be an aggregate emitted into the manifest.`,
+    );
+  }
+  return {
+    id: c.id,
+    of: c.of,
+    refField: c.refField,
+    reads: c.reads,
+    returns: describeProjectionReturn(c.returns),
+  };
+}
+
+/**
+ * Build the single combined READ manifest for the modules (`domain_manifests.json`).
+ * Hoisted VERBATIM-in-behaviour from `emit_manifests.ts` `buildManifests` — sorted
+ * keys/arrays for byte-stability, divergence detection across domains, NO-FALLBACK
+ * throws on undeclared of-types (the Rust parse would reject them anyway, loudly,
+ * and break ALL reads for the workspace — fail at build instead).
+ */
+export function buildReadManifest(modules: readonly DomainModule[]): ReadManifest {
+  const byType: AggregateFieldKinds = {};
+  for (const mod of modules) {
+    for (const agg of mod.aggregates as AggregateHandle[]) {
+      const schema = schemaOf(agg);
+      const existing = byType[agg.id];
+      if (existing !== undefined && stable(existing) !== stable(schema)) {
+        throw new Error(
+          `build-package: aggregate '${agg.id}' has DIVERGENT field schemas across ` +
+            `domains — the read projection cannot have two shapes for one wire type. ` +
+            `Reconcile the aggregate definition.`,
+        );
+      }
+      byType[agg.id] = schema;
+    }
+  }
+  const sorted: AggregateFieldKinds = {};
+  for (const k of Object.keys(byType).sort()) sorted[k] = byType[k]!;
+
+  const byId = new Map<string, QueryDescriptor>();
+  for (const mod of modules) {
+    for (const q of mod.queries ?? []) {
+      const descriptor = describeQuery(sorted, q);
+      const existing = byId.get(q.id);
+      if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(descriptor)) {
+        throw new Error(
+          `build-package: query id '${q.id}' is declared with DIVERGENT routing across ` +
+            `domains — one id cannot map to two routes. Reconcile the query declaration.`,
+        );
+      }
+      byId.set(q.id, descriptor);
+    }
+  }
+  const queries = [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+
+  const countsById = new Map<string, CountDescriptor>();
+  for (const mod of modules) {
+    for (const raw of mod.counts ?? []) {
+      const c = finishCount(raw);
+      const descriptor = describeCount(sorted, c);
+      const existing = countsById.get(c.id);
+      if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(descriptor)) {
+        throw new Error(
+          `build-package: count id '${c.id}' is declared with DIVERGENT maintenance across ` +
+            `domains — one id cannot map to two counters. Reconcile the count declaration.`,
+        );
+      }
+      countsById.set(c.id, descriptor);
+    }
+  }
+  const counts = [...countsById.values()].sort((a, b) => a.id.localeCompare(b.id));
+
+  const spatialsById = new Map<string, SpatialDescriptor>();
+  for (const mod of modules) {
+    for (const s of mod.spatials ?? []) {
+      const descriptor = describeSpatial(sorted, s);
+      const existing = spatialsById.get(s.id);
+      if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(descriptor)) {
+        throw new Error(
+          `build-package: spatial id '${s.id}' is declared with DIVERGENT maintenance across ` +
+            `domains — one id cannot map to two indexes. Reconcile the spatial declaration.`,
+        );
+      }
+      spatialsById.set(s.id, descriptor);
+    }
+  }
+  const spatials = [...spatialsById.values()].sort((a, b) => a.id.localeCompare(b.id));
+
+  const derivedsByNamespaceAndId = new Map<string, DerivedDescriptor>();
+  for (const mod of modules) {
+    for (const d of mod.deriveds ?? []) {
+      const descriptor = describeDerived(sorted, d);
+      const key = `${descriptor.of}\u0000${descriptor.id}`;
+      const existing = derivedsByNamespaceAndId.get(key);
+      if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(descriptor)) {
+        throw new Error(
+          `build-package: derived field '${descriptor.of}.${descriptor.id}' is declared ` +
+            `with DIVERGENT projection across domains. Reconcile the declaration.`,
+        );
+      }
+      derivedsByNamespaceAndId.set(key, descriptor);
+    }
+  }
+  const deriveds = [...derivedsByNamespaceAndId.values()].sort(
+    (a, b) => a.of.localeCompare(b.of) || a.id.localeCompare(b.id),
+  );
+
+  const combinedsByNamespaceAndId = new Map<string, CombinedDescriptor>();
+  for (const mod of modules) {
+    for (const c of mod.combineds ?? []) {
+      const descriptor = describeCombined(sorted, c);
+      const key = `${descriptor.of}\u0000${descriptor.id}`;
+      const existing = combinedsByNamespaceAndId.get(key);
+      if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(descriptor)) {
+        throw new Error(
+          `build-package: combined field '${descriptor.of}.${descriptor.id}' is declared ` +
+            `with DIVERGENT projection across domains. Reconcile the declaration.`,
+        );
+      }
+      combinedsByNamespaceAndId.set(key, descriptor);
+    }
+  }
+  const combineds = [...combinedsByNamespaceAndId.values()].sort(
+    (a, b) => a.of.localeCompare(b.of) || a.id.localeCompare(b.id),
+  );
+
+  return { aggregateFieldKinds: sorted, queries, counts, spatials, deriveds, combineds };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────────
+// buildIdentity / writeIdentity — the IDENTITY artifacts (hoisted from emit_identity.ts)
+// ─────────────────────────────────────────────────────────────────────────────────
+
+/** One domain that could not produce a canonical identity, with the reason recorded. */
+export interface ExcludedDomain {
+  readonly domain: string;
+  readonly reason: string;
+}
+
+/** The result of emitting the identity manifest over a set of domain modules. */
+export interface IdentityEmit {
+  /** `{domain: canonicalManifestString}` — the gate's NOMOS_DOMAIN_MANIFEST shape. */
+  readonly manifests: Record<string, string>;
+  /** `{domain: sha256(canonicalManifest)}` — the certified hash registry. */
+  readonly hashes: Record<string, string>;
+  /** Domains OMITTED because they have no canonical identity (palette gap), recorded. */
+  readonly excluded: ExcludedDomain[];
+}
+
+/**
+ * Build the identity manifest + hashes. A domain whose canonical manifest THROWS (a
+ * palette-only driver the kernel cannot lower) is RECORDED in `excluded` and omitted —
+ * never fabricated. The cross-language anchor (`sha256(bytes) === domainHash`) is
+ * asserted for every EMITTED domain; an anchor failure is a hard error.
+ */
+export function buildIdentity(modules: readonly DomainModule[]): IdentityEmit {
+  const manifests: Record<string, string> = {};
+  const hashes: Record<string, string> = {};
+  const excluded: ExcludedDomain[] = [];
+
+  for (const mod of [...modules].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+    let bytes: Buffer;
+    let hash: string;
+    try {
+      bytes = emitManifestBytes(mod);
+      hash = domainHash(mod);
+    } catch (e) {
+      // No canonical identity under the current kernel palette — record, do not fabricate.
+      excluded.push({ domain: mod.name, reason: (e as Error).message });
+      continue;
+    }
+    const fileHash = createHash("sha256").update(bytes).digest("hex");
+    if (fileHash !== hash) {
+      throw new Error(
+        `build-package: ${mod.name} manifest-byte sha256 ${fileHash} != domainHash ${hash} — ` +
+          `the identity anchor is broken (the gate would reject these bytes).`,
+      );
+    }
+    manifests[mod.name] = bytes.toString("utf8");
+    hashes[mod.name] = hash;
+  }
+
+  if (Object.keys(manifests).length === 0) {
+    throw new Error(
+      "build-package: produced NO domain identities — refusing to emit an empty registry.",
+    );
+  }
+  return { manifests, hashes, excluded };
+}
+
+/**
+ * Serialize the identity emit to its on-disk artifacts. The consumed maps stay
+ * STRICTLY `{domain: value}` (the Rust `parse_identity_map` treats EVERY key as a
+ * domain and fail-closes the WHOLE map on one bad entry); the exclusion record goes
+ * to a SEPARATE sidecar the gate never reads.
+ */
+export function writeIdentity(
+  emit: IdentityEmit,
+  outDir: string,
+): { manifestsPath: string; hashesPath: string; excludedPath: string } {
+  mkdirSync(outDir, { recursive: true });
+  const manifestsPath = join(outDir, "domain_identity_manifests.json");
+  const hashesPath = join(outDir, "domain_identity_hashes.json");
+  const excludedPath = join(outDir, "domain_identity_excluded.json");
+  writeFileSync(manifestsPath, JSON.stringify(emit.manifests, null, 2) + "\n", "utf8");
+  writeFileSync(hashesPath, JSON.stringify(emit.hashes, null, 2) + "\n", "utf8");
+  writeFileSync(excludedPath, JSON.stringify(emit.excluded, null, 2) + "\n", "utf8");
+  return { manifestsPath, hashesPath, excludedPath };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────────
+// The .package.usda envelope + the USD-IR emit
+// ─────────────────────────────────────────────────────────────────────────────────
+
+/** The package format marker the kernel checks (domain_package.rs / build_nomos.mjs). */
+export const NOMOS_DOMAIN_PACKAGE_FORMAT = "nomos.openusd-ir-package.v1";
+
+/** Lowercase hex of the UTF-8 bytes (== build_nomos.mjs `hexUtf8` == Rust `hex_encode`). */
+export function hexUtf8(text: string): string {
+  return Buffer.from(text, "utf8").toString("hex");
+}
+
+/**
+ * The `.package.usda` envelope — BYTE-EXACT to `build_nomos.mjs` `packageUsda()` and
+ * Rust `domain_package_from_js` (deterministic-rquickjs/src/domain_package.rs:11-33).
+ * The kernel's acceptance is substring-based field extraction over this template; the
+ * domainHash the deploy names is sha256 over the WHOLE returned string (trailing
+ * newline included) exactly as committed.
+ */
+export function packageUsda(usdJson: string, javascript: string): string {
+  return `#usda 1.0
+(
+    customData = {
+        string nomos:format = "${NOMOS_DOMAIN_PACKAGE_FORMAT}"
+    }
+)
+
+def "NomosDomainPackage"
+{
+    custom string nomos:usdJsonHex = "${hexUtf8(usdJson)}"
+    custom string nomos:executable:language = "javascript"
+    custom string nomos:executable:javascriptHex = "${hexUtf8(javascript)}"
+}
+`;
+}
+
+/**
+ * The USD-IR JSON for a package's modules: `emitUsd` over `/Nomos/<domain>` layers,
+ * `JSON.stringify`'d EXACTLY like every `emit_*_usd_json.ts` (single line, insertion
+ * order — `emitUsd`'s sorted layers/prims are what make it reproducible; do NOT
+ * canonicalize or pretty-print, the package hash rides on these bytes).
+ */
+export function emitUsdJsonForModules(modules: readonly DomainModule[]): string {
+  const doc = emitUsd(
+    modules.map((mod) => ({ path: `/Nomos/${mod.domain ?? mod.name}`, module: mod })),
+  );
+  return JSON.stringify(doc);
+}
+
+/** sha256 hex over a UTF-8 string — the deploy identity (`policy:{hash}`). */
+export function sha256HexUtf8(text: string): string {
+  return createHash("sha256").update(Buffer.from(text, "utf8")).digest("hex");
+}