@githolon/dsl 0.55.1 → 0.57.0

package/src/shape_compat.ts

@@ -54,10 +54,13 @@ export interface DomainInterface {
   readonly directives: Record<string, DirectivePayloadShape>;
   /** keyed by AGGREGATE SID. */
   readonly aggregates: Record<string, AggregateReadShape>;
-  /** ATTESTED READS (slice B): directive id → its declared `(queryId, from)` trust edges —
-   *  the cross-workspace dependencies this law consumes on its write path. OMITTED when the
-   *  law declares none (the era rule). */
-  readonly foreignReads?: Record<string, { queryId: string; from: string }[]>;
+  /** ATTESTED READS (slice B + dynamic policies): directive id → its declared foreign-read edges —
+   *  a STATIC `{queryId, from}` edge or a dynamic `{queryId, policy, fromPayload}` edge — the
+   *  cross-workspace dependencies this law consumes on its write path. OMITTED when none (era rule). */
+  readonly foreignReads?: Record<
+    string,
+    { queryId: string; from?: string; policy?: string; fromPayload?: string }[]
+  >;
 }
 
 /** The verdict: compatible iff nothing is missing and nothing is type-incompatible.
@@ -161,8 +164,9 @@ export function domainInterface(mod: DomainModule, stableIds?: StableIds): Domai
   Object.assign(aggregates, sortedRec(aggEntries));
   // ATTESTED READS (slice B): the declared trust edges — so shape-compat + client codegen can
   // SEE the cross-workspace dependency (typed clients don't call it; it's write-path-internal).
-  const foreignReadEntries: Array<[string, { queryId: string; from: string }[]]> = [];
-  for (const d of (mod.directives ?? []) as Array<{ id?: unknown; declaredForeignReads?: { queryId: string; from: string }[] }>) {
+  type ForeignEdge = { queryId: string; from?: string; policy?: string; fromPayload?: string };
+  const foreignReadEntries: Array<[string, ForeignEdge[]]> = [];
+  for (const d of (mod.directives ?? []) as Array<{ id?: unknown; declaredForeignReads?: ForeignEdge[] }>) {
     if (!d || typeof d.id !== "string") continue;
     if (d.declaredForeignReads !== undefined && d.declaredForeignReads.length > 0) {
       foreignReadEntries.push([d.id, d.declaredForeignReads.map((e) => ({ ...e }))]);

package/src/usd.ts

@@ -44,6 +44,7 @@ import type { DomainModule } from "./codegen_dart.js";
 import { domainInterface } from "./shape_compat.js";
 import { relationType, user, key, anyUser, qualifiedTypeId, qualifyRelationType } from "./relation_schema.js";
 import { harvestPrincipalFlows } from "./wire_encode.js";
+import { zodKind, zodObjectShape } from "./codegen_ts.js";
 import { composeSharedRelationTypes } from "./relation_composition.js";
 import { collectValueObjectUsages } from "./value_object.js";
 import {
@@ -459,7 +460,29 @@ export interface UsdLayer {
         onDishonor: "refuse" | "record";
       }
     >;
-    readonly directives: Record<string, { queryId: string; from: string }[]>;
+    /**
+     * DYNAMIC-SOURCE trust POLICIES (dynamic_source_attested_reads.md): the acceptable-source SET is
+     * law-state — a reader-side allow-list aggregate. A directive edge may route through a policy
+     * (`{queryId, policy}`) instead of a fixed workspace; the gate resolves the envelope's genesis
+     * against the folded `allowList` rows (genesis field) → the row's `keysField` accepted keys.
+     * OMITTED when no policy is declared (byte-identical to a policy-free bundle — the era rule).
+     */
+    readonly policies?: Record<
+      string,
+      {
+        allowList: string;
+        genesisField: string;
+        keysField: string;
+        maxAgeMs?: number;
+        minSourceEpoch?: "birth" | number;
+        monotone?: boolean;
+        onDishonor?: "refuse" | "record";
+      }
+    >;
+    readonly directives: Record<
+      string,
+      ({ queryId: string; from: string } | { queryId: string; policy: string })[]
+    >;
   };
   /**
    * THE READ-VISIBILITY GATE DECLARATION (the native-relations read gate).
@@ -566,6 +589,27 @@ export interface UsdDocument {
   readonly layers: UsdLayer[];
 }
 
+/** The payload field kinds of a directive — `"string-required"` for a required `z.string()`, else the
+ *  zod kind (`"optional"`, `"number"`, …). Used to validate a `fromPayload` routing field. Empty when
+ *  the payload isn't a plain object (a shape the check can't reason about — the runtime gate arbitrates). */
+function payloadFieldKinds(dir: { payloadSchema?: unknown } | undefined): Map<string, string> {
+  const m = new Map<string, string>();
+  const schema = dir?.payloadSchema as Parameters<typeof zodKind>[0] | undefined;
+  if (schema === undefined) return m;
+  let shape: Record<string, Parameters<typeof zodKind>[0]>;
+  try {
+    if (zodKind(schema) !== "object") return m;
+    shape = zodObjectShape(schema);
+  } catch {
+    return m;
+  }
+  for (const [name, f] of Object.entries(shape)) {
+    const k = zodKind(f);
+    m.set(name, k === "string" ? "string-required" : k);
+  }
+  return m;
+}
+
 /** Sort prims by their `path` (canonical structure). */
 function sortPrims(prims: UsdPrim[]): UsdPrim[] {
   return [...prims].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
@@ -984,47 +1028,122 @@ export function emitUsd(
       // trustSource declarations. Emitted iff ≥1 directive declares a foreign read (the era
       // rule). A declared `from` with NO matching trustSource is a NAMED COMPILE ERROR — the
       // kernel would fail it closed anyway; refuse loudly at build instead.
-      const foreignDirectives: Record<string, { queryId: string; from: string }[]> = {};
+      type ForeignEdgeInternal =
+        | { queryId: string; from: string }
+        | { queryId: string; policy: string; fromPayload: string };
+      type ForeignEdgeEmit = { queryId: string; from: string } | { queryId: string; policy: string };
+      const foreignDirectives: Record<string, ForeignEdgeInternal[]> = {};
       for (const d of [...l.module.directives].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))) {
-        const fr = (d as { declaredForeignReads?: { queryId: string; from: string }[] }).declaredForeignReads;
+        const fr = (d as { declaredForeignReads?: ForeignEdgeInternal[] }).declaredForeignReads;
         if (fr !== undefined && fr.length > 0) foreignDirectives[d.id] = fr.map((e) => ({ ...e }));
       }
       let nomosAttestedReadGate: UsdLayer["nomosAttestedReadGate"];
       if (Object.keys(foreignDirectives).length > 0) {
         const trust = (l.module as { trustSources?: readonly import("./attested.js").TrustSourceDecl[] }).trustSources ?? [];
         const trustByWs = new Map(trust.map((tsrc) => [tsrc.workspace, tsrc]));
+        const policies = (l.module as { trustPolicies?: readonly import("./attested.js").TrustPolicyDecl[] }).trustPolicies ?? [];
+        const policyById = new Map(policies.map((p) => [p.policyId, p]));
+        const aggIds = new Set(l.module.aggregates.map((a) => a.id));
+        // A policy-referenced allow-list must be a real aggregate of THIS module (the fold happens in
+        // the reader's own state) — else the gate could never resolve it (fail-closed at build).
+        for (const p of policies) {
+          if (!aggIds.has(p.allowListType)) {
+            throw new Error(
+              `trustPolicy('${p.policyId}'): its allowList aggregate '${p.allowListType}' is not an ` +
+                `aggregate of this domain — the acceptable-source set is the reader's OWN folded state, ` +
+                `so the allow-list must be declared (and written by a gated enrolment directive) here.`,
+            );
+          }
+        }
         const sourcesRec: NonNullable<UsdLayer["nomosAttestedReadGate"]>["sources"] = {};
+        const policiesRec: NonNullable<NonNullable<UsdLayer["nomosAttestedReadGate"]>["policies"]> = {};
+        const emitDirectives: Record<string, ForeignEdgeEmit[]> = {};
         for (const [dirId, edges] of Object.entries(foreignDirectives)) {
+          const dir = l.module.directives.find((d) => d.id === dirId);
+          const payloadShape = payloadFieldKinds(dir);
+          const emitted: ForeignEdgeEmit[] = [];
           for (const e of edges) {
-            const tsrc = trustByWs.get(e.from);
-            if (tsrc === undefined) {
-              throw new Error(
-                `directive '${dirId}' declares .readsFrom('${e.from}', '${e.queryId}') but the ` +
-                  `module exports no trustSource('${e.from}', …) — the trust edge must be declared ` +
-                  `in law (attested_reads_design.md §3.1)`,
-              );
-            }
-            if (sourcesRec[e.from] === undefined) {
-              sourcesRec[e.from] = {
-                genesis: tsrc.genesis,
-                ...(tsrc.keyHashes !== undefined && tsrc.keyHashes.length > 0
-                  ? { keyHashes: [...tsrc.keyHashes].sort() }
-                  : {}),
-                ...(tsrc.maxAgeMs !== undefined ? { maxAgeMs: tsrc.maxAgeMs } : {}),
-                ...(tsrc.minSourceEpoch !== undefined ? { minSourceEpoch: tsrc.minSourceEpoch } : {}),
-                ...(tsrc.monotone === true ? { monotone: true } : {}),
-                roster: tsrc.roster ?? "pinned",
-                onDishonor: tsrc.onDishonor ?? "refuse",
-              };
+            if ("from" in e) {
+              const tsrc = trustByWs.get(e.from);
+              if (tsrc === undefined) {
+                throw new Error(
+                  `directive '${dirId}' declares .readsFrom('${e.from}', '${e.queryId}') but the ` +
+                    `module exports no trustSource('${e.from}', …) — the trust edge must be declared ` +
+                    `in law (attested_reads_design.md §3.1)`,
+                );
+              }
+              if (sourcesRec[e.from] === undefined) {
+                sourcesRec[e.from] = {
+                  genesis: tsrc.genesis,
+                  ...(tsrc.keyHashes !== undefined && tsrc.keyHashes.length > 0
+                    ? { keyHashes: [...tsrc.keyHashes].sort() }
+                    : {}),
+                  ...(tsrc.maxAgeMs !== undefined ? { maxAgeMs: tsrc.maxAgeMs } : {}),
+                  ...(tsrc.minSourceEpoch !== undefined ? { minSourceEpoch: tsrc.minSourceEpoch } : {}),
+                  ...(tsrc.monotone === true ? { monotone: true } : {}),
+                  roster: tsrc.roster ?? "pinned",
+                  onDishonor: tsrc.onDishonor ?? "refuse",
+                };
+              }
+              emitted.push({ queryId: e.queryId, from: e.from });
+            } else {
+              const pol = policyById.get(e.policy);
+              if (pol === undefined) {
+                throw new Error(
+                  `directive '${dirId}' declares .readsFrom(fromPayload('${e.fromPayload}'), '${e.queryId}', ` +
+                    `{ policy: '${e.policy}' }) but the module exports no trustPolicy('${e.policy}', …) — the ` +
+                    `policy must be declared in law (dynamic_source_attested_reads.md).`,
+                );
+              }
+              // The routing field must be a REQUIRED string in the directive's payload (the workspace
+              // name is chosen at runtime; a missing/optional/non-string field could never route).
+              const kind = payloadShape.get(e.fromPayload);
+              if (kind === undefined) {
+                throw new Error(
+                  `directive '${dirId}': .readsFrom(fromPayload('${e.fromPayload}'), …) names a payload ` +
+                    `field that is not declared in the directive's payload — add a required z.string() ` +
+                    `'${e.fromPayload}' to the payload (it carries the routed source workspace name).`,
+                );
+              }
+              if (kind !== "string-required") {
+                throw new Error(
+                  `directive '${dirId}': the fromPayload routing field '${e.fromPayload}' must be a ` +
+                    `REQUIRED z.string() in the payload (it names the routed source workspace) — got '${kind}'.`,
+                );
+              }
+              if (policiesRec[e.policy] === undefined) {
+                policiesRec[e.policy] = {
+                  // Qualify the allow-list type by the owning domain iff it is namespaced — the
+                  // gate scans rows by their stored `__type`, which the engine stamps qualified
+                  // (`qaType`, the SAME read-projection namespacing rows/schema keys use). A bare
+                  // (unqualified) allowList would match no folded row → every dynamic read refuses.
+                  allowList: qaType(pol.allowListType),
+                  genesisField: pol.genesisField,
+                  keysField: pol.keysField,
+                  ...(pol.maxAgeMs !== undefined ? { maxAgeMs: pol.maxAgeMs } : {}),
+                  ...(pol.minSourceEpoch !== undefined ? { minSourceEpoch: pol.minSourceEpoch } : {}),
+                  ...(pol.monotone === true ? { monotone: true } : {}),
+                  ...(pol.onDishonor !== undefined ? { onDishonor: pol.onDishonor } : {}),
+                };
+              }
+              emitted.push({ queryId: e.queryId, policy: e.policy });
             }
           }
+          emitDirectives[dirId] = emitted;
         }
         // SORTED-KEY records (byte-determinism — matching the layered flatten).
         const sortedSources: typeof sourcesRec = {};
         for (const k of Object.keys(sourcesRec).sort()) sortedSources[k] = sourcesRec[k]!;
-        const sortedDirectives: Record<string, { queryId: string; from: string }[]> = {};
-        for (const k of Object.keys(foreignDirectives).sort()) sortedDirectives[k] = foreignDirectives[k]!;
-        nomosAttestedReadGate = { v: 1 as const, sources: sortedSources, directives: sortedDirectives };
+        const sortedPolicies: typeof policiesRec = {};
+        for (const k of Object.keys(policiesRec).sort()) sortedPolicies[k] = policiesRec[k]!;
+        const sortedDirectives: Record<string, ForeignEdgeEmit[]> = {};
+        for (const k of Object.keys(emitDirectives).sort()) sortedDirectives[k] = emitDirectives[k]!;
+        nomosAttestedReadGate = {
+          v: 1 as const,
+          sources: sortedSources,
+          ...(Object.keys(sortedPolicies).length > 0 ? { policies: sortedPolicies } : {}),
+          directives: sortedDirectives,
+        };
       }
       // THE BIRTH GATE (G3 — birth is a declared kernel primitive): the SORTED set of directive ids
       // declaring `.births()`. The kernel reads this off the manifest (never a domain aggregate) to know an

package/src/usd_layers.ts

@@ -835,20 +835,32 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
     // layers, SORTED keys (matching the composed emission). Omit-when-empty (era rule).
     let attestedReadGate: UsdLayer["nomosAttestedReadGate"];
     {
-      type SrcSpec = NonNullable<UsdLayer["nomosAttestedReadGate"]>["sources"][string];
+      type Gate = NonNullable<UsdLayer["nomosAttestedReadGate"]>;
+      type SrcSpec = Gate["sources"][string];
+      type PolSpec = NonNullable<Gate["policies"]>[string];
+      type EdgeList = Gate["directives"][string];
       const srcs = new Map<string, SrcSpec>();
-      const dirs = new Map<string, { queryId: string; from: string }[]>();
+      const pols = new Map<string, PolSpec>();
+      const dirs = new Map<string, EdgeList>();
       for (const l of stack) {
         if (l.nomosAttestedReadGate === undefined) continue;
         for (const [ws, spec] of Object.entries(l.nomosAttestedReadGate.sources)) srcs.set(ws, spec);
+        for (const [id, spec] of Object.entries(l.nomosAttestedReadGate.policies ?? {})) pols.set(id, spec);
         for (const [id, edges] of Object.entries(l.nomosAttestedReadGate.directives)) dirs.set(id, edges);
       }
       if (dirs.size > 0) {
         const sourcesRec: Record<string, SrcSpec> = {};
         for (const k of [...srcs.keys()].sort()) sourcesRec[k] = srcs.get(k)!;
-        const directivesRec: Record<string, { queryId: string; from: string }[]> = {};
+        const policiesRec: Record<string, PolSpec> = {};
+        for (const k of [...pols.keys()].sort()) policiesRec[k] = pols.get(k)!;
+        const directivesRec: Record<string, EdgeList> = {};
         for (const k of [...dirs.keys()].sort()) directivesRec[k] = dirs.get(k)!;
-        attestedReadGate = { v: 1, sources: sourcesRec, directives: directivesRec };
+        attestedReadGate = {
+          v: 1,
+          sources: sourcesRec,
+          ...(Object.keys(policiesRec).length > 0 ? { policies: policiesRec } : {}),
+          directives: directivesRec,
+        };
       }
     }
     // THE BIRTH GATE (G3): the SORTED union of every layer's `.births()` directive ids. Omit-when-empty