@githolon/dsl 0.1.0

package/src/extremum.ts

@@ -0,0 +1,227 @@
+// 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.
+
+/**
+ * `min(id, field)` / `max(id, field)` builders — the EXTREMUM siblings of `sum`.
+ *
+ * A `min`/`max` declares a NAMED, MAINTAINED running extremum of an `int`-kind field
+ * across every aggregate of the `of`-type (optionally filtered by a `.where(pred)`
+ * predicate and partitioned by a `.by(field)` group-by). The result is ONE value per
+ * group, maintained incrementally as the workspace folds — NEVER a `MIN/MAX(*)` scan
+ * over the `rows` table (the same O(log n) perf invariant as `sum`, via the
+ * `extremum_members` B-tree index).
+ *
+ * The TYPE-STATE mirrors `sum.ts` exactly:
+ *   `min(id, field)` → `TypelessExtremum` (only `.of` available)
+ *   `.of(agg)`       → `Extremum` builder (`.where`, `.by` available; grand-total usable)
+ *   `.where(p)`      → `Extremum` with predicate baked in (`.by` still available)
+ *   `.by(k)`         → `ExtremumDecl` (finished, grouped declaration)
+ *
+ * Both a bare `Extremum` (grand-total) and a grouped `ExtremumDecl` satisfy
+ * `AnyExtremum` — what `DomainModule.mins` / `DomainModule.maxes` accepts.
+ * `finishExtremum` normalizes either to an `ExtremumDecl`.
+ *
+ * VALIDATION RULE (manifest-load, not type-level): the `valueField` parameter MUST be
+ * an `int`-kind field of the `of`-aggregate. The DSL type system cannot enforce this
+ * at the `min/max(id, valueField)` call site (the aggregate is not yet known), but
+ * `AggregateSchemas::parse` (readmodel/src/manifest.rs) performs a no-fallback reject
+ * if the field is absent or non-int on the declared aggregate.
+ *
+ * ORDER-SENSITIVE GUARDRAIL: min/max expose NO `.first`/`.take`/`.orderBy`. min/max
+ * are ORDER-INDEPENDENT REDUCTIONS — `MIN/MAX` over a set is deterministic regardless
+ * of physical row order. Same rationale as `count.ts` / `sum.ts`. Assert the absence;
+ * do NOT add dead methods (LAW 3).
+ *
+ * EMPTY-GROUP SEMANTICS: min/max return `Option<i64>` (Rust) / `int?` (Dart, nullable).
+ * An empty group has NO extremum, and `0` is a LEGITIMATE min/max value — collapsing
+ * empty-group to `0` would be the `sum`-of-0 ambiguity (manifest.rs:274-276). `null`
+ * means "no contributing member"; a non-null value is the extremum. This is HARDER
+ * and CORRECT (LAW 3 — harden, not loosen).
+ */
+import type { AggregateHandle } from "./aggregate.js";
+import type { Field } from "./fields.js";
+import { type Predicate, type CanonicalPred, predBuilder, canonicalizePred } from "./predicate.js";
+
+/** Which kind of extremum — the `kind` discriminant shared between min/max. */
+export type ExtremumKind = "min" | "max";
+
+/**
+ * A FINISHED extremum declaration (the read-engine's input shape): an id, the
+ * aggregate TYPE it tallies, the FIELD being extremised, the `kind` (min|max), the
+ * OPTIONAL predicate, and the OPTIONAL group-by field.
+ */
+export interface ExtremumDecl {
+  readonly id: string;
+  /** `"min"` or `"max"` — the kind of extremum maintained. */
+  readonly kind: ExtremumKind;
+  /** The aggregate TYPE id, e.g. `ListingAggregate`. */
+  readonly of: string;
+  /**
+   * The `int`-kind field being extremised, e.g. `"itemValue"`. MUST be an
+   * `int`-kind field of the `of`-aggregate (validated at manifest-load).
+   */
+  readonly valueField: string;
+  /**
+   * The optional predicate: ONLY aggregates satisfying this predicate contribute.
+   * ABSENT ⇒ every aggregate of the `of`-type is considered.
+   */
+  readonly where?: CanonicalPred;
+  /**
+   * The group-by field name. ABSENT ⇒ a grand total across all (matching)
+   * aggregates of the `of`-type (one synthetic group).
+   */
+  readonly by?: string;
+}
+
+/**
+ * The `Extremum` BUILDER: it has named its `of`-type (and valued field), so `.where(...)`
+ * and `.by(...)` are available. The `F` type parameter carries the `of`-aggregate's
+ * field map so `.where(p => p.field("status").eq("active"))` is keyof-checked.
+ */
+export interface Extremum<F extends Record<string, Field> = Record<string, Field>> {
+  readonly id: string;
+  readonly kind: ExtremumKind;
+  /** The aggregate TYPE id the extremum tallies. */
+  readonly of: string;
+  /** The `int`-kind field being extremised. */
+  readonly valueField: string;
+  /**
+   * Attach an optional PREDICATE: only aggregates satisfying the predicate contribute.
+   * Returns a new `Extremum` with the predicate baked in; `.by(...)` is still available.
+   */
+  where(fn: (p: ReturnType<typeof predBuilder<F>>) => Predicate<F>): Extremum<F>;
+  /**
+   * Partition by a GROUP-BY field. Every distinct value of `groupField` maintains its
+   * own running extremum. Returns a finished `ExtremumDecl`.
+   */
+  by(groupField: string): ExtremumDecl;
+}
+
+/**
+ * The INITIAL, un-typed extremum — its ONLY method is `.of(...)`. An `min/max(id, field)`
+ * without `.of(...)` cannot be used as a declaration: the aggregate type is not optional.
+ */
+export interface TypelessExtremum {
+  readonly id: string;
+  readonly kind: ExtremumKind;
+  /** The `int`-kind field to extremise. */
+  readonly valueField: string;
+  /**
+   * Declare the aggregate TYPE. Takes a typed HANDLE (never a string id). Returns the
+   * `Extremum` builder (the only shape exposing `.where` and `.by`), which is already
+   * a usable grand-total extremum.
+   */
+  of<F extends Record<string, Field>>(aggregate: AggregateHandle<string, F>): Extremum<F>;
+}
+
+/**
+ * Either form a domain may declare in `DomainModule.mins` / `DomainModule.maxes`.
+ * `Extremum<any>` for the same reason as `AnySum = SumDecl | Sum<any>`:
+ * `Extremum<F>` is invariant in `F` (the `where` method), so `Extremum<SpecificFields>`
+ * is not assignable to `Extremum<Record<string,Field>>`. The consumer only accesses
+ * `id`/`kind`/`of`/`valueField`/`by` string fields — it never calls `.where(fn)` — so
+ * `any` is safe.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyExtremum = ExtremumDecl | Extremum<any>;
+
+/** Narrow: an `Extremum` builder exposes a `by` METHOD; an `ExtremumDecl` does not. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isExtremumBuilder(e: AnyExtremum): e is Extremum<any> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return typeof (e as Extremum<any>).by === "function";
+}
+
+/**
+ * Normalize an `AnyExtremum` to a finished `ExtremumDecl`. The grand-total builder
+ * (bare `.of(...)`) becomes `{id, kind, of, valueField}` (no `by`); a grouped
+ * `.by(...)` result is already an `ExtremumDecl` and passes through.
+ */
+export function finishExtremum(e: AnyExtremum): ExtremumDecl {
+  if (isExtremumBuilder(e)) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const b = e as any;
+    const w: CanonicalPred | undefined = b._where;
+    return {
+      id: b.id,
+      kind: b.kind,
+      of: b.of,
+      valueField: b.valueField,
+      ...(w !== undefined ? { where: w } : {}),
+    };
+  }
+  return e;
+}
+
+/** Internal factory so `.where(...)` can return a new Extremum without duplicating impl. */
+function makeExtremum<F extends Record<string, Field>>(
+  id: string,
+  kind: ExtremumKind,
+  ofType: string,
+  valueField: string,
+  where: CanonicalPred | undefined,
+): Extremum<F> {
+  // Same exactOptionalPropertyTypes pattern as makeSum: spread `_where` only when
+  // defined so the key is absent (not `undefined`) in the predicate-free case.
+  const e = {
+    id,
+    kind,
+    of: ofType,
+    valueField,
+    ...(where !== undefined ? { _where: where } : {}),
+    where(fn: (p: ReturnType<typeof predBuilder<F>>) => Predicate<F>): Extremum<F> {
+      const pred = fn(predBuilder<F>());
+      const canonical = canonicalizePred(pred as Predicate<Record<string, Field>>);
+      return makeExtremum<F>(id, kind, ofType, valueField, canonical);
+    },
+    by(groupField: string): ExtremumDecl {
+      return {
+        id,
+        kind,
+        of: ofType,
+        valueField,
+        ...(where !== undefined ? { where } : {}),
+        by: groupField,
+      };
+    },
+  } as unknown as Extremum<F>;
+  return e;
+}
+
+/**
+ * Begin a `min` declaration. `id` is the min's canonical name (e.g.
+ * `"minItemValuePerSite"`); `valueField` is the `int`-kind field on the `of`-aggregate
+ * whose minimum is maintained. Returns a `TypelessExtremum`: until `.of(aggregate)` is
+ * called, the aggregate type is unknown and no usable declaration exists.
+ */
+export function min(id: string, valueField: string): TypelessExtremum {
+  return {
+    id,
+    kind: "min",
+    valueField,
+    of<F extends Record<string, Field>>(aggregate: AggregateHandle<string, F>): Extremum<F> {
+      return makeExtremum<F>(id, "min", aggregate.id, valueField, undefined);
+    },
+  };
+}
+
+/**
+ * Begin a `max` declaration. `id` is the max's canonical name (e.g.
+ * `"maxItemValuePerSite"`); `valueField` is the `int`-kind field on the `of`-aggregate
+ * whose maximum is maintained. Returns a `TypelessExtremum`: until `.of(aggregate)` is
+ * called, the aggregate type is unknown and no usable declaration exists.
+ */
+export function max(id: string, valueField: string): TypelessExtremum {
+  return {
+    id,
+    kind: "max",
+    valueField,
+    of<F extends Record<string, Field>>(aggregate: AggregateHandle<string, F>): Extremum<F> {
+      return makeExtremum<F>(id, "max", aggregate.id, valueField, undefined);
+    },
+  };
+}

