@githolon/dsl 0.34.1 → 0.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.34.1",
+  "version": "0.35.0",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/attested.ts

@@ -0,0 +1,74 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine}.  If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * ATTESTED CROSS-WORKSPACE CAPTURED READS (slice B — `architecture/attested_reads_design.md`).
+ *
+ * The doctrine: *"trusting my parent not to lie, I enforce what I admit by checking facts from
+ * workspaces I choose to trust, via a captured and attested read."* The trust boundary is DECLARED
+ * IN LAW ({@link trustSource} → the `nomosAttestedReadGate` era key) and provable at replay: a plan
+ * reads a DECLARED query of a FOREIGN workspace (`read(theQuery, args, { from })` + the directive's
+ * `.readsFrom(from, theQuery)`), the SOURCE holon's kernel signs an envelope binding the result to
+ * its chain position (head oid + certified fold-root + signer epoch), and every verify door checks
+ * SIGNATURE + TRUST + BOUNDS + FRESHNESS — never re-deriving from the foreign chain (the exact
+ * inverse of the same-workspace CAS lane; a foreign fact is carried evidence, not re-folded state).
+ *
+ * Stage 1 is the K1 layer: the reader's law PINS the accepted attestor keyHashes by hand
+ * ({@link trustSource}). K2 (`trustParent`, birth-cert-derived pins) and K3 (tracked rosters)
+ * grow the same declaration without re-shaping it (the `roster` mode names the layer).
+ *
+ * This file holds the halves that need `directive.ts` (the sanctioning ensure + the merge-seam
+ * injector); the leaf-module core lives in `attested_core.ts` (re-exported here).
+ */
+import { directive, type Directive } from "./directive.js";
+import { z } from "zod";
+import { NomosSourceFrontier } from "./attested_core.js";
+
+export {
+  trustSource,
+  foreignQuery,
+  isTrustSourceDecl,
+  NomosSourceFrontier,
+  sourceFrontierId,
+  SOURCE_FRONTIER_PREFIX,
+  __trustFor,
+  type TrustSourceDecl,
+  type TrustSourceOptions,
+  type ForeignQueryRef,
+} from "./attested_core.js";
+
+/**
+ * THE FRONTIER SANCTIONING DECLARATION (the `nomosBirthRecordEnsure` pattern): the auto-appended
+ * `NomosSourceFrontier` event is an ENSURE at a deterministic id, so the id-mint gate admits it
+ * only through the declared-ensures lane — the law must carry an `Ensure → NomosSourceFrontier`
+ * directive. This one is DELIBERATELY USELESS TO DISPATCH (its plan writes nothing); its only
+ * load-bearing property is its manifest/USD presence.
+ */
+export const nomosSourceFrontierEnsure = directive("nomosSourceFrontierEnsure")
+  .ensures(NomosSourceFrontier)
+  .payload(z.object({}).strict())
+  .plan(() => []);
+
+/**
+ * Inject the attested-read structural exports into a merged module-exports bag IFF it declares ≥1
+ * foreign read (`.readsFrom`) — the RelationTuple/birth-meter "discoverable without re-exports"
+ * courtesy at the one merge seam. A foreign-read-free bag is returned UNTOUCHED (the era rule —
+ * byte-identical). Existing keys are never overwritten.
+ */
+export function withAttestedReadExports<M extends Record<string, unknown>>(mod: M): M {
+  const declaresForeign = Object.values(mod).some(
+    (v) =>
+      v !== null &&
+      typeof v === "object" &&
+      Array.isArray((v as { declaredForeignReads?: unknown }).declaredForeignReads) &&
+      ((v as { declaredForeignReads: unknown[] }).declaredForeignReads.length > 0) &&
+      typeof (v as Directive<unknown>).plan === "function",
+  );
+  if (!declaresForeign) return mod;
+  const out: Record<string, unknown> = { ...mod };
+  if (!("NomosSourceFrontier" in out)) out.NomosSourceFrontier = NomosSourceFrontier;
+  if (!("nomosSourceFrontierEnsure" in out)) out.nomosSourceFrontierEnsure = nomosSourceFrontierEnsure;
+  return out as M;
+}

package/src/attested_core.ts

