@githolon/dsl 0.1.0

package/src/query/relations.ts

@@ -0,0 +1,144 @@
+// 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} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * The **relation registry** + **traversal certifier** for the entity-graph query
+ * vertical.
+ *
+ * ## A relation is already a `t.ref` field — no new field kind
+ * The ground truth (verified in `fields.ts:95`): a relation between two aggregates
+ * is ALREADY modelled as a ref field —
+ * `parentId: t.ref(Parent)` produces `Field{ kind:'ref', refAggregateId: 'ParentAggregate' }`.
+ * So the relation graph is NOT a new authoring construct; it is DERIVED by reading
+ * the `kind==='ref'` fields off the registered `AggregateHandle`s.
+ *
+ * `buildRelationRegistry(handles)` builds `Map<aggId, Map<field, targetAggId>>` — for
+ * each handle, every ref field becomes an edge `(aggId, field) → refAggregateId`.
+ *
+ * ## The traversal certifier (schema-evolution safety)
+ * `certifyTraversal` walks an authored hop list against the registry and FAILS at
+ * cert time (not run time) on:
+ *   * a hop whose field does not exist on the current aggregate (a RENAMED ref →
+ *     the edge is gone → fail; this is the schema-evolution guard),
+ *   * a hop whose field is not a ref (you can only traverse along relations),
+ *   * a hop whose target is not a REGISTERED aggregate,
+ *   * a CROSS-WORKSPACE ref (`refWorkspace` set) — those are PR-tier edges the
+ *     kernel routes, NOT same-DB joinable; reject them here,
+ *   * exceeding the bounded traversal DEPTH (`MAX_DEPTH`),
+ *   * revisiting an aggregate already on the path (CYCLE guard — e.g.
+ *     `Child.parentId ↔ Parent.primaryChildId`).
+ *
+ * The certifier returns the resolved chain of `(fromAgg, field, toAgg)` hops so the
+ * compiler can lower each to a JOIN without re-deriving anything.
+ */
+import type { AggregateHandle } from "../aggregate.js";
+import type { Field } from "../fields.js";
+
+/** A registered ref edge: traversing `field` from `from` lands on `to`. */
+export interface RefEdge {
+  readonly from: string;
+  readonly field: string;
+  readonly to: string;
+}
+
+/** `Map<aggId, Map<field, targetAggId>>` — the derived same-workspace relation graph. */
+export type RelationRegistry = Map<string, Map<string, string>>;
+
+/** The set of every registered aggregate id (target-existence check). */
+export interface CertifyContext {
+  readonly registry: RelationRegistry;
+  readonly known: ReadonlySet<string>;
+}
+
+/** Bounded traversal depth — the runtime backstop has a step budget; THIS is the
+ * cert-time bound so an unbounded/cyclic traversal never even compiles. */
+export const MAX_DEPTH = 8;
+
+/**
+ * Derive the relation registry from the registered aggregate handles. Reads ONLY
+ * the `kind==='ref'` fields (with a same-workspace `refAggregateId`); cross-ws refs
+ * (`refWorkspace` set) are intentionally EXCLUDED from the joinable graph.
+ */
+export function buildRelationRegistry(
+  handles: readonly AggregateHandle[],
+): CertifyContext {
+  const registry: RelationRegistry = new Map();
+  const known = new Set<string>();
+  for (const h of handles) known.add(h.id);
+  for (const h of handles) {
+    const edges = new Map<string, string>();
+    for (const [field, f] of Object.entries(h.fields as Record<string, Field>)) {
+      if (f.kind !== "ref") continue;
+      // Cross-workspace refs are NOT same-DB joinable — leave them out so a
+      // traversal over one fails the "field is not a (joinable) ref" check.
+      if (f.refWorkspace !== undefined) continue;
+      if (f.refAggregateId === undefined) continue;
+      edges.set(field, f.refAggregateId);
+    }
+    registry.set(h.id, edges);
+  }
+  return { registry, known };
+}
+
+/** A traversal-certification failure carrying a human diagnostic. */
+export class TraversalCertError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TraversalCertError";
+  }
+}
+
+/**
+ * Certify an authored hop list (`['siteId', ...]`) starting at `root`. Returns the
+ * resolved `RefEdge[]`. THROWS `TraversalCertError` on any of the guard violations.
+ */
+export function certifyTraversal(
+  ctx: CertifyContext,
+  root: string,
+  hops: readonly string[],
+): RefEdge[] {
+  if (!ctx.known.has(root)) {
+    throw new TraversalCertError(`root aggregate '${root}' is not registered`);
+  }
+  if (hops.length > MAX_DEPTH) {
+    throw new TraversalCertError(
+      `traversal depth ${hops.length} exceeds MAX_DEPTH ${MAX_DEPTH}`,
+    );
+  }
+  const visited = new Set<string>([root]);
+  const out: RefEdge[] = [];
+  let current = root;
+  for (const field of hops) {
+    const edges = ctx.registry.get(current);
+    // current is always a known aggregate (root checked; each `to` checked below).
+    const target = edges?.get(field);
+    if (target === undefined) {
+      // Either the field does not exist, or it exists but is not a (same-ws) ref —
+      // both collapse to "not a traversable relation here". This is the
+      // schema-evolution guard: a renamed/retyped ref makes the edge vanish → FAIL.
+      throw new TraversalCertError(
+        `'${current}' has no traversable ref field '${field}' ` +
+          `(renamed/retyped/cross-workspace refs fail here)`,
+      );
+    }
+    if (!ctx.known.has(target)) {
+      throw new TraversalCertError(
+        `ref '${current}.${field}' targets unregistered aggregate '${target}'`,
+      );
+    }
+    if (visited.has(target)) {
+      throw new TraversalCertError(
+        `traversal cycle: '${target}' already visited on the path ` +
+          `(e.g. Child.parentId ↔ Parent.primaryChildId)`,
+      );
+    }
+    visited.add(target);
+    out.push({ from: current, field, to: target });
+    current = target;
+  }
+  return out;
+}

