@githolon/dsl 0.15.0 → 0.16.1

package/src/shape_compat.ts

@@ -0,0 +1,208 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact.  If a file isn't this / hosting this / authoring for this
+// / proving this — it's gone.
+//
+// SHAPE COMPATIBILITY (#72) — the structural contract a client and a workspace
+// negotiate by, INSTEAD of the package hash. See architecture/shape_compatibility.md.
+//
+// A client fits a workspace iff the workspace's installed interface SUBTYPES what the
+// client depends on:
+//   • WRITES are CONTRAVARIANT — for every directive the client calls, the workspace
+//     has that directive id and its CURRENT payload schema ACCEPTS the client's
+//     payload: every field the workspace REQUIRES the client always sends, and every
+//     shared field's kind matches. (Extra client fields are ignored — non-strict zod.)
+//   • READS are COVARIANT by STABLE ID (#58) — for every aggregate the client reads,
+//     the workspace has that aggregate SID and every field the client CONSUMES (by
+//     field sid) is present with a compatible kind. The workspace may serve MORE.
+//
+// Identity is by stable id, not name or hash — that is what makes the relation
+// decidable across renames (a renamed aggregate field keeps its sid, so an old client
+// stays read-compatible). Directive/payload identity is the dispatched id + field
+// names (directives are not sid-tracked yet — a payload rename IS a write break, and
+// is reported precisely).
+
+import { z } from "zod";
+import { introspectPayload, type DomainModule, type PayloadFieldSpec } from "./codegen_dart.js";
+import type { StableIds } from "./stable_ids_types.js";
+import type { Field } from "./fields.js";
+
+/** One payload field's normalized shape: its kind + whether the schema makes it optional. */
+export interface PayloadFieldShape {
+  readonly kind: string;
+  readonly optional: boolean;
+}
+/** A directive's payload contract — the field set + types the gate validates against. */
+export interface DirectivePayloadShape {
+  readonly fields: Record<string, PayloadFieldShape>;
+}
+/** An aggregate's read contract — fields keyed by STABLE ID (rename-safe), each carrying
+ *  its current label (for human-readable verdicts) + its read kind. */
+export interface AggregateReadShape {
+  readonly sid: string;
+  readonly label: string;
+  /** keyed by FIELD SID. */
+  readonly fields: Record<string, { kind: string; label: string }>;
+}
+/** A domain's full structural interface — the offer (a workspace's installed law) AND
+ *  the requirement (the law a client was generated from) are the SAME vocabulary. */
+export interface DomainInterface {
+  readonly v: 1;
+  readonly domain: string;
+  readonly domainSid?: string;
+  /** keyed by DIRECTIVE ID (the dispatched name). */
+  readonly directives: Record<string, DirectivePayloadShape>;
+  /** keyed by AGGREGATE SID. */
+  readonly aggregates: Record<string, AggregateReadShape>;
+}
+
+/** The verdict: compatible iff nothing is missing and nothing is type-incompatible.
+ *  `missing` = a depended-on directive/aggregate/field the workspace doesn't expose;
+ *  `incompatible` = present but type-divergent (a payload field kind, a retyped read field). */
+export interface CompatVerdict {
+  readonly ok: boolean;
+  readonly missing: string[];
+  readonly incompatible: string[];
+}
+
+/** Normalize a directive payload field to a language-neutral kind from its introspected
+ *  spec (the SAME `introspectPayload` the Dart/TS clients are generated from, so both
+ *  sides of a comparison speak one vocabulary). */
+function payloadFieldKind(spec: PayloadFieldSpec): string {
+  switch (spec.toJson) {
+    case "enum":
+      return "enum";
+    case "strList":
+      return "set";
+    case "json":
+      return "json";
+    case "scalar":
+    default:
+      switch (spec.dartType) {
+        case "int":
+          return "int";
+        case "double":
+          return "double";
+        case "bool":
+          return "bool";
+        default:
+          return "string";
+      }
+  }
+}
+
+/** The aggregate read kind when no stable-id kind is recorded (pre-#58 fallback): the
+ *  field's own declared kind, with the read-collapsed CRDTs normalized to their scalar. */
+function aggFieldReadKind(f: Field): string {
+  switch (f.kind) {
+    case "counter":
+      return "int";
+    case "position":
+      return "string";
+    default:
+      return f.kind;
+  }
+}
+
+/** Extract a domain's structural interface from its loaded module + (optionally) its
+ *  stable-id surface. Without stable ids (pre-#58) aggregate fields key by NAME and the
+ *  kind comes from the field declaration — a graceful, rename-unaware fallback. */
+export function domainInterface(mod: DomainModule, stableIds?: StableIds): DomainInterface {
+  const enumTypes = new Map<string, string>();
+  // DETERMINISTIC KEY ORDER — directive ids, aggregate sids, and field keys are SORTED, so the
+  // emitted interface is byte-stable and the layered-USD fold (which merges + sorts) reproduces it
+  // byte-identically (the `nomosStableIds`/`nomosReadGate` convention). architecture/shape_compatibility.md.
+  const sortedRec = <T>(entries: Array<[string, T]>): Record<string, T> => {
+    const out: Record<string, T> = {};
+    for (const [k, v] of entries.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))) out[k] = v;
+    return out;
+  };
+  const directives: Record<string, DirectivePayloadShape> = {};
+  const dirEntries: Array<[string, DirectivePayloadShape]> = [];
+  for (const d of (mod.directives ?? []) as Array<{ id?: unknown; payloadSchema?: unknown }>) {
+    if (!d || typeof d.id !== "string") continue;
+    const fieldEntries: Array<[string, PayloadFieldShape]> = [];
+    const schema = d.payloadSchema;
+    if (schema && typeof schema === "object") {
+      for (const spec of introspectPayload(schema as z.ZodTypeAny, enumTypes)) {
+        fieldEntries.push([spec.name, { kind: payloadFieldKind(spec), optional: !!spec.optional }]);
+      }
+    }
+    dirEntries.push([d.id, { fields: sortedRec(fieldEntries) }]);
+  }
+  Object.assign(directives, sortedRec(dirEntries));
+  const aggregates: Record<string, AggregateReadShape> = {};
+  const aggEntries: Array<[string, AggregateReadShape]> = [];
+  for (const agg of (mod.aggregates ?? []) as Array<{ id: string; fields: Record<string, Field> }>) {
+    const label = agg.id;
+    const sa = stableIds?.aggregates?.[label];
+    const aggSid = sa?.sid ?? label;
+    const fieldEntries: Array<[string, { kind: string; label: string }]> = [];
+    for (const [fname, f] of Object.entries(agg.fields ?? {})) {
+      if (!f || f.kind === "hasMany") continue;
+      const fsid = sa?.fields?.[fname]?.sid ?? fname;
+      const kind = sa?.fields?.[fname]?.kind ?? aggFieldReadKind(f);
+      fieldEntries.push([fsid, { kind, label: fname }]);
+    }
+    aggEntries.push([aggSid, { sid: aggSid, label, fields: sortedRec(fieldEntries) }]);
+  }
+  Object.assign(aggregates, sortedRec(aggEntries));
+  return {
+    v: 1,
+    domain: (mod as { domain?: string; name?: string }).domain ?? (mod as { name?: string }).name ?? "",
+    ...(stableIds?.domain !== undefined ? { domainSid: stableIds.domain } : {}),
+    directives,
+    aggregates,
+  };
+}
+
+/** Decide whether a CLIENT interface is satisfied by a WORKSPACE interface (the offer).
+ *  Pure + deterministic — the SAME relation runs at connect() and (mirrored) at the
+ *  editor/CI. Names the exact directive / aggregate / field at fault, never a hash. */
+export function compatible(client: DomainInterface, workspace: DomainInterface): CompatVerdict {
+  const missing: string[] = [];
+  const incompatible: string[] = [];
+
+  // WRITES — contravariant. The workspace must accept every payload the client sends.
+  for (const [did, cShape] of Object.entries(client.directives)) {
+    const wShape = workspace.directives[did];
+    if (!wShape) {
+      missing.push(`directive '${did}'`);
+      continue;
+    }
+    // Every field the WORKSPACE requires, the client must ALWAYS send (present + required).
+    for (const [f, wf] of Object.entries(wShape.fields)) {
+      if (wf.optional) continue;
+      const cf = cShape.fields[f];
+      if (!cf || cf.optional) {
+        incompatible.push(`directive '${did}': workspace requires field '${f}' the client does not always send`);
+      }
+    }
+    // Every field both sides know must agree on kind (a payload retype is a write break).
+    for (const [f, cf] of Object.entries(cShape.fields)) {
+      const wf = wShape.fields[f];
+      if (wf && wf.kind !== cf.kind) {
+        incompatible.push(`directive '${did}': field '${f}' kind ${cf.kind} ≠ workspace ${wf.kind}`);
+      }
+    }
+  }
+
+  // READS — covariant by stable id. Every field the client consumes must be served compatibly.
+  for (const [sid, cAgg] of Object.entries(client.aggregates)) {
+    const wAgg = workspace.aggregates[sid];
+    if (!wAgg) {
+      missing.push(`aggregate '${cAgg.label}'`);
+      continue;
+    }
+    for (const [fsid, cf] of Object.entries(cAgg.fields)) {
+      const wf = wAgg.fields[fsid];
+      if (!wf) {
+        missing.push(`field '${cAgg.label}.${cf.label}'`);
+      } else if (wf.kind !== cf.kind) {
+        incompatible.push(`field '${cAgg.label}.${cf.label}': read kind ${cf.kind} ≠ workspace ${wf.kind}`);
+      }
+    }
+  }
+
+  return { ok: missing.length === 0 && incompatible.length === 0, missing, incompatible };
+}