@@ -0,0 +1,158 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine}.  If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * ATTESTED READS — the CORE (leaf-module) half: the trust declaration, the foreign query
+ * reference, and the reader-side SourceFrontier aggregate. Kept free of `directive.ts` imports
+ * so `read.ts` (which `birth_meter.ts` → `directive.ts` depend on) can import it without a
+ * module-init cycle. The sanctioning ensure directive + the merge-seam injector live in
+ * `attested.ts`. Full doctrine: `architecture/attested_reads_design.md`.
+ */
+import { aggregate } from "./aggregate.js";
+import { t } from "./fields.js";
+import { Lww } from "./drivers.js";
+
+/** A lightweight reference to a query declared in the SOURCE workspace's law — the reader
+ *  consumes only its id (the query spec is the SOURCE's law, never re-declared reader-side).
+ *  Use this (not a full `query(...)` export) so the foreign query never enters the READER's
+ *  own read surface/openapi. A full QueryDecl is also accepted wherever this is. */
+export interface ForeignQueryRef {
+  readonly id: string;
+  /** brand — keeps a foreign ref out of the reader's query auto-discovery. */
+  readonly __nomosForeignQuery: true;
+}
+
+/** Name a query of the SOURCE workspace's law by id (see {@link ForeignQueryRef}). */
+export function foreignQuery(id: string): ForeignQueryRef {
+  return { id, __nomosForeignQuery: true };
+}
+
+/** The §4.4 freshness + §1.3 key-resolution vocabulary of one declared trust edge. */
+export interface TrustSourceOptions {
+  /** The source chain's GENESIS oid — the workspace's true identity (the name is routing). */
+  readonly genesis: string;
+  /** K1: the accepted read-attestor keyHashes (`sha256hex(pubkey)`). Required while `roster`
+   *  is `"pinned"` (the stage-1 default); later layers derive/track the set. */
+  readonly keyHashes?: readonly string[];
+  /** §4.4a — wall-clock freshness bound in ms (judged against the intent's frozen HLC). */
+  readonly maxAgeMs?: number;
+  /** §4.4b — the epoch anchor: `"birth"` (the reader's own birth-cert epoch) or an integer floor. */
+  readonly minSourceEpoch?: "birth" | number;
+  /** §4.4c — maintain + enforce the monotone `SourceFrontier` (no regression below what this
+   *  reader's chain has already seen from this source). */
+  readonly monotone?: boolean;
+  /** §1.3 — how the accepted-key set is populated: `"pinned"` (K1, acts in stage 1),
+   *  `"derived"` (K2), `"tracked"` (K3). Parsed by the kernel from stage 1; later modes
+   *  only ACT in later stages. */
+  readonly roster?: "pinned" | "derived" | "tracked";
+  /** §5.3 — what a folded `SourceDishonor` fact does at verify: `"refuse"` (default) or `"record"`. */
+  readonly onDishonor?: "refuse" | "record";
+}
+
+/** One declared trust edge — an exported {@link trustSource} value, auto-discovered by shape. */
+export interface TrustSourceDecl extends TrustSourceOptions {
+  readonly workspace: string;
+  readonly __nomosTrustSource: true;
+}
+
+// ── the runtime trust registry — module-init state the foreign read lane consults ──────────────
+// `trustSource()` runs at module evaluation BOTH at compile (node) and inside the sealed lump
+// (QuickJS), so the read lane can resolve an edge's `monotone` posture without plumbing the
+// declaration through every plan. Keyed by source workspace name; later declaration wins
+// (the same later-wins the module merge applies).
+const trustRegistry = new Map<string, TrustSourceDecl>();
+
+/** The registered trust edge for a source workspace (`undefined` = undeclared). Library-internal. */
+export function __trustFor(workspace: string): TrustSourceDecl | undefined {
+  return trustRegistry.get(workspace);
+}
+
+/**
+ * DECLARE a trusted source workspace (the reader-law half of an attested read — §3.1). Export the
+ * returned decl from a domain module; `nomos-compile` discovers it by shape and lowers it into the
+ * `nomosAttestedReadGate` era key (emitted iff ≥1 directive declares a foreign read — a domain
+ * using none is byte-identical, the era rule).
+ */
+export function trustSource(workspace: string, opts: TrustSourceOptions): TrustSourceDecl {
+  const decl: TrustSourceDecl = { workspace, ...opts, __nomosTrustSource: true };
+  const roster = opts.roster ?? "pinned";
+  if (roster === "pinned" && (opts.keyHashes === undefined || opts.keyHashes.length === 0)) {
+    throw new Error(
+      `trustSource('${workspace}'): the 'pinned' roster (K1) requires ≥1 keyHash — pin the ` +
+        `source's read-attestor sha256hex(pubkey), or use roster:'derived'/'tracked' (later stages)`,
+    );
+  }
+  if (typeof opts.genesis !== "string" || opts.genesis.length === 0) {
+    throw new Error(
+      `trustSource('${workspace}'): 'genesis' (the source chain's genesis oid) is required — ` +
+        `the NAME is routing; genesis + key are identity`,
+    );
+  }
+  trustRegistry.set(workspace, decl);
+  return decl;
+}
+
+/** Shape predicate for compile discovery (the `isQueryDecl` pattern). */
+export function isTrustSourceDecl(v: unknown): v is TrustSourceDecl {
+  return (
+    v !== null &&
+    typeof v === "object" &&
+    (v as { __nomosTrustSource?: unknown }).__nomosTrustSource === true &&
+    typeof (v as { workspace?: unknown }).workspace === "string"
+  );
+}
+
+// ── the SourceFrontier (§4.4c) — the reader-side monotone record of the source's position ──────
+
+/** The deterministic instance-id prefix — `source-frontier:<source_genesis>` (keyed by the source's
+ *  TRUE identity, never its routable name). Mirrored in the kernel
+ *  (`nomos_executor::SOURCE_FRONTIER_PREFIX`). */
+export const SOURCE_FRONTIER_PREFIX = "source-frontier:";
+
+/** The frontier record's instance id for a source genesis. */
+export function sourceFrontierId(sourceGenesis: string): string {
+  return SOURCE_FRONTIER_PREFIX + sourceGenesis;
+}
+
+/**
+ * NomosSourceFrontier — the highest source position this reader's chain has SEEN per trusted
+ * source (§4.4c): the deterministic reduction of head-distance freshness. Updated IN-BAND by the
+ * foreign read lane (the slice-A birth-record pattern — the read lane emits it, the gate demands
+ * it); the gate's monotone arm refuses any attestation BEHIND it. Reader-chain state — re-folded
+ * at replay, so the predicate is deterministic forever.
+ */
+export const NomosSourceFrontier = aggregate("NomosSourceFrontier", {
+  /** The source workspace name the edge was declared under (routing/diagnostics). */
+  source: t.string().merge(Lww),
+  /** The highest source signer-epoch an admitted attestation has shown this reader. */
+  maxEpochSeen: t.int().merge(Lww),
+  /** The highest `attested_at_ms` an admitted attestation has shown this reader. */
+  maxAttestedAtSeen: t.int().merge(Lww),
+  /** The source head oid at the highest-seen position (diagnostics/audit). */
+  headAtMax: t.string().merge(Lww),
+});
+
+
+// ── the ensure() hook — breaks the read.ts → authoring.ts module-init cycle ────────────────────
+// `authoring.ts` registers its `ensure()` here at module init; the foreign read lane calls it
+// through this indirection (read.ts must not import authoring.ts: authoring → framework/relations
+// → directive → birth_meter → read would be a cycle).
+type EnsureFn = (
+  agg: unknown,
+  id: string,
+) => { set(field: string, value: unknown): unknown };
+let ensureImpl: EnsureFn | null = null;
+/** Registered by `authoring.ts` at module init. Library-internal. */
+export function __registerEnsure(fn: EnsureFn): void {
+  ensureImpl = fn;
+}
+/** The registered `ensure()` — throws NAMED if authoring never initialized (impossible in any
+ *  real bundle: `read` and `ensure` ride the same library). Library-internal. */
+export function __ensure(agg: unknown, id: string): { set(field: string, value: unknown): unknown } {
+  if (ensureImpl === null) {
+    throw new Error("attested read: the authoring surface is not initialized (no ensure())");
+  }
+  return ensureImpl(agg, id);
+}