package/src/fields.ts

@@ -0,0 +1,291 @@
+// 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.
+
+/**
+ * Field builders (`t.*`). Each field carries:
+ *  - a Zod schema (the single source of truth for its runtime type + TS inference),
+ *  - a merge Driver (defaulted; overridable via `.merge(...)`),
+ *  - a kind tag used to map authored values onto the kernel `Value` shape.
+ *
+ * `.merge(Driver)` is chainable and returns a new immutable Field so inference of
+ * the value type (via Zod) is preserved.
+ */
+import { z } from "zod";
+import { Conflict, Lww, type Driver } from "./drivers.js";
+import type { AggregateHandle } from "./aggregate.js";
+
+export type FieldKind =
+  | "string"
+  | "int"
+  | "enum"
+  | "set"
+  | "map"
+  | "json"
+  | "ref"
+  // `t.hasMany(Child).via(backref)` — a VIRTUAL inverse relation (the 1:N read side of a
+  // `t.ref` on the child). Stored on NOTHING: it is not in the kernel wire schema (encodeKernelSchema
+  // skips it, so it changes no hash) and is never authored directly — `.add` writes the child's
+  // back-reference, and the read engine serves it as the managed `Child by backref` index.
+  | "hasMany"
+  // evidence.md §6/§9.2 — a content-addressed EvidenceRef. The migration target of the
+  // hand-wired `blobRef` `t.jsonObject()` string (thing_structures.ts). The authored
+  // value is the typed EvidenceRef shape; it encodes to a kernel `Value::Evidence`.
+  | "evidence";
+
+/**
+ * The authored shape of an `EvidenceRef` (`evidence.md` §1) — a content-addressed
+ * reference the dev places on an aggregate field via `t.evidence()`. The `hash` is the
+ * git blob oid (computed by the framework from the bytes, peer-side, pure); the dev
+ * supplies the bytes via the dispatch SIDECAR and the framework mints this ref. Mirrors
+ * the kernel `nomos_kernel::evidence::EvidenceRef` byte-for-byte (the field order the
+ * canonicalizer commits).
+ */
+export interface EvidenceRefValue {
+  /** The content hash — git's blob oid (the identity). */
+  hash: string;
+  /** The declared content type (e.g. `application/pdf`). */
+  mediaType: string;
+  /** The byte length of the referenced content. */
+  byteLength: number;
+  /** Where the bytes live: `git` (inline-syncing) or `external` (shreddable storage). */
+  storageClass: "git" | "external";
+}
+
+/** The Zod schema for an authored `EvidenceRefValue` — the single source of truth. */
+export const evidenceRefSchema: z.ZodType<EvidenceRefValue> = z.object({
+  hash: z.string(),
+  mediaType: z.string(),
+  byteLength: z.number().int().nonnegative(),
+  storageClass: z.enum(["git", "external"]),
+});
+
+export interface Field<T = unknown, K extends FieldKind = FieldKind> {
+  /** The kind tag. `K` is the LITERAL kind so the query DSL can constrain `.ref`
+   * to ONLY `kind:'ref'` fields at compile time (`t.ref` → `Field<string,'ref'>`).
+   * `.merge` preserves it. */
+  readonly kind: K;
+  readonly zod: z.ZodType<T>;
+  readonly driver: Driver;
+  /** For `t.ref` cross-workspace edges: the foreign workspace id, if any. */
+  readonly refWorkspace?: string;
+  /** For `t.ref` (the target) AND `t.hasMany` (the child type): the related aggregate's wire id. */
+  readonly refAggregateId?: string;
+  /** For `t.hasMany(Child).via(backref)`: the back-reference field NAME on the child. Virtual. */
+  readonly viaField?: string;
+  /**
+   * For a `t.map(inner)` field: the inner VALUE field's kind (e.g. `"string"` for
+   * `t.map(t.string())`, `"json"` for `t.map(t.json())`). The wire DRIVER is
+   * identical for both (`MapOf(Lww)` — a json leaf encodes to a `Str` value just like
+   * a string), so this changes NO hash; it only tells codegen how to SURFACE each
+   * entry value: a `string`-valued map reads `Map<String,String>` (flat strings),
+   * whereas a `json`-valued map reads `Map<String,Object?>` (each entry JSON-decoded
+   * back to its object) so a value-object map (e.g. a site's `customFields`,
+   * each entry the canonical `CustomField.toJson()`) round-trips losslessly. `undefined`
+   * for a non-map field.
+   */
+  readonly mapValueKind?: FieldKind;
+  /**
+   * For a `json`-kind field: the DECODED SHAPE of its value-object, when the domain
+   * dev can assert it. A `t.json()` leaf is typed `String` in the DSL (the kernel
+   * `Value` is Str|Int only, so a value-object — OR a double/bool — is stored as a
+   * JSON string), but the Rust read engine DECODES it back to whatever it is
+   * (object / list / scalar). The v1-FREE projection needs to know whether to surface
+   * it as a STRUCTURED `Map<String,Object?>` (a strict object reader, e.g. `location`)
+   * or as a permissive `Object?` (a value that can legitimately be a list/scalar — e.g.
+   * a `scaleX` double or an `estimatedCost` authored as a JSON leaf). `"object"` is the
+   * EXPLICIT assertion "this json leaf is always a JSON OBJECT" (set by `t.jsonObject()`);
+   * `undefined` (a plain `t.json()`) means the shape is unknown/non-object → the
+   * projection defaults it to the permissive `Object?`. This flag affects ONLY the
+   * generated frontend projection TYPE — NOT the kernel wire `Schema` (driver-only, see
+   * `encodeKernelSchema`) — so it changes NO hash (identical to `mapValueKind`/`isOptional`).
+   */
+  readonly jsonShape?: "object";
+  /**
+   * Whether a folded aggregate may LACK this field. A SCALAR field
+   * (`string`/`int`/`enum`/`ref`/`json`) that a `.creates` directive does not
+   * always fold (e.g. `description`/`siteType` on a freshly-created site) is marked
+   * `.optional()` so the generated Dart projection type makes it NULLABLE and decodes
+   * a minimal freshly-folded aggregate (DSL codegen GAP 1). COLLECTION fields
+   * (`set`/`map`) are ALWAYS empty-defaultable and never need this. This flag affects
+   * ONLY the generated frontend type's required-vs-optional — NOT the kernel wire
+   * `Schema` (which is driver-only, see `encodeKernelSchema`), so it changes no hash.
+   */
+  readonly isOptional: boolean;
+  /** Returns a copy with the chosen driver (kind literal preserved). */
+  merge(driver: Driver): Field<T, K>;
+  /**
+   * Mark this (scalar) field OPTIONAL: a folded aggregate may lack it, so the
+   * generated Dart type is nullable + tolerant. Chainable + non-destructive (kind
+   * literal + driver preserved). Wraps the Zod schema in `.optional()` so the field
+   * schema IS the single source of truth codegen derives required-vs-optional from.
+   */
+  optional(): Field<T | undefined, K>;
+  /** Phantom to keep T load-bearing for inference. */
+  readonly _t?: T;
+}
+
+function makeField<T, K extends FieldKind = FieldKind>(
+  kind: K,
+  zod: z.ZodType<T>,
+  driver: Driver,
+  extra: {
+    refWorkspace?: string;
+    refAggregateId?: string;
+    viaField?: string;
+    isOptional?: boolean;
+    mapValueKind?: FieldKind;
+    jsonShape?: "object";
+  } = {},
+): Field<T, K> {
+  const isOptional = extra.isOptional ?? false;
+  const f: Field<T, K> = {
+    kind,
+    zod,
+    driver,
+    isOptional,
+    ...(extra.refWorkspace !== undefined ? { refWorkspace: extra.refWorkspace } : {}),
+    ...(extra.refAggregateId !== undefined ? { refAggregateId: extra.refAggregateId } : {}),
+    ...(extra.viaField !== undefined ? { viaField: extra.viaField } : {}),
+    ...(extra.mapValueKind !== undefined ? { mapValueKind: extra.mapValueKind } : {}),
+    ...(extra.jsonShape !== undefined ? { jsonShape: extra.jsonShape } : {}),
+    merge(d: Driver) {
+      return makeField<T, K>(kind, zod, d, extra);
+    },
+    optional(): Field<T | undefined, K> {
+      // Wrap the Zod once (`.optional()` is idempotent enough — re-wrapping an
+      // already-optional schema stays optional). Carry the flag so codegen reads it
+      // directly without re-introspecting Zod.
+      return makeField<T | undefined, K>(kind, zod.optional(), driver, {
+        ...extra,
+        isOptional: true,
+      });
+    },
+  };
+  return f;
+}
+
+/** Infer the authored value type of a Field. */
+export type FieldValue<F> = F extends Field<infer T> ? T : never;
+
+export const t = {
+  string(): Field<string, "string"> {
+    return makeField("string", z.string(), Lww);
+  },
+  int(): Field<number, "int"> {
+    return makeField("int", z.number().int(), Lww);
+  },
+  /** Enum via `as const` literal union — value typos squeal at compile time. */
+  enum<const E extends readonly [string, ...string[]]>(values: E): Field<E[number], "enum"> {
+    return makeField<E[number], "enum">(
+      "enum",
+      z.enum(values) as unknown as z.ZodType<E[number]>,
+      Lww,
+    );
+  },
+  /** A set of items. Defaults to AddWins is NOT assumed — caller picks via .merge; default Lww-on-set is wrong, so we default to Conflict-free AddWins-friendly Lww only when overridden. */
+  set(_inner: Field<string>): Field<string[], "set"> {
+    // Authored as an array; encodes to a Set Value (AddToSet op). Default driver
+    // is AddWins since a set field that isn't add-wins is almost always a bug,
+    // but it remains overridable.
+    return makeField<string[], "set">("set", z.array(z.string()), { kind: "AddWins" });
+  },
+  /** A map of driven sub-fields. Defaults to MapOf(Lww); override via .merge(MapOf(...)).
+   * Records the inner VALUE field's `kind` (`mapValueKind`) so codegen can surface a
+   * `json`-valued map (`t.map(t.json())`) as `Map<String,Object?>` (each entry decoded
+   * back to its object — loss-less value-object round-trip) while a `string`-valued map
+   * stays `Map<String,String>`. The wire driver is identical (`MapOf(Lww)` — both encode
+   * a leaf to `Str`), so this changes no hash. */
+  map<T>(inner: Field<T>): Field<Record<string, T>, "map"> {
+    return makeField<Record<string, T>, "map">(
+      "map",
+      z.record(z.string(), inner.zod),
+      { kind: "MapOf", inner: inner.driver },
+      { mapValueKind: inner.kind },
+    );
+  },
+  /** Arbitrary JSON-string leaf (used inside maps); encodes as a Str at op time. The
+   * decoded shape is UNKNOWN/non-object (it may be a double/bool/list authored as a
+   * JSON leaf — the kernel `Value` is Str|Int only), so the v1-free projection surfaces
+   * it as a permissive `Object?`. Use `t.jsonObject()` when the leaf is ALWAYS an OBJECT
+   * value-object (e.g. a `location`) to get a strict `Map<String,Object?>` read type. */
+  json(): Field<string, "json"> {
+    return makeField<string, "json">("json", z.string(), Lww);
+  },
+  /** A JSON-OBJECT value-object leaf: an arbitrary JSON-string leaf (identical wire +
+   * driver to `t.json()` — a `Str` at op time, so NO hash change) whose decoded value is
+   * asserted to ALWAYS be a JSON OBJECT (e.g. `location`, `address`, `blobRef`,
+   * `structuralAssignment`). The v1-FREE projection surfaces it as a STRUCTURED
+   * `Map<String,Object?>` with a STRICT reader (a present-but-non-object value throws —
+   * the strict-decode contract), as opposed to a plain `t.json()` (decoded shape unknown
+   * → permissive `Object?`). Marks `jsonShape:"object"`; the kind stays `"json"`. */
+  jsonObject(): Field<string, "json"> {
+    return makeField<string, "json">("json", z.string(), Lww, { jsonShape: "object" });
+  },
+  /**
+   * Reference to another aggregate (stored as its id string).
+   *  - `t.ref(Agg)`               — same-workspace.
+   *  - `t.ref('otherWsId', Agg)`  — cross-workspace (PR-tier edge); just marked,
+   *    routing is the kernel's job.
+   */
+  ref: refImpl as RefFn,
+  /**
+   * A 1:N INVERSE relation — the read side of a `t.ref` on the child (`aggregate_lifecycle_and_relations.md`).
+   * `t.hasMany(Child).via("parent")` on a Parent declares "the Children whose `parent` ref points here".
+   * It is VIRTUAL: nothing is stored on the parent (encodeKernelSchema skips it → no hash change). From this one
+   * line the framework derives BOTH sides — `parent.add("children", child)` writes the child's back-ref
+   * (one event on the CHILD, parent untouched), and the read engine serves `parent.children` as the
+   * managed `Child by parent` index. The dev never builds a write-amplifying parent collection.
+   */
+  hasMany(child: AggregateHandle<string, Record<string, Field>>): {
+    via(backref: string): Field<string[], "hasMany">;
+  } {
+    return {
+      via(backref: string): Field<string[], "hasMany"> {
+        return makeField<string[], "hasMany">("hasMany", z.array(z.string()), Conflict, {
+          refAggregateId: child.id,
+          viaField: backref,
+        });
+      },
+    };
+  },
+  /**
+   * A content-addressed EVIDENCE reference (`evidence.md` §6/§9.2). The authored value is
+   * the typed {@link EvidenceRefValue} ({hash, mediaType, byteLength, storageClass}); it
+   * encodes to a first-class kernel `Value::Evidence` (NOT a JSON string), the gate
+   * evidence-backs it (re-hash the dispatch sidecar + store), and codegen emits a typed
+   * `EvidenceRef` class (TS + Dart). This is the migration target of the hand-wired
+   * `blobRef` `t.jsonObject()` string — re-pointing the LIVE Attachment domain is the §7
+   * "use exhaustively" phase (deferred); this builder + codegen + a test-domain field
+   * land the type now. Default driver Lww (a content ref is replaced wholesale — a Scalar
+   * value, like a string), overridable via `.merge(...)`.
+   */
+  evidence(): Field<EvidenceRefValue, "evidence"> {
+    return makeField<EvidenceRefValue, "evidence">("evidence", evidenceRefSchema, Lww);
+  },
+};
+
+interface RefFn {
+  (target: AggregateHandle<string, Record<string, Field>>): Field<string, "ref">;
+  (
+    workspaceId: string,
+    target: AggregateHandle<string, Record<string, Field>>,
+  ): Field<string, "ref">;
+}
+
+function refImpl(
+  a: string | AggregateHandle<string, Record<string, Field>>,
+  b?: AggregateHandle<string, Record<string, Field>>,
+): Field<string, "ref"> {
+  if (typeof a === "string") {
+    const target = b!;
+    return makeField<string, "ref">("ref", z.string(), Conflict, {
+      refWorkspace: a,
+      refAggregateId: target.id,
+    });
+  }
+  return makeField<string, "ref">("ref", z.string(), Conflict, { refAggregateId: a.id });
+}