package/src/usd.ts

@@ -41,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;
@@ -292,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
@@ -341,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). */
@@ -700,6 +752,70 @@ 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),
@@ -710,6 +826,9 @@ export function emitUsd(
         ...(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: {
@@ -737,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

@@ -156,6 +156,9 @@ function domainLayerAttrLines(domain: string, layer: UsdLayer, indent: string):
     ...(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)))}`]
       : []),
@@ -635,6 +638,37 @@ 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
@@ -740,6 +774,7 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
       ...(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 } : {}),
@@ -866,6 +901,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
   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"]>();
@@ -889,6 +925,11 @@ export function parseUsdaDocument(text: string): UsdDocument {
       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"]);
@@ -1008,6 +1049,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
       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);
@@ -1023,6 +1065,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
         ...(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 } : {}),

package/src/wire.ts

@@ -127,6 +127,14 @@ export interface WireIntent {
   strikes: string[];
   events: WireEvent[];
   reads?: WireRead[];
+  /**
+   * THE OBSERVED ENDORSE FOOTPRINT (security_model.md — the integrity dual, Slice B): every
+   * PrincipalEvidence flow this plan run actually produced `{sink, facet, reason}`. A TRANSIENT
+   * verify-input — it rides the plan output the gate checks against the law's `nomosFlowGate.endorse`
+   * (author + replay), NEVER the committed intent's events, so it is not OID-hashed. OMITTED when
+   * empty so a principal-free intent is byte-identical.
+   */
+  endorse?: { sink: string; facet: string; reason: string | null }[];
 }
 
 /**

package/src/wire_encode.ts

@@ -26,7 +26,8 @@ import type { AggregateHandle } from "./aggregate.js";
 import type { Field, EvidenceRefValue } from "./fields.js";
 import type { Directive, ReferentialMarker } from "./directive.js";
 import type { PlannedOp, FieldOp } from "./ops.js";
-import type { Ports } from "./ctx.js";
+import { deterministicPorts, type Ports } from "./ctx.js";
+import type { PrincipalFacet } from "./principal_evidence.js";
 import type {
   WireEvent,
   WireHlc,
@@ -290,5 +291,77 @@ export function executeDirectiveToIntent<P>(
     return { aggregate, marker: eventMarker, ops };
   });
   // Attach the captured read footprint — OMITTED when empty so a read-free intent is byte-identical.
-  return { id: intentIdFromHlc(hlc), hlc, strikes, events, ...(reads.length ? { reads } : {}) };
+  // Attach the OBSERVED ENDORSE footprint (Slice B) — the principal flows this run produced; the gate
+  // checks them against the law's nomosFlowGate.endorse. Transient verify-input (not OID-hashed),
+  // OMITTED when empty so a principal-free intent is byte-identical.
+  const endorse = flowsFromOps(ops);
+  return {
+    id: intentIdFromHlc(hlc),
+    hlc,
+    strikes,
+    events,
+    ...(reads.length ? { reads } : {}),
+    ...(endorse.length ? { endorse } : {}),
+  };
+}
+
+/** One declared principal flow harvested from a plan — `sink` is `<AggregateType>.<field>`. */
+export interface PrincipalFlow {
+  readonly sink: string;
+  readonly facet: PrincipalFacet;
+  readonly reason: string | null;
+}
+
+/** Extract the principal flows carried by a plan's field ops (those with an `endorsement`). The ONE
+ *  op→flow mapping shared by the discovery harvest (compile) and the runtime footprint (Slice B). */
+function flowsFromOps(ops: readonly FieldOp[]): PrincipalFlow[] {
+  const flows: PrincipalFlow[] = [];
+  for (const op of ops) {
+    if (op.endorsement) {
+      flows.push({ sink: `${op.aggregateType ?? op.aggregateId}.${op.field}`, facet: op.endorsement.facet, reason: op.endorsement.reason });
+    }
+  }
+  return flows.sort((a, b) =>
+    a.sink !== b.sink ? (a.sink < b.sink ? -1 : 1) : a.facet < b.facet ? -1 : a.facet > b.facet ? 1 : 0,
+  );
+}
+
+/**
+ * THE DISCOVERY HARVEST (security_model.md — discovery IS law): run a directive's PURE plan with a
+ * probe payload + a probe principal, and harvest every PrincipalEvidence conversion's declared flow
+ * (`{sink, facet, reason}`). Executes the plan (not its AST) — the same technique as the rule-4 reads
+ * probe. Best-effort + fail-open on HARVEST (a probe that can't drive a branch just omits that flow);
+ * the omission is SAFE because the runtime/replay witness (Slice B) refuses any observed flow absent
+ * from the manifest. The reasons are static law, so they are intent-independent. SORTED for determinism.
+ */
+export function harvestPrincipalFlows(directive: Directive<unknown>): PrincipalFlow[] {
+  const ctx: Ports = deterministicPorts({ principal: "principal:probe" });
+  // A probe payload: any field access yields a benign string. Plans that need a typed shape (an
+  // array .map, etc.) may throw — caught below; that directive's flows are then witnessed at runtime.
+  const probe = new Proxy({}, { get: () => "probe" });
+  // A plan that MINTS (`create(Agg)` — the common `.creates` shape) calls `globalThis.nomos.mint`; the
+  // harvest runs at compile, where the engine's real shim is absent. Install a deterministic stub so the
+  // probe plan runs to completion and its flows ARE harvested (an un-harvested authority flow would be
+  // refused at runtime by the Slice B witness — fail-closed, but a false jam). The minted VALUE is
+  // irrelevant — a flow's sink is the field path, not the id. Restore any pre-existing shim after.
+  const g = globalThis as unknown as { nomos?: { mint?: (t: string) => string; read?: unknown } };
+  const hadNomos = "nomos" in g;
+  const prior: { mint?: (t: string) => string; read?: unknown } | undefined = g.nomos;
+  if (!hadNomos || typeof prior?.mint !== "function") {
+    g.nomos = { ...(prior ?? {}), mint: (typeTag: string) => `${typeTag}_0192f00d-0000-7000-8000-000000000000` };
+  }
+  let ops: FieldOp[];
+  __resetAuthoring();
+  __resetReads();
+  try {
+    const returned = directive.plan(probe as never, ctx);
+    ops = [...__drainAuthoring(), ...(Array.isArray(returned) ? returned : [])].filter((op): op is FieldOp => op.kind !== "strike");
+  } catch {
+    try { __drainAuthoring(); __drainReads(); } catch { /* sink already drained */ }
+    return [];
+  } finally {
+    if (hadNomos && prior !== undefined) g.nomos = prior; else delete g.nomos;
+  }
+  __drainReads();
+  return flowsFromOps(ops);
 }