package/src/authoring.ts

@@ -28,6 +28,7 @@ import type { Field } from "./fields.js";
 import type { FieldOp, PlannedOp, PlannedEventMarker } from "./ops.js";
 import { endorsementOf } from "./principal_evidence.js";
 import { __qualifyAggregateType } from "./framework/relations.js";
+import { __registerEnsure } from "./attested_core.js";
 
 // ── the per-dispatch authoring sink — library state the engine never sees (NOT a side channel out of
 //    the sandbox; it is internal to the directive runtime, drained synchronously by `executeDirectiveToIntent`). ──
@@ -141,3 +142,7 @@ export function existing(agg: AggregateHandle, id: string): AggregateRef {
 export function ensure(agg: AggregateHandle, id: string): AggregateRef {
   return new Ref(agg, id, "ensures");
 }
+
+// Register ensure() for the foreign read lane (attested reads — see attested_core.ts; the
+// indirection exists purely to avoid a module-init import cycle through read.ts).
+__registerEnsure((agg, id) => ensure(agg as AggregateHandle, id));

package/src/build_package.ts

@@ -60,6 +60,7 @@ import {
   synthesizeBirthQuotaInvariants,
 } from "./birth_meter.js";
 import { withBirthMeterExports } from "./birth_meter_ensure.js";
+import { withAttestedReadExports, isTrustSourceDecl, type TrustSourceDecl } from "./attested.js";
 import type { RelationTypeDecl } from "./relation_schema.js";
 import { domainHash, emitManifestBytes } from "./manifest.js";
 import { collectValueObjectDescriptors } from "./value_object.js";
@@ -157,6 +158,9 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   // Ensure→NomosBirthRecord manifest declaration is what admits the auto-appended record through
   // the id-mint gate's declared-ensures lane. Birth-free domains are byte-identical (era rule).
   merged = withBirthMeterExports(merged);
+  // ATTESTED READS (slice B): a foreign-read-declaring domain gains the SourceFrontier
+  // aggregate + its sanctioning ensure at the same seam (era-safe: others byte-identical).
+  merged = withAttestedReadExports(merged);
 
   const byId = new Map<string, AggregateHandle>();
   for (const a of [...aggregatesOf(merged), ...(spec.extraAggregates ?? [])]) byId.set(a.id, a);
@@ -251,6 +255,15 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   // byte-identical in the canonical manifest/USD to before the key existed.
   // Discover the sentinel AND its declared owner/cert locators (the kernel reads them off the era key, names
   // neither). A bare marker omits the locators ⇒ the kernel's framework default applies (the era rule).
+  // ATTESTED READS (slice B): the module-level trustSource declarations, discovered by shape
+  // across the merged exports (the workspaceInvariants duck-typing). Later-wins by workspace.
+  const trustByWs = new Map<string, TrustSourceDecl>();
+  for (const v of Object.values(merged)) {
+    if (isTrustSourceDecl(v)) trustByWs.set(v.workspace, v);
+  }
+  const trustSources = [...trustByWs.values()].sort((a, b) =>
+    a.workspace < b.workspace ? -1 : a.workspace > b.workspace ? 1 : 0,
+  );
   const pabMarker =
     parentAttestedBirthMarker(merged) ??
     spec.modules.map((m) => parentAttestedBirthMarker(m)).find((x) => x !== null) ??
@@ -295,6 +308,9 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
     // THE PEER-SOVEREIGN ROOT-OF-TRUST: omit-when-false — a law that doesn't require parent-attested
     // birth is byte-identical in the canonical manifest/USD (the nomosParentAttestedBirth era rule).
     ...(parentAttestedBirth ? { parentAttestedBirth } : {}),
+    // Omit-when-empty — the nomosAttestedReadGate era rule: a domain with no declared trust
+    // edge is byte-identical in the canonical manifest/USD.
+    ...(trustSources.length > 0 ? { trustSources } : {}),
     ...(dartImports.length > 0 ? { dartImports } : {}),
     ...(spec.dartRefImports !== undefined && spec.dartRefImports.length > 0
       ? { dartRefImports: [...spec.dartRefImports] }

package/src/codegen_dart.ts

@@ -2789,6 +2789,14 @@ export interface DomainModule {
   parentAttestedBirth?:
     | boolean
     | { ownerObject?: string; ownerField?: string; certObject?: string; certField?: string };
+  /**
+   * The domain's DECLARED TRUST EDGES (slice B — attested cross-workspace reads,
+   * `architecture/attested_reads_design.md` §3): the exported `trustSource(ws, …)` declarations,
+   * discovered by shape. Lowered — together with directives' `.readsFrom` tuples — into the
+   * `nomosAttestedReadGate` USD era key (emitted iff ≥1 directive declares a foreign read).
+   * ADDITIVE + OPTIONAL: a domain with no trust edge omits this and is byte-identical (era rule).
+   */
+  trustSources?: import("./attested.js").TrustSourceDecl[];
   /**
    * The domain's NATIVE ZANZIBAR RELATION SCHEMA (`relation_schema.ts` — the userset-rewrite law,
    * P1). Pure-data per-type relation rewrites lowered to the `nomosRelations` USD era key (NO JS on

package/src/compile_package_main.ts

@@ -1272,9 +1272,14 @@ async function main(): Promise<void> {
   // `read()`'s body (dsl/src/read.ts — keep them byte-identical) and is tree-shaken
   // out of read-free lumps.
   const CAPTURED_READ_LUMP_MARKER = "nomos.read is not provided by this host";
+  // Slice B: a FOREIGN (attested) read declaration ALSO opts the law into the read lane —
+  // `read(q, args, {from})` is served from the verified injected envelope, so a law whose
+  // only reads are foreign is just as declared as a local-read law.
   const declaresCapturedReads = domainModules.some((m) =>
     m.directives.some(
-      (d) => ((d as { declaredQueryReads?: unknown[] }).declaredQueryReads ?? []).length > 0,
+      (d) =>
+        ((d as { declaredQueryReads?: unknown[] }).declaredQueryReads ?? []).length > 0 ||
+        ((d as { declaredForeignReads?: unknown[] }).declaredForeignReads ?? []).length > 0,
     ),
   );
   if (javascript.includes(CAPTURED_READ_LUMP_MARKER) && !declaresCapturedReads) {

package/src/directive.ts

@@ -174,6 +174,16 @@ export interface Directive<P = unknown> {
    * OMITTED from the canonical manifest when empty (hash-stable for read-free directives).
    */
   readonly declaredQueryReads?: QueryDecl[];
+  /**
+   * The directive's DECLARED FOREIGN (attested cross-workspace) reads (slice B —
+   * `architecture/attested_reads_design.md` §3.1): the `(queryId, from)` trust edges its
+   * `plan` may `read(theQuery, args, { from })` on the write path. The query is the SOURCE
+   * workspace's law (only its id is consumed here); the trust in the source is a separate
+   * module-level {@link trustSource} declaration. Lowered into the `nomosAttestedReadGate`
+   * era key. OPTIONAL + ADDITIVE; OMITTED when empty (a foreign-read-free directive is
+   * byte-identical — the era rule).
+   */
+  readonly declaredForeignReads?: { queryId: string; from: string }[];
   /**
    * The directive's DECLARED emit boundary: the event types its `plan` may EMIT,
    * each with an optional `max` bound. Part of the domain identity. Defaults to `{}`
@@ -313,6 +323,14 @@ export interface RequirableDirective<P> extends Directive<P> {
    * before this existed. Returns a NEW requirable directive (non-destructive).
    */
   reads(...reads: (string | QueryDecl)[]): RequirableDirective<P>;
+  /**
+   * Declare ONE FOREIGN (attested cross-workspace) read boundary (slice B): the plan may
+   * `read(theQuery, args, { from: sourceWs })` — served at author by the SOURCE holon's kernel
+   * as a SIGNED attestation, verified at every gate against the module's `trustSource(sourceWs,
+   * …)` declaration (signature / accepted key + genesis / bounds / freshness). Callable multiple
+   * times; deduped by `(queryId, from)`. Purely additive (the era rule).
+   */
+  readsFrom(sourceWorkspace: string, query: { id: string }): RequirableDirective<P>;
   /**
    * Declare ONE entry of the directive's EMIT boundary: an `eventType` its `plan` may
    * emit, with an optional `max` count bound. Callable MULTIPLE times to accumulate
@@ -653,6 +671,19 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
       const mergedQueries = [...byId.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
       return makeRequirable({ ...base, declaredReads: merged, declaredQueryReads: mergedQueries });
     },
+    readsFrom(sourceWorkspace: string, query: { id: string }): RequirableDirective<P> {
+      // ATTESTED CROSS-WORKSPACE READ (slice B): accumulate the (queryId, from) trust edge,
+      // dedup by pair, sort (only the SET is the contract — byte-determinism for the era key).
+      const prior = base.declaredForeignReads ?? [];
+      const key = (e: { queryId: string; from: string }) => `${e.from}\u0000${e.queryId}`;
+      const byKey = new Map<string, { queryId: string; from: string }>(prior.map((e) => [key(e), e]));
+      const entry = { queryId: query.id, from: sourceWorkspace };
+      byKey.set(key(entry), entry);
+      const merged = [...byKey.values()].sort((a, b) =>
+        a.from !== b.from ? (a.from < b.from ? -1 : 1) : a.queryId < b.queryId ? -1 : a.queryId > b.queryId ? 1 : 0,
+      );
+      return makeRequirable({ ...base, declaredForeignReads: merged });
+    },
     emits(eventType: string, opts?: { max?: number }): RequirableDirective<P> {
       // Accumulate one event type onto any prior emits; a `max` bound is recorded only
       // when supplied (so `{}` vs `{max}` is a real contract difference).

package/src/engine_entry.ts

@@ -59,6 +59,7 @@ import { isRelationTypeDecl } from "./relation_schema.js";
 import { synthesizePreconditionInvariants } from "./precondition.js";
 import { synthesizeBirthQuotaInvariants } from "./birth_meter.js";
 import { withBirthMeterExports } from "./birth_meter_ensure.js";
+import { withAttestedReadExports } from "./attested.js";
 import { generateOpenApiFragment, mergeOpenApiFragments, type OpenApiDoc } from "./codegen_openapi.js";
 import type { QueryDecl } from "./query.js";
 import type { AnyCount } from "./count.js";
@@ -249,7 +250,7 @@ function mergeModules(mods: readonly DomainModuleExports[]): DomainModuleExports
   // METERED BIRTH: a `.births()`-declaring domain gains the birth-meter structural exports
   // (the sanctioning `nomosBirthRecordEnsure` + the meter aggregates) at this same seam, so
   // the registry + `describe()` see the exact surface the composed manifest carries.
-  return withBirthMeterExports(expandCapabilityExports(merged));
+  return withAttestedReadExports(withBirthMeterExports(expandCapabilityExports(merged)));
 }
 
 /**

package/src/index.ts

@@ -120,6 +120,19 @@ export { create, existing, ensure, type AggregateRef } from "./authoring.js";
 // `nomos-compile` REFUSES law that references read() (a named compile error, never a runtime halt).
 // The captured-reads wave (task #58) wires the capability in and lifts the refusal.
 export { read } from "./read.js";
+// ATTESTED CROSS-WORKSPACE READS (slice B — attested_reads_design.md): the declared trust
+// surface (`trustSource`), the foreign query reference, and the reader-side SourceFrontier.
+export {
+  trustSource,
+  foreignQuery,
+  NomosSourceFrontier,
+  sourceFrontierId,
+  SOURCE_FRONTIER_PREFIX,
+  nomosSourceFrontierEnsure,
+  type TrustSourceDecl,
+  type TrustSourceOptions,
+  type ForeignQueryRef,
+} from "./attested.js";
 // THE BIRTH EFFECT (G3 — birth is a declared kernel primitive): a `.births()` directive's plan records the
 // child's genesis recipe via `birth(recipe)` (reuse `buildGenesisChain`); it rides the committed intent as a
 // declared output, and the kernel — reading the `.births` declaration off the law manifest (the

package/src/read.ts

@@ -18,7 +18,8 @@
  * routes them here. (See `docs/aggregate_lifecycle_and_relations.md`.)
  */
 import type { QueryDecl } from "./query.js";
-import type { WireRead } from "./wire.js";
+import type { WireRead, WireReadAttestation } from "./wire.js";
+import { NomosSourceFrontier, sourceFrontierId, __trustFor, __ensure } from "./attested_core.js";
 
 // ── the per-dispatch read footprint — library state drained by `executeDirectiveToIntent` (mirrors the authoring sink) ──
 let footprint: WireRead[] = [];
@@ -58,7 +59,11 @@ function host(): NomosRead {
  * {@link CAPTURED_READ_LUMP_MARKER}, which lives ONLY in this function's body and is tree-shaken
  * away with it) — and an inert host (no `nomos.read`) still halts with the named error below.
  */
-export function read<T = unknown>(query: QueryDecl, args: Record<string, string>): T {
+export function read<T = unknown>(
+  query: QueryDecl | { id: string },
+  args: Record<string, string>,
+  opts?: { from?: string },
+): T {
   const h = host() as { read?: unknown } | undefined;
   if (typeof h?.read !== "function") {
     // The string below IS the compile gate's marker — keep it byte-identical to
@@ -69,9 +74,43 @@ export function read<T = unknown>(query: QueryDecl, args: Record<string, string>
         `to the directive and recompile (#58).`,
     );
   }
-  const result = host().read(query.id, args) as T;
-  footprint.push({ queryId: query.id, args, result });
-  return result;
+  const from = opts?.from ?? "";
+  if (from === "") {
+    const result = host().read(query.id, args) as T;
+    footprint.push({ queryId: query.id, args, result });
+    return result;
+  }
+  // ── THE FOREIGN (attested cross-workspace) LANE (slice B — attested_reads_design.md §4.1).
+  // The port answers the `{rows, attestation}` wrapper: at AUTHOR the kernel verified the
+  // injected source envelope before serving it; at VERIFY the recorded capture replays
+  // verbatim. The rows return to the plan; the envelope rides the footprint; and when the
+  // trust edge declares `monotone`, the lane records the advanced SourceFrontier IN-BAND
+  // (the slice-A birth-record pattern — the gate DEMANDS this record, so honestly-compiled
+  // law satisfies it by construction).
+  const answer = (host() as { read(q: string, a: Record<string, string>, o?: { from?: string }): unknown }).read(
+    query.id,
+    args,
+    { from },
+  ) as { rows: T; attestation: WireReadAttestation };
+  const att = answer?.attestation;
+  if (att === undefined || att === null) {
+    throw new Error(
+      `read('${query.id}', {from: '${from}'}): the read port answered no attestation — ` +
+        `a foreign read is served only as a signed envelope (declare .readsFrom + trustSource ` +
+        `and author through a holon door that injects the source attestation).`,
+    );
+  }
+  footprint.push({ queryId: query.id, args, result: answer.rows, attestation: att });
+  if (__trustFor(from)?.monotone === true) {
+    const frontier = __ensure(NomosSourceFrontier, sourceFrontierId(att.source_genesis)) as {
+      set(f: string, v: unknown): unknown;
+    };
+    frontier.set("source", from);
+    frontier.set("maxEpochSeen", att.source_epoch);
+    frontier.set("maxAttestedAtSeen", att.attested_at_ms);
+    frontier.set("headAtMax", att.source_head);
+  }
+  return answer.rows;
 }
 
 /**

package/src/read_projection_manifest.ts

@@ -55,7 +55,20 @@ export function qualifyManifestAggregateLabels(
   return {
     ...manifest,
     aggregates: manifest.aggregates.map((a) => (namespaced.has(a.id) ? { ...a, id: qa(a.id) } : a)),
-    directives: manifest.directives.map((d) => (namespaced.has(d.target) ? { ...d, target: qa(d.target) } : d)),
+    // NB: `capturedReads[].returns` (the #58 read-gate spec the kernel derives against) MUST be
+    // qualified too — the projection stamps the QUALIFIED `__type` on every row, so a bare
+    // `returns` derives 0 rows at the one gate (the bug that broke captured_reads.test.mjs).
+    directives: manifest.directives.map((d) => ({
+      ...d,
+      ...(namespaced.has(d.target) ? { target: qa(d.target) } : {}),
+      ...(d.capturedReads !== undefined
+        ? {
+            capturedReads: d.capturedReads.map((r) =>
+              namespaced.has(r.returns) ? { ...r, returns: qa(r.returns) } : r,
+            ),
+          }
+        : {}),
+    })),
     ...(stableIds !== undefined ? { stableIds } : {}),
     ...(manifest.queries !== undefined
       ? { queries: manifest.queries.map((q) => (namespaced.has(q.returns) ? { ...q, returns: qa(q.returns) } : q)) }

package/src/shape_compat.ts

@@ -54,6 +54,10 @@ 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 }[]>;
 }
 
 /** The verdict: compatible iff nothing is missing and nothing is type-incompatible.
@@ -147,12 +151,23 @@ export function domainInterface(mod: DomainModule, stableIds?: StableIds): Domai
     aggEntries.push([aggSid, { sid: aggSid, label, fields: sortedRec(fieldEntries) }]);
   }
   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 }[] }>) {
+    if (!d || typeof d.id !== "string") continue;
+    if (d.declaredForeignReads !== undefined && d.declaredForeignReads.length > 0) {
+      foreignReadEntries.push([d.id, d.declaredForeignReads.map((e) => ({ ...e }))]);
+    }
+  }
+  const foreignReads = sortedRec(foreignReadEntries);
   return {
     v: 1,
     domain: (mod as { domain?: string; name?: string }).domain ?? (mod as { name?: string }).name ?? "",
     ...(stableIds?.domain !== undefined ? { domainSid: stableIds.domain } : {}),
     directives,
     aggregates,
+    ...(foreignReadEntries.length > 0 ? { foreignReads } : {}),
   };
 }
 

package/src/usd.ts

@@ -433,6 +433,34 @@ export interface UsdLayer {
     /** directive id → the SORTED query ids its plan may read. */
     readonly directives: Record<string, string[]>;
   };
+  /**
+   * THE ATTESTED-READ GATE DECLARATION (slice B — attested cross-workspace reads,
+   * `architecture/attested_reads_design.md` §3.2). Present IFF ≥1 directive declares a
+   * foreign read (`.readsFrom(ws, query)` + a module-level `trustSource(ws, …)`): the
+   * reader's law names, per trusted source, the source's IDENTITY (genesis), the accepted
+   * attestor keyHashes (K1 pins), and its freshness/dishonor vocabulary; and per directive,
+   * the `(queryId, from)` edges its plan may consume. The QUERY SPEC is NOT emitted here —
+   * the query is the SOURCE's law; the reader declares only the trust edge + the id.
+   * OMITTED for foreign-read-free law (byte-identical hash — the exact `nomosReadGate` era
+   * discipline). The `roster` mode names the §1.3 layer (`pinned`=K1, `derived`=K2,
+   * `tracked`=K3) — one era key from stage 1; later stages ADD modes, never re-shape.
+   */
+  readonly nomosAttestedReadGate?: {
+    readonly v: 1;
+    readonly sources: Record<
+      string,
+      {
+        genesis: string;
+        keyHashes?: string[];
+        maxAgeMs?: number;
+        minSourceEpoch?: "birth" | number;
+        monotone?: boolean;
+        roster: "pinned" | "derived" | "tracked";
+        onDishonor: "refuse" | "record";
+      }
+    >;
+    readonly directives: Record<string, { queryId: string; from: string }[]>;
+  };
   /**
    * THE READ-VISIBILITY GATE DECLARATION (the native-relations read gate).
    * Present IFF ≥1 aggregate of this layer is declared PRIVATE (`visibility:
@@ -952,6 +980,52 @@ export function emitUsd(
       }
       const nomosAttestationGate =
         Object.keys(attestationReq).length > 0 ? { v: 1 as const, directives: attestationReq } : undefined;
+      // THE ATTESTED-READ GATE (slice B): per-directive `(queryId, from)` edges + the module's
+      // 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 }[]> = {};
+      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;
+        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 sourcesRec: NonNullable<UsdLayer["nomosAttestedReadGate"]>["sources"] = {};
+        for (const [dirId, edges] of Object.entries(foreignDirectives)) {
+          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",
+              };
+            }
+          }
+        }
+        // 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 };
+      }
       // 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
       // admitted directive births, then folds the recipe the intent carried. Omit-when-empty (era rule —
@@ -1160,6 +1234,7 @@ export function emitUsd(
         ...(nomosReadProjectionNamespace !== undefined ? { nomosReadProjectionNamespace } : {}),
         ...(nomosRelationGate !== undefined ? { nomosRelationGate } : {}),
         ...(nomosAttestationGate !== undefined ? { nomosAttestationGate } : {}),
+        ...(nomosAttestedReadGate !== undefined ? { nomosAttestedReadGate } : {}),
         ...(nomosBirthGate !== undefined ? { nomosBirthGate } : {}),
         ...(nomosBirthRecordGate !== undefined ? { nomosBirthRecordGate } : {}),
         ...(nomosParentAttestedBirth !== undefined ? { nomosParentAttestedBirth } : {}),

package/src/usd_layers.ts

@@ -185,6 +185,9 @@ function domainLayerAttrLines(domain: string, layer: UsdLayer, indent: string):
     ...(layer.nomosAttestationGate !== undefined
       ? [`${indent}custom string nomos:attestationGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosAttestationGate)))}`]
       : []),
+    ...(layer.nomosAttestedReadGate !== undefined
+      ? [`${indent}custom string nomos:attestedReadGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosAttestedReadGate)))}`]
+      : []),
     ...(layer.nomosBirthGate !== undefined
       ? [`${indent}custom string nomos:birthGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosBirthGate)))}`]
       : []),
@@ -828,6 +831,26 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
         attestationGate = { v: 1, directives: rec };
       }
     }
+    // THE ATTESTED-READ GATE (slice B): sources + per-directive edges merged later-wins across
+    // layers, SORTED keys (matching the composed emission). Omit-when-empty (era rule).
+    let attestedReadGate: UsdLayer["nomosAttestedReadGate"];
+    {
+      type SrcSpec = NonNullable<UsdLayer["nomosAttestedReadGate"]>["sources"][string];
+      const srcs = new Map<string, SrcSpec>();
+      const dirs = new Map<string, { queryId: string; from: string }[]>();
+      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, 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 }[]> = {};
+        for (const k of [...dirs.keys()].sort()) directivesRec[k] = dirs.get(k)!;
+        attestedReadGate = { v: 1, sources: sourcesRec, directives: directivesRec };
+      }
+    }
     // THE BIRTH GATE (G3): the SORTED union of every layer's `.births()` directive ids. Omit-when-empty
     // (era rule). The set is the contract; order is incidental (sorted for byte-determinism).
     let birthGate: UsdLayer["nomosBirthGate"];
@@ -916,6 +939,7 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
       ...(readProjectionNamespace !== undefined ? { nomosReadProjectionNamespace: readProjectionNamespace } : {}),
       ...(relationGate !== undefined ? { nomosRelationGate: relationGate } : {}),
       ...(attestationGate !== undefined ? { nomosAttestationGate: attestationGate } : {}),
+      ...(attestedReadGate !== undefined ? { nomosAttestedReadGate: attestedReadGate } : {}),
       ...(birthGate !== undefined ? { nomosBirthGate: birthGate } : {}),
       ...(birthRecordGate !== undefined ? { nomosBirthRecordGate: birthRecordGate } : {}),
       ...(parentAttestedBirth !== undefined ? { nomosParentAttestedBirth: parentAttestedBirth } : {}),
@@ -1053,6 +1077,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
   const relationNamespaceByDomain = new Map<string, UsdLayer["nomosRelationNamespace"]>();
   const readProjectionNamespaceByDomain = new Map<string, UsdLayer["nomosReadProjectionNamespace"]>();
   const attestationGateByDomain = new Map<string, UsdLayer["nomosAttestationGate"]>();
+  const attestedReadGateByDomain = new Map<string, UsdLayer["nomosAttestedReadGate"]>();
   const birthGateByDomain = new Map<string, UsdLayer["nomosBirthGate"]>();
   const birthRecordGateByDomain = new Map<string, UsdLayer["nomosBirthRecordGate"]>();
   const parentAttestedBirthByDomain = new Map<string, UsdLayer["nomosParentAttestedBirth"]>();
@@ -1119,6 +1144,11 @@ export function parseUsdaDocument(text: string): UsdDocument {
       if (typeof attGateHex === "string") {
         attestationGateByDomain.set(domain, JSON.parse(unhexUtf8(attGateHex)) as UsdLayer["nomosAttestationGate"]);
       }
+      // THE ATTESTED-READ GATE (slice B): the hex-carried trust-edge declaration.
+      const attReadGateHex = p.attrs.get("nomos:attestedReadGateHex");
+      if (typeof attReadGateHex === "string") {
+        attestedReadGateByDomain.set(domain, JSON.parse(unhexUtf8(attReadGateHex)) as UsdLayer["nomosAttestedReadGate"]);
+      }
       // THE BIRTH GATE (G3): the hex-carried `.births()` directive set.
       const birthGateHex = p.attrs.get("nomos:birthGateHex");
       if (typeof birthGateHex === "string") {
@@ -1243,6 +1273,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
       const relNs = relationNamespaceByDomain.get(domain);
       const rpNs = readProjectionNamespaceByDomain.get(domain);
       const attGate = attestationGateByDomain.get(domain);
+      const attReadGate = attestedReadGateByDomain.get(domain);
       const birthGate = birthGateByDomain.get(domain);
       const birthRecordGate = birthRecordGateByDomain.get(domain);
       const parentAttestedBirth = parentAttestedBirthByDomain.get(domain);
@@ -1266,6 +1297,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
         ...(rpNs !== undefined ? { nomosReadProjectionNamespace: rpNs } : {}),
         ...(relGate !== undefined ? { nomosRelationGate: relGate } : {}),
         ...(attGate !== undefined ? { nomosAttestationGate: attGate } : {}),
+        ...(attReadGate !== undefined ? { nomosAttestedReadGate: attReadGate } : {}),
         ...(birthGate !== undefined ? { nomosBirthGate: birthGate } : {}),
         ...(birthRecordGate !== undefined ? { nomosBirthRecordGate: birthRecordGate } : {}),
         ...(parentAttestedBirth !== undefined ? { nomosParentAttestedBirth: parentAttestedBirth } : {}),

package/src/wire.ts

@@ -162,6 +162,42 @@ export interface WireRead {
   args: Record<string, string>;
   /** The captured result. Replay returns this verbatim; the gate may re-verify it against `hlc`. */
   result: unknown;
+  /**
+   * THE READ ATTESTATION (slice B — attested cross-workspace reads): present IFF this read was
+   * served by a FOREIGN workspace (`read(q, args, {from})`). The TS twin of the kernel's
+   * `ports::ReadAttestation` (snake_case — the kernel serde wire). OMITTED for a local read so
+   * a local-read intent stays byte-identical (the era rule).
+   */
+  attestation?: WireReadAttestation;
+}
+
+/**
+ * The kernel `ports::ReadAttestation` wire twin (attested_reads_design.md §2.1) — FIXED at its
+ * terminal shape: the signed core fields + three optional evidence slots later stages populate
+ * (`delegation` K2, `roster_proof` K3, `receipt_hint` receipts). Field names are the kernel's
+ * serde snake_case (this object rides INSIDE `captured_ports.reads[i]`).
+ */
+export interface WireReadAttestation {
+  v: number;
+  source_workspace: string;
+  source_genesis: string;
+  source_head: string;
+  fold_root: string;
+  source_epoch: number;
+  attested_at_ms: number;
+  /** base64(32B ed25519 public key) — keyHash = sha256hex(raw). */
+  public_key: string;
+  /** base64(64B ed25519) over the `nomos-attested-read-v1\0` signed bytes. */
+  signature: string;
+  delegation?: {
+    signer_key_hash: string;
+    attestor_key_hash: string;
+    epoch: number;
+    delegated_at_ms: number;
+    signature: string;
+  };
+  roster_proof?: { commit_b64: string; leaf_b64: string; path: string[] };
+  receipt_hint?: { batch_id: string };
 }
 
 /**