package/src/framework/bootstrap.ts

@@ -0,0 +1,22 @@
+// 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.
+
+/**
+ * Stage-0 bootstrap domain.
+ *
+ * Genesis pins this package so an empty GitHolon has exactly one executable
+ * authority: install the Nomos lifecycle controller package. It deliberately
+ * exposes the narrow stage-zero intent `bootstrap/installDomain`; after Nomos is
+ * active, all future domain lifecycle authoring must use installed Nomos law.
+ */
+
+export {
+  DomainInstallation,
+  PolicyBundle,
+  installDomain,
+  policyAggregateId,
+} from "./domain_lifecycle.js";

package/src/framework/disclosure.ts

@@ -0,0 +1,108 @@
+// 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 `disclosure` domain — a recorded, re-derivable report disclosure.
+ *
+ * When a report is generated and handed to a recipient (a regulator, an auditor),
+ * the FACT of the disclosure is itself a first-class, append-only kernel record.
+ * A `Disclosure` pins everything needed to RE-DERIVE the disclosed
+ * artifact byte-for-byte:
+ *
+ *   * `sourceCommit` — the ledger commit the report's query was resolved @ (the
+ *     projection is rebuilt @ this commit on re-derivation),
+ *   * `queryHash`    — sha256 of the canonical query AST (which question),
+ *   * `artifactSha`  — the content-addressed blob oid of the rendered bytes (the
+ *     answer — `put_blob(render_output)` must reproduce this exactly),
+ *   * `recipient` / `purpose` — the disclosure's audit metadata,
+ *   * `generatedBy` / `generatedAt` — who/when authored it.
+ *
+ * Re-derivation = verification: rebuild the projection @ `sourceCommit`, re-run the
+ * report feeding the captured rows, and assert `put_blob(render) == artifactSha`.
+ * Because the artifact is content-addressed and the query is pinned, a recorded
+ * disclosure is provably the bytes that were disclosed.
+ *
+ * Authored against the STABLE DSL only (typed fields + drivers + a `.creates`
+ * directive). All provenance fields are immutable-after-create (NOTE 1a in
+ * identity.ts) — a disclosure is a frozen fact — modelled as `Lww` (a second write
+ * merely converges; the real semantic is create-only, a kernel gap flagged there).
+ */
+import { z } from "zod";
+import { aggregate, instance } from "../aggregate.js";
+import { t } from "../fields.js";
+import { Lww } from "../drivers.js";
+import { directive } from "../directive.js";
+import { set } from "../ops.js";
+
+/**
+ * The Disclosure — a frozen record of one report disclosure. Keyed by a
+ * `disclosureId` (instance-bound). Every field is immutable-after-create provenance.
+ */
+export const Disclosure = aggregate("Disclosure", {
+  disclosureId: t.string().merge(Lww), // immutable-after-create
+  reportId: t.string().merge(Lww), // which report (e.g. a recently-touched report)
+  reportVersion: t.string().merge(Lww), // the report's declared version (REPORT axis)
+  // The DOMAIN-VERSION axis (#136): the set of domain identity hashes
+  // { domain → sha256(canonical manifest) } active for the report's domains at
+  // capture, JSON-encoded (sorted keys → byte-stable). This is what lets a
+  // why-different diff report "data identical but embodied-carbon domain v3→v4":
+  // two disclosures with an identical resultDigest but a different domainVersionSet
+  // prove the difference is a VERSION change, not a data change. Immutable-after-
+  // create like every other provenance field.
+  domainVersionSet: t.string().merge(Lww),
+  sourceCommit: t.string().merge(Lww), // ledger commit the query was resolved @ (DATA axis)
+  queryHash: t.string().merge(Lww), // sha256(canonical query AST) (QUERY axis)
+  resultDigest: t.string().merge(Lww), // sha256(canonical totally-ordered rows)
+  artifactSha: t.string().merge(Lww), // content-addressed oid of the rendered bytes
+  recipient: t.string().merge(Lww), // who the disclosure was made to
+  purpose: t.string().merge(Lww), // why (audit metadata)
+  generatedBy: t.string().merge(Lww), // authoring actor
+  generatedAt: t.string().merge(Lww), // ISO-8601
+});
+
+/**
+ * `recordDisclosure` — `.creates` a Disclosure (instance-bound by
+ * `disclosureId`). Rejects a double-create (RefMode::Create). The render bytes are
+ * NOT in the payload — they are `put_blob`'d separately to the content-addressed
+ * store and only their `artifactSha` is recorded here (the disclosure points at the
+ * artifact; it does not embed it).
+ */
+export const recordDisclosure = directive("recordDisclosure")
+  .creates(Disclosure)
+  .payload(
+    z.object({
+      disclosureId: z.string(),
+      reportId: z.string(),
+      reportVersion: z.string(),
+      domainVersionSet: z.string(),
+      sourceCommit: z.string(),
+      queryHash: z.string(),
+      resultDigest: z.string(),
+      artifactSha: z.string(),
+      recipient: z.string(),
+      purpose: z.string(),
+      generatedBy: z.string(),
+      generatedAt: z.string(),
+    }),
+  )
+  .plan((p) => {
+    const d = instance(Disclosure, p.disclosureId);
+    return [
+      set(d, "disclosureId", p.disclosureId),
+      set(d, "reportId", p.reportId),
+      set(d, "reportVersion", p.reportVersion),
+      set(d, "domainVersionSet", p.domainVersionSet),
+      set(d, "sourceCommit", p.sourceCommit),
+      set(d, "queryHash", p.queryHash),
+      set(d, "resultDigest", p.resultDigest),
+      set(d, "artifactSha", p.artifactSha),
+      set(d, "recipient", p.recipient),
+      set(d, "purpose", p.purpose),
+      set(d, "generatedBy", p.generatedBy),
+      set(d, "generatedAt", p.generatedAt),
+    ];
+  });