package/src/query.ts

@@ -0,0 +1,151 @@
+// 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} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * `query(id)` builder — the DECLARATION layer of Nomos's read-side closure.
+ *
+ * READ-CLOSURE step 1. Measured: the whole-workspace `view()` fold is 24.3s at
+ * 100k intents; an indexed read of the same is 278µs. The fix is structural, not a
+ * perf tweak: a domain DECLARES its reads as NAMED, INDEXED queries; the compiler
+ * (a LATER step — the Rust read engine / FRB / `view()` deletion) generates the
+ * index + a typesafe query system from these declarations; and — because every
+ * query MUST carry an index key — an un-indexed read becomes INEXPRESSIBLE.
+ *
+ * This module adds ONLY the declaration + its TYPE-STATE. It mirrors the
+ * additive, omit-when-empty, identity-bearing pattern of `directive.ts`'s
+ * `.reads()`/`.emits()`: a query a domain declares is carried into the canonical
+ * manifest (and USD IR) and becomes part of the domain IDENTITY; a domain that
+ * declares NO query is byte-identical to before this existed.
+ *
+ * The TYPE-STATE is the mechanical boundary's first brick. `query(id)` yields a
+ * `KeylessQuery` whose ONLY method is `.key(...)`; `.returns(...)`/registration
+ * live solely on the `Query` that `.key(...)` produces. So a query with no index
+ * key cannot even be CONSTRUCTED — "no un-indexed query is expressible" is proven
+ * at the type level, before any runtime check.
+ */
+import type { AggregateHandle } from "./aggregate.js";
+import type { Field } from "./fields.js";
+
+type StringKeyOf<T> = Extract<keyof T, string>;
+
+type JsonFieldKeys<F extends Record<string, Field>> = {
+  [K in StringKeyOf<F>]: F[K] extends Field<unknown, "json"> ? K : never;
+}[StringKeyOf<F>];
+
+/**
+ * Legal indexed key paths for a returned aggregate:
+ *   - a declared top-level aggregate field; or
+ *   - a dotted path rooted at a JSON leaf (`placement.siteId`), which the read
+ *     manifest routes as an explicit nested index.
+ */
+export type QueryableFieldPath<F extends Record<string, Field>> =
+  | StringKeyOf<F>
+  | `${JsonFieldKeys<F>}.${string}`;
+
+type QueryKeyCompatibility<
+  K extends readonly string[],
+  F extends Record<string, Field>,
+> = Exclude<K[number], QueryableFieldPath<F>> extends never
+  ? unknown
+  : {
+      readonly __query_key_error__: `query key '${Exclude<K[number], QueryableFieldPath<F>>}' is not a field on returned aggregate`;
+    };
+
+/**
+ * A FINISHED query declaration: an id, the INDEX KEY (the ordered field list the
+ * generated index is built over — order is the index column order, PRESERVED, not
+ * sorted), and the aggregate TYPE id it `returns`. Minimal by design: params /
+ * where / scope are later steps.
+ */
+export interface QueryDecl {
+  readonly id: string;
+  /** Index key fields, in DECLARED order (= index column order). */
+  readonly key: string[];
+  /** The aggregate TYPE id the query returns, e.g. `SampleThingAggregate`. */
+  readonly returns: string;
+}
+
+/**
+ * The managed read indexes IMPLIED by an aggregate's `t.hasMany` relations. Each
+ * `t.hasMany(Child).via("parent")` field declares the inverse index `Child by parent` — the read side
+ * the framework maintains so `parent.children` is an O(result) lookup, not a scan. The dev writes no
+ * `query(...)`: the relation IS the index. Deterministic (sorted by id), so it can be merged into the
+ * aggregate's declared queries without changing order-dependent output.
+ */
+export function hasManyIndexes(agg: AggregateHandle): QueryDecl[] {
+  const out: QueryDecl[] = [];
+  // `agg.hasMany` holds exactly the virtual inverses, so no kind check is needed here —
+  // the partition in `aggregate()` already guarantees every member is a `t.hasMany`.
+  for (const field of Object.values(agg.hasMany as Record<string, Field>)) {
+    if (field.refAggregateId !== undefined && field.viaField !== undefined) {
+      out.push({
+        id: `${field.refAggregateId}_by_${field.viaField}`,
+        key: [field.viaField],
+        returns: field.refAggregateId,
+      });
+    }
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * The registerable form of a query: it has an index key, so `.returns(...)` (which
+ * fixes the returned aggregate type and yields the finished {@link QueryDecl}) is
+ * available. This is the ONLY shape carrying `.returns` — see {@link KeylessQuery}.
+ */
+export interface Query<K extends readonly string[] = readonly string[]> {
+  readonly id: string;
+  readonly key: readonly [...K];
+  /**
+   * Fix the aggregate TYPE this query returns, producing the finished declaration.
+   * Takes a typed HANDLE (never the string id) — a typo'd handle is a compile
+   * error, the same convention as `directive`'s referential markers.
+   */
+  returns<const Id extends string, F extends Record<string, Field>>(
+    aggregate: AggregateHandle<Id, F> & QueryKeyCompatibility<K, F>,
+  ): QueryDecl;
+}
+
+/**
+ * The INITIAL, un-keyed query — its ONLY method is `.key(...)`. It deliberately has
+ * NO `.returns` and is NOT a `QueryDecl`, so `query("q").returns(...)` (skipping the
+ * index key) is a COMPILE error and a key-less query cannot be constructed. THIS is
+ * the type-level "no un-indexed query expressible" property.
+ */
+export interface KeylessQuery {
+  readonly id: string;
+  /**
+   * Declare the INDEX KEY — the ordered field list the generated index is built
+   * over. Order is significant (index column order) and is PRESERVED, never sorted.
+   * Returns the registerable {@link Query} (the only shape exposing `.returns`).
+   */
+  key<const K extends readonly [string, ...string[]]>(...fields: K): Query<K>;
+}
+
+/**
+ * Begin a query declaration. Returns a {@link KeylessQuery}: until `.key(...)` is
+ * called, neither `.returns` nor a finished `QueryDecl` exists — the index key is
+ * NOT optional, it is a prerequisite for the query to take any further shape.
+ */
+export function query<const Id extends string>(id: Id): KeylessQuery {
+  return {
+    id,
+    key<const K extends readonly [string, ...string[]]>(...fields: K): Query<K> {
+      // Preserve declared order — this list is the index's column order, not a set.
+      const keyFields = [...fields] as unknown as readonly [...K];
+      return {
+        id,
+        key: keyFields,
+        returns<const AggId extends string, F extends Record<string, Field>>(
+          aggregate: AggregateHandle<AggId, F> & QueryKeyCompatibility<K, F>,
+        ): QueryDecl {
+          return { id, key: [...keyFields], returns: aggregate.id };
+        },
+      };
+    },
+  };
+}

package/src/read.ts

@@ -0,0 +1,54 @@
+// 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.
+
+/**
+ * THE CAPTURED READ — the plan's read side, made deterministic (Jack 2026-06-08).
+ *
+ * A plan that can't read can't decide anything; so it reads — through DECLARED, O(1) DSL queries (a
+ * managed index, never a scan). The catch that keeps determinism: every read is CAPTURED. The library
+ * calls the ONE host read capability `nomos.read(queryId, args)`, records `{queryId, args, result}` into
+ * a per-dispatch footprint, and `executeDirectiveToIntent` attaches it to the intent (all taken at the intent's HLC).
+ *
+ * `nomos.read` is the exact twin of `nomos.rng`: a LIVE source at author (the host serves it from the
+ * projection at the current tip), a CAPTURE replayed at verify (the host returns the recorded result —
+ * never a live re-query). So a write commits both halves of its truth: the events it wrote AND the queries
+ * it read to justify them. The dev never sees `nomos.read` — they call typed DSL queries; the library
+ * routes them here. (See `docs/aggregate_lifecycle_and_relations.md`.)
+ */
+import type { QueryDecl } from "./query.js";
+import type { WireRead } from "./wire.js";
+
+// ── the per-dispatch read footprint — library state drained by `executeDirectiveToIntent` (mirrors the authoring sink) ──
+let footprint: WireRead[] = [];
+/** Clear the footprint before a plan runs (called by `executeDirectiveToIntent`). */
+export function __resetReads(): void {
+  footprint = [];
+}
+/** Take + clear the reads captured during a plan (called by `executeDirectiveToIntent`). */
+export function __drainReads(): WireRead[] {
+  const f = footprint;
+  footprint = [];
+  return f;
+}
+
+interface NomosRead {
+  read(queryId: string, args: Record<string, string>): unknown;
+}
+/** The ONE host read capability — an O(1) projection read (live at author, captured-replay at verify). */
+function host(): NomosRead {
+  return (globalThis as unknown as { nomos: NomosRead }).nomos;
+}
+
+/**
+ * Read an O(1) DSL-defined query on the write path. Returns the result AND captures `{queryId, args,
+ * result}` into the intent's read footprint — so the read is replayable and the write's premise is
+ * committed. `query` is a declared, indexed {@link QueryDecl} (e.g. a `t.hasMany` inverse from
+ * `hasManyIndexes`); `args` are its index-key values.
+ */
+export function read<T = unknown>(query: QueryDecl, args: Record<string, string>): T {
+  const result = host().read(query.id, args) as T;
+  footprint.push({ queryId: query.id, args, result });
+  return result;
+}

package/src/relation.ts

@@ -0,0 +1,189 @@
+// 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} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+// The cross-workspace `relation` declaration (`cross_workspace.md` §2). A TARGET domain
+// declares, on the directive a cross-workspace PR proposes, the relation it will adjudicate:
+// the source/target aggregate endpoints, the BOUNDED evidence read it discloses (the
+// disclosure contract + anti-smuggle key, §2.4), and that an invariant predicate guards it.
+//
+// This is DECLARATION ONLY — symmetric with `emits`/`requires`/`readsCertified`. It lowers
+// into the domain manifest IR (`manifest.ts`, the hash-pinned #136 identity), which the ONE
+// write-path gate (`executor::admit` step 5.5 / `kernel::manifest_view`) resolves to adjudicate
+// a carried PR against the target's OWN law. The invariant PREDICATE itself is executable
+// behaviour (a guard-shaped pure fn over `(target state, carried evidence)`, `evidence.md`
+// §4b) — supplied to the gate as the domain's runtime guard, NOT captured in the manifest
+// (only its PRESENCE is hashed, exactly like a directive `plan`).
+
+/** Freshness of the disclosed source fact (`cross_workspace.md` §2.4). `immutable`
+ * (set-once, e.g. `createdBy`) — any commit proves it. `current-state` (e.g. "is currently an
+ * owner") — point-in-time at the witnessed commit; the target combines it with its own
+ * current state per §3.5. */
+export type EvidenceKind = "immutable" | "current-state";
+
+/** The BOUNDED evidence read a relation discloses over the SOURCE (`cross_workspace.md` §2.4):
+ * exactly the fields the invariant reads, the predicate over the source aggregate, and the
+ * freshness kind. This IS the disclosure contract (the target learns these fields and NOTHING
+ * else) AND the anti-smuggle key (a carried witness must match this declared read exactly). */
+export interface RelationEvidence {
+  /** The source aggregate TYPE the read selects from (e.g. `ThingAggregate`). */
+  readonly aggregate: string;
+  /** The exact fields disclosed (the SELECT list). The SET is the contract. */
+  readonly select: string[];
+  /** The bounded predicate over the source (the WHERE) — the read's scope. */
+  readonly where: string;
+  /** `immutable` or `current-state` — governs whether freshness bites (§3.5). */
+  readonly kind: EvidenceKind;
+}
+
+/** The PROVEN facts a relation invariant predicate consumes (`cross_workspace.md` §2.4): the
+ * verified carried-evidence fields (the declared `select`, e.g. `createdBy`/`thingId`), the
+ * PROVEN author of the source commit, and the proposed target directive's own payload arguments.
+ * This is deliberately small: no relation recipe, no hidden target-state summary, no generated
+ * write authority. If a domain needs more target-owned facts, it must declare/read them through
+ * ordinary Nomos law, not through a manifest-side cross-workspace template. */
+export interface InvariantEvidence {
+  /** The disclosed source fields → values (EXACTLY the relation's declared `select`). The
+   * least-disclosure surface, e.g. `{ createdBy: "david", thingId: "thing-A" }`. The body reads
+   * the tenant-specific field names IT declared in the relation's `select` here. */
+  readonly fields: Record<string, string>;
+  /** The PROVEN author of the source commit (the verified `envelope.json` attribution actor). */
+  readonly authoredBy: string;
+  /** The target directive payload as proposed by the incoming ordinary intent. The invariant
+   * compares these arguments with `fields` and `authoredBy`; it does not receive authority to
+   * synthesize any other write. */
+  readonly proposed: Record<string, string>;
+}
+
+/** The verdict an invariant body returns (`cross_workspace.md` §2.1 / §4b — symmetric with the
+ * `guard` outcome union). `{ accept: true }` ⇒ the PR's `proposes` merges; `{ reject: code }` ⇒
+ * a typed decline (the fail receipt carries ONLY `code`, §2.4 least-disclosure). */
+export type InvariantVerdict = { readonly accept: true } | { readonly reject: string };
+
+/** The EXECUTABLE invariant predicate body (`cross_workspace.md` §2.1 / §4b): a guard-shaped PURE
+ * function of `(the TARGET's own current state, the PROVEN carried evidence)` → {@link
+ * InvariantVerdict}. It reads ONLY the §1.1 enforceable set (carried self-verifying evidence +
+ * target authoritative state, both supplied in {@link InvariantEvidence}) — NEVER a live source
+ * read ([[determinism-or-death]]). The body ships in the engine bundle (compiled, like a directive
+ * `plan`), NOT in the manifest (only its PRESENCE is hashed); the gate evaluates it IN THE SEALED
+ * ENGINE over the carried evidence + the target state — the SAME engine path `plan()` uses. */
+export type InvariantBody = (evidence: InvariantEvidence) => InvariantVerdict;
+
+/** A finished cross-workspace relation declaration (`cross_workspace.md` §2.1). Attached to a
+ * directive via `.declaresRelation(...)`; lowered into the manifest IR keyed by `proposes`. */
+export interface RelationDecl {
+  /** The relation id (e.g. `ThingOwnership`). */
+  readonly id: string;
+  /** The SOURCE aggregate TYPE that PROPOSES the contribution (e.g. `ThingAggregate`). */
+  readonly source: string;
+  /** The TARGET aggregate TYPE that ACCEPTS the contribution (e.g. `UserPermission`). */
+  readonly target: string;
+  /** The TARGET directive the relation proposes into (the gate's lookup key; e.g. `grantOwner`).
+   * Defaults to the directive the relation is declared on. */
+  readonly proposes: string;
+  /** The bounded evidence read over the source — the disclosure contract. */
+  readonly evidence: RelationEvidence;
+  /** Whether an invariant predicate is declared (presence only — the body is executable, not
+   * hashed; the gate evaluates the domain's runtime guard). */
+  readonly hasInvariant: boolean;
+  /** The EXECUTABLE invariant predicate body (`cross_workspace.md` §2.1). `undefined` when no
+   * invariant is declared (`hasInvariant: false`). The body is COMPILED INTO THE ENGINE BUNDLE
+   * (not the manifest — only `hasInvariant` is hashed, exactly like a directive `plan`); the gate
+   * evaluates it in the sealed engine over the carried evidence + target state (the determinism /
+   * sovereignty core — the verdict is read from THIS domain law, not transcribed into Rust). */
+  readonly invariant?: InvariantBody;
+}
+
+/** Stage 1 of the builder: id + the two endpoints. */
+class RelationSourceStep<Id extends string> {
+  constructor(private readonly id: Id) {}
+  /** Declare the SOURCE → TARGET endpoints (aggregate TYPE ids). */
+  endpoints(source: string, target: string): RelationProposesStep<Id> {
+    return new RelationProposesStep(this.id, source, target);
+  }
+}
+
+/** Stage 2: the proposed target directive + the bounded evidence read. */
+class RelationProposesStep<Id extends string> {
+  constructor(
+    private readonly id: Id,
+    private readonly source: string,
+    private readonly target: string,
+  ) {}
+  /** Declare the target directive the relation proposes + the BOUNDED evidence read (the
+   * disclosure contract). `hasInvariant` defaults true (a relation without a guard would admit
+   * any signed evidence — the dev opts OUT explicitly via `{ hasInvariant: false }`, never by
+   * omission).
+   *
+   * The INVARIANT BODY (`opts.invariant`, or the chained `.invariant(fn)`) is the EXECUTABLE
+   * guard-shaped predicate the gate evaluates IN THE SEALED ENGINE over the carried evidence +
+   * the target's own state (`cross_workspace.md` §2.1). It is compiled into the engine bundle,
+   * NOT the manifest (only `hasInvariant` is hashed, like a directive `plan`) — so refactoring
+   * the predicate without changing its declared shape does not move the domain hash, yet the
+   * gate verdict is READ FROM THIS DOMAIN LAW (determinism/sovereignty core), never a Rust
+   * transcription. Returns a {@link RelationProposedStep} carrying the chainable `.invariant`. */
+  proposes(
+    directive: string,
+    evidence: RelationEvidence,
+    opts: { hasInvariant?: boolean; invariant?: InvariantBody } = {},
+  ): RelationProposedStep {
+    return new RelationProposedStep({
+      id: this.id,
+      source: this.source,
+      target: this.target,
+      proposes: directive,
+      // Sort the disclosed fields — the SET is the contract (and the Rust view sorts too, so the
+      // manifest is byte-stable regardless of authoring order).
+      evidence: { ...evidence, select: [...evidence.select].sort() },
+      // An explicit body implies presence; otherwise `hasInvariant` defaults true. A relation that
+      // declares an invariant body but `{ hasInvariant: false }` is a contradiction the builder
+      // refuses to encode (presence MUST track the body).
+      hasInvariant: opts.invariant !== undefined ? true : (opts.hasInvariant ?? true),
+      ...(opts.invariant !== undefined ? { invariant: opts.invariant } : {}),
+    });
+  }
+}
+
+/** Stage 3: the finished relation, chainable with `.invariant(fn)` to attach the EXECUTABLE
+ * predicate body (`cross_workspace.md` §2.1). A {@link RelationProposedStep} IS a finished
+ * {@link RelationDecl} (the `.declaresRelation(...)` site accepts it directly), with the extra
+ * `.invariant(...)` ergonomic — `relation("X").endpoints(s,t).proposes(d, read).invariant(fn)`. */
+class RelationProposedStep implements RelationDecl {
+  readonly id: string;
+  readonly source: string;
+  readonly target: string;
+  readonly proposes: string;
+  readonly evidence: RelationEvidence;
+  readonly hasInvariant: boolean;
+  readonly invariant?: InvariantBody;
+  constructor(decl: RelationDecl) {
+    this.id = decl.id;
+    this.source = decl.source;
+    this.target = decl.target;
+    this.proposes = decl.proposes;
+    this.evidence = decl.evidence;
+    this.hasInvariant = decl.hasInvariant;
+    // `exactOptionalPropertyTypes`: only set the optional `invariant` when present (never
+    // assign an explicit `undefined`), so a relation without executable body omits the property.
+    if (decl.invariant !== undefined) this.invariant = decl.invariant;
+  }
+  /** Attach the EXECUTABLE invariant predicate body — the guard-shaped pure fn the gate evaluates
+   * in the sealed engine over `(target state, carried evidence)` (`cross_workspace.md` §2.1 / §4b).
+   * Sets `hasInvariant: true` (presence tracks the body). Returns a NEW step (non-destructive).
+   * Reads `relation("X").endpoints(s,t).proposes(d, read).withInvariant((ev) => …)` at the site. */
+  withInvariant(fn: InvariantBody): RelationProposedStep {
+    return new RelationProposedStep({ ...(this as RelationDecl), hasInvariant: true, invariant: fn });
+  }
+}
+
+/** Begin a cross-workspace relation declaration:
+ * `relation("ThingOwnership").endpoints("ThingAggregate","UserPermission")
+ *    .proposes("grantOwner", { aggregate:"ThingAggregate", select:["createdBy","thingId"],
+ *                              where:"thingId == $thingId", kind:"immutable" })`.
+ * Pure declaration — lowered into the manifest IR (`cross_workspace.md` §2). */
+export function relation<const Id extends string>(id: Id): RelationSourceStep<Id> {
+  return new RelationSourceStep(id);
+}

package/src/report/csv.ts

@@ -0,0 +1,54 @@
+// 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} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * `csv(rows, columns)` — a tiny deterministic CSV builder for report renders.
+ *
+ * Runs INSIDE the sealed engine over the host-fed `queryRows` (the render is a pure
+ * function — no clock, no rng, no ambient). Deterministic by construction: fixed
+ * column order, RFC-4180 quoting, `\n` line endings (never the platform's), and the
+ * rows arrive already totally-ordered from the host query port.
+ */
+import type { QueryRow, SqlRow } from "../report.js";
+
+/** RFC-4180 field quoting: quote iff the field contains `,`, `"`, or a newline. */
+function quote(field: string): string {
+  if (/[",\n\r]/.test(field)) {
+    return '"' + field.replace(/"/g, '""') + '"';
+  }
+  return field;
+}
+
+/**
+ * Render `rows` to CSV over the named `columns` (in order). Each column name is a
+ * key of `QueryRow`. The header row is the column names; each data row is the
+ * stringified field values. `\n` separated, trailing newline — a stable byte shape.
+ */
+export function csv(rows: QueryRow[], columns: (keyof QueryRow)[]): string {
+  const lines: string[] = [];
+  lines.push(columns.map((c) => quote(String(c))).join(","));
+  for (const row of rows) {
+    lines.push(columns.map((c) => quote(String(row[c]))).join(","));
+  }
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Render `SqlRow`s (sealed-SQL report rows: column name → cell text) to CSV over
+ * the named `columns` in order. Same deterministic byte shape as `csv` — fixed
+ * column order, RFC-4180 quoting, `\n` endings — but keyed by string column names
+ * (the sealed query's SELECT aliases) rather than the fixed `QueryRow` shape. A
+ * missing column renders as the empty field (the SELECT alias governs presence).
+ */
+export function csvRows(rows: SqlRow[], columns: string[]): string {
+  const lines: string[] = [];
+  lines.push(columns.map((c) => quote(c)).join(","));
+  for (const row of rows) {
+    lines.push(columns.map((c) => quote(row[c] ?? "")).join(","));
+  }
+  return lines.join("\n") + "\n";
+}