@githolon/dsl 0.14.0 → 0.16.0

package/src/usd.ts

@@ -33,6 +33,7 @@ import {
   type CanonicalManifest,
   type CanonicalProjectionReturn,
 } from "./manifest.js";
+import type { AggregateHandle } from "./aggregate.js";
 import {
   mergeRequiresScope,
   CompositionViolation,
@@ -40,7 +41,9 @@ import {
 } from "./compose.js";
 import type { WireSchema, WireRefMode } from "./wire.js";
 import type { DomainModule } from "./codegen_dart.js";
+import { domainInterface } from "./shape_compat.js";
 import { relationType, user, key, anyUser } from "./relation_schema.js";
+import { harvestPrincipalFlows } from "./wire_encode.js";
 
 /** The referential marker of a directive prim (kernel `RefMode` wire string). */
 export type RefMode = WireRefMode;
@@ -126,10 +129,46 @@ export interface UsdCombined {
   readonly returns: CanonicalProjectionReturn;
 }
 
+/** One field's read-projection descriptor: the field kind plus a map's value kind. */
+export interface UsdFieldKindDescriptor {
+  readonly kind: string;
+  readonly mapValueKind?: string;
+}
+
+export interface UsdReadProjection {
+  readonly aggregateFieldKinds: Record<string, Record<string, UsdFieldKindDescriptor>>;
+  readonly queries: { id: string; key: { field: string; kind: string }[]; returns: string }[];
+  readonly counts: { id: string; of: string; by: string | null; where?: unknown }[];
+  readonly spatials: { id: string; of: string; on: string }[];
+  readonly deriveds: { id: string; of: string; returns: CanonicalProjectionReturn }[];
+  readonly combineds: { id: string; of: string; refField: string; reads: string; returns: CanonicalProjectionReturn }[];
+  readonly sums?: { id: string; of: string; field: string; by: string | null; where?: unknown }[];
+  readonly mins?: { id: string; of: string; field: string; by: string | null; where?: unknown }[];
+  readonly maxes?: { id: string; of: string; field: string; by: string | null; where?: unknown }[];
+  readonly orderedReads?: {
+    id: string;
+    of: string;
+    orderKey: string;
+    orderDesc?: true;
+    where?: unknown;
+    limit: number;
+  }[];
+}
+
 /** One USD layer: a stage path + its prims (canonically sorted by prim path). */
 export interface UsdLayer {
   readonly path: string;
   readonly prims: UsdPrim[];
+  /**
+   * The canonical admission/merge manifest for this layer, committed inside the package.
+   * Hosts must not stage or mutate this view; holons derive it from active installed law.
+   */
+  readonly nomosIdentityManifest?: CanonicalManifest;
+  /**
+   * The projection schema/read-routing fragment for this layer, committed inside the package.
+   * It carries the projection-only field-kind data that cannot be recovered from merge drivers.
+   */
+  readonly nomosReadProjection?: UsdReadProjection;
   /**
    * 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
@@ -255,6 +294,15 @@ export interface UsdLayer {
    * whose old AND new packages both carry this key is DIFFED BY SID at the one gate.
    */
   readonly nomosStableIds?: import("./stable_ids_types.js").StableIds;
+  /**
+   * THE STRUCTURAL INTERFACE (#72) — this domain's directives (payload shapes) + aggregates
+   * (read shapes, sid-keyed). ON-LEDGER (it rides the package, which installs as the
+   * `policy:{hash}.bundle`), so a client reads the workspace's OFFER straight from the folded
+   * law — reactively, host-blind (architecture/shape_compatibility.md). A client negotiates
+   * shape-compatibility against THIS, not the package hash. Pre-#72 bundles omit it; a client
+   * then reports `offerKnown:false` and never refuses on its absence (era-safe, graceful).
+   */
+  readonly nomosInterface?: import("./shape_compat.js").DomainInterface;
   /**
    * THE CAPTURED-READ GATE DECLARATION (#58). Present IFF ≥1 directive of this layer
    * declares a captured-read query (`.reads(someQuery)`): the law's EXPLICIT opt-in
@@ -304,6 +352,47 @@ export interface UsdLayer {
     readonly v: 1;
     readonly aggregates: Record<string, { scope: string; fields: string[]; delegatable: false }>;
   };
+  /**
+   * THE CAPABILITY DECLARATION IN LAW (Full-A — capability_marketplace.md §4): the impure-
+   * capability quartets (obligation/complete/fail/block/deadLetter) lowered into the SEALED
+   * law, so the holon SURFACES them on the `declared_capabilities` read and the host relays a
+   * deploy-time "declared — bind it or obligations wait" notice without reaching into root
+   * law-state (boundness stays P6 — it is cross-holon root state). OMITTED for capability-free
+   * law (byte-identical hash — the era rule); declaring a capability MOVES the domainHash
+   * (named, expected). SORTED by aggregateId.
+   */
+  readonly nomosCapabilities?: {
+    readonly v: 1;
+    readonly capabilities: readonly {
+      readonly capability: string;
+      readonly aggregateId: string;
+      readonly obligation: string;
+      readonly complete: string;
+      readonly fail: string;
+      readonly block: string;
+      readonly deadLetter: string;
+      readonly tasksQueryId: string | null;
+      /** The HTTPS endpoint the obligation is offered to (outbox); absent ⇒ no destination. */
+      readonly endpoint?: string;
+    }[];
+  };
+  /**
+   * THE FLOW GATE WAIVERS (architecture/security_model.md) — both halves of the audit surface,
+   * hashed into the law + replay-verified. `declassify` (confidentiality, rule 4): every acknowledged
+   * secret-correlated refusal. `endorse` (the integrity dual): every harvested PrincipalEvidence flow
+   * into an authority/standing/attribution sink — discovery IS law, witnessed fail-closed at runtime.
+   * Each half is OMITTED when empty (the era rule — a flow-free domain is byte-identical).
+   */
+  readonly nomosFlowGate?: {
+    readonly v: 1;
+    readonly declassify?: readonly { readonly site: string; readonly reason: string }[];
+    readonly endorse?: readonly {
+      readonly directiveId: string;
+      readonly sink: string;
+      readonly facet: string;
+      readonly reason: string | null;
+    }[];
+  };
 }
 
 /** The reserved variant name declaring a set's DEFAULT (USD has a default variant). */
@@ -363,6 +452,123 @@ function encodeModuleToPrims(layerPath: string, mod: DomainModule): UsdPrim[] {
   return sortPrims(prims);
 }
 
+function aggregateFieldKindsForModule(
+  mod: DomainModule,
+): Record<string, Record<string, UsdFieldKindDescriptor>> {
+  const out: Record<string, Record<string, UsdFieldKindDescriptor>> = {};
+  for (const agg of [...(mod.aggregates as AggregateHandle[])].sort((a, b) =>
+    a.id < b.id ? -1 : a.id > b.id ? 1 : 0,
+  )) {
+    const fields: Record<string, UsdFieldKindDescriptor> = {};
+    for (const name of Object.keys(agg.fields).sort()) {
+      const field = agg.fields[name]!;
+      fields[name] = {
+        kind: field.kind,
+        ...(field.mapValueKind !== undefined ? { mapValueKind: field.mapValueKind } : {}),
+      };
+    }
+    out[agg.id] = fields;
+  }
+  return out;
+}
+
+function readKeyFieldKind(
+  byType: Record<string, Record<string, UsdFieldKindDescriptor>>,
+  queryId: string,
+  returns: string,
+  keyField: string,
+): string {
+  const schema = byType[returns];
+  if (schema === undefined) {
+    throw new Error(
+      `usd: query '${queryId}' returns '${returns}', which has no field schema in nomosReadProjection`,
+    );
+  }
+  const lookup = keyField.includes(".") ? keyField.split(".")[0]! : keyField;
+  const descriptor = schema[lookup];
+  if (descriptor === undefined) {
+    throw new Error(
+      `usd: query '${queryId}' is keyed on '${keyField}' (field '${lookup}'), which '${returns}' does not declare`,
+    );
+  }
+  return descriptor.kind;
+}
+
+function readProjectionForModule(mod: DomainModule, manifest: CanonicalManifest): UsdReadProjection {
+  const aggregateFieldKinds = aggregateFieldKindsForModule(mod);
+  return {
+    aggregateFieldKinds,
+    queries: (manifest.queries ?? []).map((q) => ({
+      id: q.id,
+      key: q.key.map((field) => ({
+        field,
+        kind: readKeyFieldKind(aggregateFieldKinds, q.id, q.returns, field),
+      })),
+      returns: q.returns,
+    })),
+    counts: (manifest.counts ?? []).map((c) => ({
+      id: c.id,
+      of: c.of,
+      by: c.by ?? null,
+      ...(c.where !== undefined ? { where: c.where } : {}),
+    })),
+    spatials: (manifest.spatials ?? []).map((s) => ({ id: s.id, of: s.of, on: s.on })),
+    deriveds: (manifest.deriveds ?? []).map((d) => ({ id: d.id, of: d.of, returns: d.returns })),
+    combineds: (manifest.combineds ?? []).map((c) => ({
+      id: c.id,
+      of: c.of,
+      refField: c.refField,
+      reads: c.reads,
+      returns: c.returns,
+    })),
+    ...((manifest.sums ?? []).length > 0
+      ? {
+          sums: manifest.sums!.map((s) => ({
+            id: s.id,
+            of: s.of,
+            field: s.sumField,
+            by: s.by ?? null,
+            ...(s.where !== undefined ? { where: s.where } : {}),
+          })),
+        }
+      : {}),
+    ...((manifest.mins ?? []).length > 0
+      ? {
+          mins: manifest.mins!.map((e) => ({
+            id: e.id,
+            of: e.of,
+            field: e.valueField,
+            by: e.by ?? null,
+            ...(e.where !== undefined ? { where: e.where } : {}),
+          })),
+        }
+      : {}),
+    ...((manifest.maxes ?? []).length > 0
+      ? {
+          maxes: manifest.maxes!.map((e) => ({
+            id: e.id,
+            of: e.of,
+            field: e.valueField,
+            by: e.by ?? null,
+            ...(e.where !== undefined ? { where: e.where } : {}),
+          })),
+        }
+      : {}),
+    ...((manifest.orderedReads ?? []).length > 0
+      ? {
+          orderedReads: manifest.orderedReads!.map((r) => ({
+            id: r.id,
+            of: r.of,
+            orderKey: r.orderKey,
+            ...(r.orderDesc ? { orderDesc: true as const } : {}),
+            ...(r.where !== undefined ? { where: r.where } : {}),
+            limit: r.limit,
+          })),
+        }
+      : {}),
+  };
+}
+
 /**
  * Lower a layer's `relationType` decls into the canonical `nomosRelations` wire object (P1) —
  * keys SORTED for byte-determinism, omit-when-empty (the era rule). Multiple decls for one type
@@ -546,14 +752,83 @@ export function emitUsd(
           encAggregates[a.id] = { scope: a.requiresRead, fields: [...a.encryptedFields], delegatable: false };
         }
       }
+      // THE CAPABILITY DECLARATION IN LAW (Full-A — capability_marketplace.md §4): the
+      // impure-capability quartets lowered into the SEALED law, so the holon can SURFACE
+      // them on a read (`declared_capabilities`) and the host RELAYS a deploy-time notice
+      // ("declares 'x' — bind it or obligations wait") WITHOUT reaching into root law-state.
+      // Mirrors the deploy-sidecar `capabilityLowerings` extraction; SORTED by aggregate id;
+      // omit-when-empty so capability-free law is byte-identical (the era rule). Declaring a
+      // capability now MOVES the domainHash (named, expected — like the stable-ids key).
+      const nomosCapabilities = [...((l.module as { impureCapabilities?: readonly unknown[] }).impureCapabilities ?? [])]
+        .map((c) => {
+          const k = c as {
+            aggregate: { id: string };
+            obligation: { id: string };
+            complete: { id: string };
+            fail: { id: string };
+            block: { id: string };
+            deadLetter: { id: string };
+            name?: unknown;
+            capability?: unknown;
+            endpoint?: unknown;
+            tasks?: { id?: unknown };
+          };
+          const cap = typeof k.name === "string" ? k.name : typeof k.capability === "string" ? k.capability : null;
+          if (cap === null) return null; // a binding-free quartet declares nothing (omit-when-absent)
+          return {
+            capability: cap,
+            aggregateId: k.aggregate.id,
+            obligation: k.obligation.id,
+            complete: k.complete.id,
+            fail: k.fail.id,
+            block: k.block.id,
+            deadLetter: k.deadLetter.id,
+            tasksQueryId: typeof k.tasks?.id === "string" ? k.tasks.id : null,
+            ...(typeof k.endpoint === "string" ? { endpoint: k.endpoint } : {}),
+          };
+        })
+        .filter((c): c is NonNullable<typeof c> => c !== null)
+        .sort((a, b) => (a.aggregateId < b.aggregateId ? -1 : a.aggregateId > b.aggregateId ? 1 : 0));
+      // THE DECLASSIFY SITES (nomosFlowGate rule 4 — security_model.md): every acknowledged
+      // intended secret-correlated refusal, with its human reason. Hashed into the law (it IS
+      // a law-declared waiver) + replay-verified — "the set of declassify sites is the entire
+      // audit surface". Omit-when-empty: a domain with no declassify is byte-identical.
+      const flowDeclassify = [
+        ...[...(l.module.workspaceInvariants ?? [])]
+          .filter((wi) => typeof (wi as { declassify?: unknown }).declassify === "string")
+          .map((wi) => ({ site: `workspaceInvariant:${wi.id}`, reason: (wi as { declassify: string }).declassify })),
+        ...[...(l.module.aggregates as { id: string; invariantDeclassify?: unknown }[])]
+          .filter((a) => typeof a.invariantDeclassify === "string")
+          .map((a) => ({ site: `aggregateInvariant:${a.id}`, reason: a.invariantDeclassify as string })),
+        ...[...((l.module as { impureCapabilities?: readonly { name?: string; capability?: string; aggregate: { id: string }; declassify?: unknown }[] }).impureCapabilities ?? [])]
+          .filter((c) => typeof c.declassify === "string")
+          .map((c) => ({ site: `capability:${c.name ?? c.capability ?? c.aggregate.id}`, reason: c.declassify as string })),
+      ].sort((a, b) => (a.site < b.site ? -1 : a.site > b.site ? 1 : 0));
+      // THE ENDORSE FLOWS (the integrity dual — security_model.md): discovery IS law. Run each
+      // directive's pure plan with a probe principal + payload and harvest every PrincipalEvidence
+      // conversion's declared flow {directiveId, sink, facet, reason}. Hashed into nomosFlowGate +
+      // witnessed fail-closed at runtime (Slice B). Omit-when-empty (a principal-free domain is
+      // byte-identical). SORTED for determinism.
+      const flowEndorse = [...l.module.directives]
+        .flatMap((d) => harvestPrincipalFlows(d as never).map((f) => ({ directiveId: d.id, sink: f.sink, facet: f.facet, reason: f.reason })))
+        .sort((a, b) =>
+          a.directiveId !== b.directiveId ? (a.directiveId < b.directiveId ? -1 : 1)
+            : a.sink !== b.sink ? (a.sink < b.sink ? -1 : 1)
+              : a.facet < b.facet ? -1 : a.facet > b.facet ? 1 : 0,
+        );
       return {
         path: l.path,
         prims: encodeModuleToPrims(l.path, l.module),
+        nomosIdentityManifest: manifest,
+        nomosReadProjection: readProjectionForModule(l.module, manifest),
         ...(manifest.queries !== undefined ? { queries: manifest.queries } : {}),
         ...(manifest.deriveds !== undefined ? { deriveds: manifest.deriveds } : {}),
         ...(manifest.combineds !== undefined ? { combineds: manifest.combineds } : {}),
         // STABLE IDS (#58): every post-#58 compile carries them (the era key).
         ...(manifest.stableIds !== undefined ? { nomosStableIds: manifest.stableIds } : {}),
+        // THE STRUCTURAL INTERFACE (#72): the on-ledger OFFER — a client negotiates shape-
+        // compatibility against this, reactively, straight from the folded `policy:{hash}.bundle`.
+        nomosInterface: domainInterface(l.module, manifest.stableIds),
         ...(Object.keys(readGateDirectives).length > 0
           ? {
               nomosReadGate: {
@@ -581,6 +856,18 @@ export function emitUsd(
         ...(Object.keys(encAggregates).length > 0
           ? { nomosEncryption: { v: 1 as const, aggregates: encAggregates } }
           : {}),
+        ...(nomosCapabilities.length > 0
+          ? { nomosCapabilities: { v: 1 as const, capabilities: nomosCapabilities } }
+          : {}),
+        ...(flowDeclassify.length > 0 || flowEndorse.length > 0
+          ? {
+              nomosFlowGate: {
+                v: 1 as const,
+                ...(flowDeclassify.length > 0 ? { declassify: flowDeclassify } : {}),
+                ...(flowEndorse.length > 0 ? { endorse: flowEndorse } : {}),
+              },
+            }
+          : {}),
       };
     })
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));

package/src/usd_layers.ts

@@ -143,6 +143,43 @@ function sortedSchema(schema: WireSchema): WireSchema {
   return out;
 }
 
+function domainLayerAttrLines(domain: string, layer: UsdLayer, indent: string): string[] {
+  return [
+    `${indent}custom string nomos:kind = "domain"`,
+    `${indent}custom string nomos:domain = ${usdaString(domain)}`,
+    ...(layer.nomosIdentityManifest !== undefined
+      ? [`${indent}custom string nomos:identityManifestHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosIdentityManifest)))}`]
+      : []),
+    ...(layer.nomosReadProjection !== undefined
+      ? [`${indent}custom string nomos:readProjectionHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosReadProjection)))}`]
+      : []),
+    ...(layer.nomosStableIds !== undefined
+      ? [`${indent}custom string nomos:stableIdsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosStableIds)))}`]
+      : []),
+    ...(layer.nomosInterface !== undefined
+      ? [`${indent}custom string nomos:interfaceHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosInterface)))}`]
+      : []),
+    ...(layer.nomosReadGate !== undefined
+      ? [`${indent}custom string nomos:readGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosReadGate)))}`]
+      : []),
+    ...(layer.nomosReadVisibility !== undefined
+      ? [`${indent}custom string nomos:readVisibilityHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosReadVisibility)))}`]
+      : []),
+    ...(layer.nomosEncryption !== undefined
+      ? [`${indent}custom string nomos:encryptionHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosEncryption)))}`]
+      : []),
+    ...(layer.nomosRelations !== undefined
+      ? [`${indent}custom string nomos:relationsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosRelations)))}`]
+      : []),
+    ...(layer.nomosRelationGate !== undefined
+      ? [`${indent}custom string nomos:relationGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosRelationGate)))}`]
+      : []),
+    ...(layer.nomosAttestationGate !== undefined
+      ? [`${indent}custom string nomos:attestationGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosAttestationGate)))}`]
+      : []),
+  ];
+}
+
 // ── per-module layer emission ────────────────────────────────────────────────────────
 
 /** One authored module of a domain's ordered module list (weak → strong). */
@@ -349,31 +386,9 @@ export function usdaLayerText(
     `{`,
     `    def Scope ${usdaString(primName(domain))}`,
     `    {`,
-    `        custom string nomos:kind = "domain"`,
-    `        custom string nomos:domain = ${usdaString(domain)}`,
-    // STABLE IDS + the captured-read gate (#58): layer-level law keys, hex-carried
+    // Stable ids + holon-owned manifests: layer-level law keys, hex-carried
     // so the .usda round-trips byte-faithfully to the IR layer.
-    ...(layer.nomosStableIds !== undefined
-      ? [`        custom string nomos:stableIdsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosStableIds)))}`]
-      : []),
-    ...(layer.nomosReadGate !== undefined
-      ? [`        custom string nomos:readGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosReadGate)))}`]
-      : []),
-    ...(layer.nomosReadVisibility !== undefined
-      ? [`        custom string nomos:readVisibilityHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosReadVisibility)))}`]
-      : []),
-    ...(layer.nomosEncryption !== undefined
-      ? [`        custom string nomos:encryptionHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosEncryption)))}`]
-      : []),
-    ...(layer.nomosRelations !== undefined
-      ? [`        custom string nomos:relationsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosRelations)))}`]
-      : []),
-    ...(layer.nomosRelationGate !== undefined
-      ? [`        custom string nomos:relationGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosRelationGate)))}`]
-      : []),
-    ...(layer.nomosAttestationGate !== undefined
-      ? [`        custom string nomos:attestationGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosAttestationGate)))}`]
-      : []),
+    ...domainLayerAttrLines(domain, layer, "        "),
     ``,
     ...body,
     `    }`,
@@ -388,8 +403,30 @@ export function usdaLayerText(
  * list is STRONGEST-FIRST, so the list is emitted REVERSED. Same monoid, opposite
  * notation — the reversal IS the correspondence, recorded in the doc string.
  */
-export function layeredRootUsda(sublayerRelPathsWeakToStrong: readonly string[]): string {
+export function layeredRootUsda(
+  sublayerRelPathsWeakToStrong: readonly string[],
+  composed?: UsdDocument,
+): string {
   const strongestFirst = [...sublayerRelPathsWeakToStrong].reverse();
+  const composedDomainOpinions =
+    composed === undefined || composed.layers.length === 0
+      ? []
+      : [
+          ``,
+          `over "Nomos"`,
+          `{`,
+          ...composed.layers.flatMap((layer) => {
+            const domain = layer.path.slice(layer.path.lastIndexOf("/") + 1);
+            return [
+              `    over ${usdaString(primName(domain))}`,
+              `    {`,
+              ...domainLayerAttrLines(domain, layer, "        "),
+              `    }`,
+            ];
+          }),
+          `}`,
+          ``,
+        ];
   return [
     `#usda 1.0`,
     `(`,
@@ -406,6 +443,7 @@ export function layeredRootUsda(sublayerRelPathsWeakToStrong: readonly string[])
     ),
     `    ]`,
     `)`,
+    ...composedDomainOpinions,
     ``,
   ].join("\n");
 }
@@ -461,6 +499,97 @@ function foldById<T extends { readonly id: string }>(
   return [...byId.keys()].sort().map((id) => byId.get(id)!);
 }
 
+function foldByKey<T>(
+  lists: readonly (readonly T[] | undefined)[],
+  keyOf: (item: T) => string,
+): T[] | undefined {
+  const byKey = new Map<string, T>();
+  for (const list of lists) for (const item of list ?? []) byKey.set(keyOf(item), item);
+  if (byKey.size === 0) return undefined;
+  return [...byKey.keys()].sort().map((key) => byKey.get(key)!);
+}
+
+function foldRecord<T>(
+  records: readonly (Readonly<Record<string, T>> | undefined)[],
+): Record<string, T> | undefined {
+  const byKey = new Map<string, T>();
+  for (const record of records) {
+    if (record === undefined) continue;
+    for (const [key, value] of Object.entries(record)) byKey.set(key, value);
+  }
+  if (byKey.size === 0) return undefined;
+  const out: Record<string, T> = {};
+  for (const key of [...byKey.keys()].sort()) out[key] = byKey.get(key)!;
+  return out;
+}
+
+function foldIdentityManifest(
+  stack: readonly UsdLayer[],
+  stableIds: UsdLayer["nomosStableIds"],
+): UsdLayer["nomosIdentityManifest"] {
+  const manifests = stack
+    .map((l) => l.nomosIdentityManifest)
+    .filter((m): m is NonNullable<UsdLayer["nomosIdentityManifest"]> => m !== undefined);
+  if (manifests.length === 0) return undefined;
+  const domain = manifests[manifests.length - 1]!.domain;
+  const workspaceInvariants = foldById(manifests.map((m) => m.workspaceInvariants));
+  const queries = foldById(manifests.map((m) => m.queries));
+  const counts = foldById(manifests.map((m) => m.counts));
+  const spatials = foldById(manifests.map((m) => m.spatials));
+  const sums = foldById(manifests.map((m) => m.sums));
+  const deriveds = foldById(manifests.map((m) => m.deriveds));
+  const combineds = foldById(manifests.map((m) => m.combineds));
+  const mins = foldById(manifests.map((m) => m.mins));
+  const maxes = foldById(manifests.map((m) => m.maxes));
+  const orderedReads = foldById(manifests.map((m) => m.orderedReads));
+  const workspaceTypes = foldById(manifests.map((m) => m.workspaceTypes));
+  const homes = foldRecord(manifests.map((m) => m.homes));
+  const routes = foldByKey(manifests.map((m) => m.routes), (r) => r.directive);
+  return {
+    domain,
+    aggregates: foldById(manifests.map((m) => m.aggregates)) ?? [],
+    directives: foldById(manifests.map((m) => m.directives)) ?? [],
+    ...(stableIds !== undefined ? { stableIds } : {}),
+    ...(workspaceInvariants !== undefined ? { workspaceInvariants } : {}),
+    ...(queries !== undefined ? { queries } : {}),
+    ...(counts !== undefined ? { counts } : {}),
+    ...(spatials !== undefined ? { spatials } : {}),
+    ...(sums !== undefined ? { sums } : {}),
+    ...(deriveds !== undefined ? { deriveds } : {}),
+    ...(combineds !== undefined ? { combineds } : {}),
+    ...(mins !== undefined ? { mins } : {}),
+    ...(maxes !== undefined ? { maxes } : {}),
+    ...(orderedReads !== undefined ? { orderedReads } : {}),
+    ...(workspaceTypes !== undefined ? { workspaceTypes } : {}),
+    ...(homes !== undefined ? { homes } : {}),
+    ...(routes !== undefined ? { routes } : {}),
+  };
+}
+
+function foldReadProjection(stack: readonly UsdLayer[]): UsdLayer["nomosReadProjection"] {
+  const projections = stack
+    .map((l) => l.nomosReadProjection)
+    .filter((p): p is NonNullable<UsdLayer["nomosReadProjection"]> => p !== undefined);
+  if (projections.length === 0) return undefined;
+  const aggregateFieldKinds = foldRecord(projections.map((p) => p.aggregateFieldKinds)) ?? {};
+  const sums = foldById(projections.map((p) => p.sums));
+  const mins = foldById(projections.map((p) => p.mins));
+  const maxes = foldById(projections.map((p) => p.maxes));
+  const orderedReads = foldById(projections.map((p) => p.orderedReads));
+  return {
+    aggregateFieldKinds,
+    queries: foldById(projections.map((p) => p.queries)) ?? [],
+    counts: foldById(projections.map((p) => p.counts)) ?? [],
+    spatials: foldById(projections.map((p) => p.spatials)) ?? [],
+    deriveds: foldById(projections.map((p) => p.deriveds)) ?? [],
+    combineds: foldById(projections.map((p) => p.combineds)) ?? [],
+    ...(sums !== undefined ? { sums } : {}),
+    ...(mins !== undefined ? { mins } : {}),
+    ...(maxes !== undefined ? { maxes } : {}),
+    ...(orderedReads !== undefined ? { orderedReads } : {}),
+  };
+}
+
 /**
  * THE ORDERED OPINION-MAP FOLD: flatten module layers (weak → strong within each
  * stage path) into the effective single-layer-per-domain document. Strongest
@@ -509,6 +638,39 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
         stableIds = { v: 1, domain: domainSid, aggregates };
       }
     }
+    // THE STRUCTURAL INTERFACE (#72): fold per-module interfaces — directives + aggregates merged
+    // later-wins, SORTED keys (matching the composed emission's sorted-key `domainInterface`).
+    let iface: UsdLayer["nomosInterface"];
+    {
+      type Dir = NonNullable<UsdLayer["nomosInterface"]>["directives"][string];
+      type Agg = NonNullable<UsdLayer["nomosInterface"]>["aggregates"][string];
+      const dirs = new Map<string, Dir>();
+      const aggsI = new Map<string, Agg>();
+      let domainI: string | undefined;
+      let domainSidI: string | undefined;
+      for (const l of stack) {
+        if (l.nomosInterface === undefined) continue;
+        domainI = l.nomosInterface.domain;
+        domainSidI = l.nomosInterface.domainSid;
+        for (const [id, spec] of Object.entries(l.nomosInterface.directives)) dirs.set(id, spec);
+        for (const [sid, spec] of Object.entries(l.nomosInterface.aggregates)) aggsI.set(sid, spec);
+      }
+      if (domainI !== undefined) {
+        const directivesRec: Record<string, Dir> = {};
+        for (const k of [...dirs.keys()].sort()) directivesRec[k] = dirs.get(k)!;
+        const aggregatesRec: Record<string, Agg> = {};
+        for (const k of [...aggsI.keys()].sort()) aggregatesRec[k] = aggsI.get(k)!;
+        iface = {
+          v: 1,
+          domain: domainI,
+          ...(domainSidI !== undefined ? { domainSid: domainSidI } : {}),
+          directives: directivesRec,
+          aggregates: aggregatesRec,
+        };
+      }
+    }
+    const identityManifest = foldIdentityManifest(stack, stableIds);
+    const readProjection = foldReadProjection(stack);
     // The captured-read gate (#58): queries + per-directive read sets merged
     // later-wins, SORTED keys (matching the composed emission).
     let readGate: UsdLayer["nomosReadGate"];
@@ -606,10 +768,13 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
     return {
       path,
       prims: [...prims.keys()].sort().map((p) => prims.get(p)!),
+      ...(identityManifest !== undefined ? { nomosIdentityManifest: identityManifest } : {}),
+      ...(readProjection !== undefined ? { nomosReadProjection: readProjection } : {}),
       ...(queries !== undefined ? { queries } : {}),
       ...(deriveds !== undefined ? { deriveds } : {}),
       ...(combineds !== undefined ? { combineds } : {}),
       ...(stableIds !== undefined ? { nomosStableIds: stableIds } : {}),
+      ...(iface !== undefined ? { nomosInterface: iface } : {}),
       ...(readGate !== undefined ? { nomosReadGate: readGate } : {}),
       ...(readVisibility !== undefined ? { nomosReadVisibility: readVisibility } : {}),
       ...(encryption !== undefined ? { nomosEncryption: encryption } : {}),
@@ -733,7 +898,10 @@ function attrStringArray(prim: ParsedPrim, name: string): string[] {
 export function parseUsdaDocument(text: string): UsdDocument {
   const prims = parseUsdaPrims(text);
   const domainByScope = new Map<string, string>();
+  const identityManifestByDomain = new Map<string, UsdLayer["nomosIdentityManifest"]>();
+  const readProjectionByDomain = new Map<string, UsdLayer["nomosReadProjection"]>();
   const stableIdsByDomain = new Map<string, UsdLayer["nomosStableIds"]>();
+  const interfaceByDomain = new Map<string, UsdLayer["nomosInterface"]>();
   const readGateByDomain = new Map<string, UsdLayer["nomosReadGate"]>();
   const readVisibilityByDomain = new Map<string, UsdLayer["nomosReadVisibility"]>();
   const encryptionByDomain = new Map<string, UsdLayer["nomosEncryption"]>();
@@ -744,11 +912,24 @@ export function parseUsdaDocument(text: string): UsdDocument {
     if (p.attrs.get("nomos:kind") === "domain") {
       const domain = attrString(p, "nomos:domain");
       domainByScope.set(p.path, domain);
-      // STABLE IDS + the captured-read gate (#58): the hex-carried layer-level keys.
+      // Holon-owned manifests + gates: the hex-carried layer-level law keys.
+      const idHex = p.attrs.get("nomos:identityManifestHex");
+      if (typeof idHex === "string") {
+        identityManifestByDomain.set(domain, JSON.parse(unhexUtf8(idHex)) as UsdLayer["nomosIdentityManifest"]);
+      }
+      const rpHex = p.attrs.get("nomos:readProjectionHex");
+      if (typeof rpHex === "string") {
+        readProjectionByDomain.set(domain, JSON.parse(unhexUtf8(rpHex)) as UsdLayer["nomosReadProjection"]);
+      }
       const sidHex = p.attrs.get("nomos:stableIdsHex");
       if (typeof sidHex === "string") {
         stableIdsByDomain.set(domain, JSON.parse(unhexUtf8(sidHex)) as UsdLayer["nomosStableIds"]);
       }
+      // THE STRUCTURAL INTERFACE (#72): the on-ledger OFFER, hex-carried per domain layer.
+      const ifaceHex = p.attrs.get("nomos:interfaceHex");
+      if (typeof ifaceHex === "string") {
+        interfaceByDomain.set(domain, JSON.parse(unhexUtf8(ifaceHex)) as UsdLayer["nomosInterface"]);
+      }
       const rgHex = p.attrs.get("nomos:readGateHex");
       if (typeof rgHex === "string") {
         readGateByDomain.set(domain, JSON.parse(unhexUtf8(rgHex)) as UsdLayer["nomosReadGate"]);
@@ -865,7 +1046,10 @@ export function parseUsdaDocument(text: string): UsdDocument {
   const layers: UsdLayer[] = [...buckets.keys()]
     .map((domain) => {
       const b = buckets.get(domain)!;
+      const identity = identityManifestByDomain.get(domain);
+      const readProjection = readProjectionByDomain.get(domain);
       const sids = stableIdsByDomain.get(domain);
+      const iface = interfaceByDomain.get(domain);
       const rg = readGateByDomain.get(domain);
       const rv = readVisibilityByDomain.get(domain);
       const enc = encryptionByDomain.get(domain);
@@ -875,10 +1059,13 @@ export function parseUsdaDocument(text: string): UsdDocument {
       return {
         path: `/Nomos/${domain}`,
         prims: [...b.prims].sort(byPath),
+        ...(identity !== undefined ? { nomosIdentityManifest: identity } : {}),
+        ...(readProjection !== undefined ? { nomosReadProjection: readProjection } : {}),
         ...(b.queries.length > 0 ? { queries: [...b.queries].sort(byId) } : {}),
         ...(b.deriveds.length > 0 ? { deriveds: [...b.deriveds].sort(byId) } : {}),
         ...(b.combineds.length > 0 ? { combineds: [...b.combineds].sort(byId) } : {}),
         ...(sids !== undefined ? { nomosStableIds: sids } : {}),
+        ...(iface !== undefined ? { nomosInterface: iface } : {}),
         ...(rg !== undefined ? { nomosReadGate: rg } : {}),
         ...(rv !== undefined ? { nomosReadVisibility: rv } : {}),
         ...(enc !== undefined ? { nomosEncryption: enc } : {}),