@githolon/dsl 0.15.0 → 0.16.0

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);
 }