@githolon/dsl 0.1.0

package/src/ops.ts

@@ -0,0 +1,145 @@
+// 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.
+
+/**
+ * Op helpers — the declarative ops a directive's `plan` returns. They map 1:1 to
+ * the kernel's `Op` (Set / AddToSet / SetEntry).
+ *
+ * Type-safety (the whole point):
+ *  - the field name is checked via `keyof` against the aggregate's fields;
+ *  - the value is type-checked against THAT field's declared type.
+ * So `set(thing, 'pos', 10)` compiles, but `set(thing, 'poss', …)` and
+ * `set(thing, 'pos', 'hi')` are compile errors.
+ */
+import type { AggregateHandle, BoundAggregate } from "./aggregate.js";
+import type { Field, FieldValue } from "./fields.js";
+
+/**
+ * A FIELD op, retaining the source aggregate id + field for deterministic wire encoding.
+ *
+ * `aggregateId` is the address the op targets: for an unbound handle it is the
+ * aggregate TYPE (legacy one-per-workspace shape); for a bound ref
+ * (`instance(h, id)`) it is the concrete INSTANCE id, and `aggregateType` carries
+ * the TYPE so the directive runtime can stamp the `__type` provenance `view()` reads (#105).
+ */
+export interface FieldOp {
+  readonly aggregateId: string;
+  /** The aggregate TYPE, present only when the op targets a bound instance ref. */
+  readonly aggregateType?: string;
+  /**
+   * Optional explicit referential marker for this op's aggregate bucket. Normal
+   * fanout defaults siblings to `Mutate`; framework lifecycle directives can mark
+   * a sibling bucket as `ensures`/`creates` without hand-authoring wire events.
+   */
+  readonly marker?: PlannedEventMarker;
+  readonly field: string;
+  readonly kind: "set" | "addToSet" | "setEntry";
+  readonly value?: unknown;
+  readonly items?: readonly string[];
+  readonly entryKey?: string;
+}
+
+export type PlannedEventMarker = "creates" | "mutates" | "ensures" | "archives";
+
+/**
+ * A STRIKE op — retract (logically remove) the intent `target`. The kernel folds a
+ * strike by PARITY (`struck_ids`): an odd number of active strikes drops the target;
+ * striking the strike (even) re-applies it. So `strike` is its own undo/redo — toggle.
+ *
+ * It is a first-class, MAXIMALLY COMPOSABLE op: a directive's `plan` returns it in the
+ * SAME `PlannedOp[]` as field ops, so one plan can `strike(X)` AND author replacement
+ * ops in a single atomic intent (that is exactly `replace`). `executeDirectiveToIntent`
+ * routes strikes onto `WireIntent.strikes` (the kernel's strikeout channel) and field ops onto
+ * `events`. The strike flows through the engine plan output (`{events, strikes}`) so it
+ * is VERIFIED at the gate — never a forgeable, out-of-band retraction (determinism law).
+ *
+ * The unlock for the repair domain (#260): `revert`, `replace`, and `drain` all compose
+ * from `strike` + ordinary event ops — no per-hatch machinery.
+ */
+export interface StrikeOp {
+  readonly kind: "strike";
+  /** The intent id to retract (toggle). */
+  readonly target: string;
+}
+
+/** A planned op a directive's `plan` returns — a field write or a strike. */
+export type PlannedOp = FieldOp | StrikeOp;
+
+/**
+ * Strike (retract / toggle-off) the intent `target`. Composable in any `plan`
+ * alongside `set`/`addToSet`/`setEntry`. See {@link StrikeOp}.
+ */
+export function strike(target: string): StrikeOp {
+  return { kind: "strike", target };
+}
+
+/** An op target: either a bare TYPE handle (unbound) or an instance-bound ref. */
+type Target<Id extends string = string, F extends Record<string, Field> = Record<string, Field>> =
+  | AggregateHandle<Id, F>
+  | BoundAggregate<Id, F>;
+
+type Fields<A> = A extends Target<string, infer F> ? F : never;
+
+/** Resolve a target's `{aggregateId, aggregateType}` — bound → instance id + type. */
+function addressOf(agg: Target): { aggregateId: string; aggregateType?: string } {
+  if ((agg as BoundAggregate).__isBoundAggregate === true) {
+    const b = agg as BoundAggregate;
+    return { aggregateId: b.id, aggregateType: b.type };
+  }
+  return { aggregateId: (agg as AggregateHandle).id };
+}
+
+/** Set a scalar field. Field name + value type are both checked. */
+export function set<
+  A extends Target,
+  K extends keyof Fields<A> & string,
+>(agg: A, field: K, value: FieldValue<Fields<A>[K]>): FieldOp {
+  return { ...addressOf(agg), field, kind: "set", value };
+}
+
+/** Return the same field op with an explicit per-aggregate event marker. */
+export function withMarker(op: FieldOp, marker: PlannedEventMarker): FieldOp {
+  return { ...op, marker };
+}
+
+// NOTE (id-mint redesign): the `setReserved` / `ReservedField` mechanism is GONE. Its
+// only member was `__mintSeed` — the per-mint nonce a minted-create recorded so the OLD
+// gate could re-derive the FNV id. The kernel now mints a `"{TypeTag}_{UUIDv7}"` from a
+// HOST-INJECTED rng and the gate VERIFIES the id's shape + type-tag prefix (no re-derive),
+// so there is NO seed to record — a `.creates` plan stamps NOTHING extra. The auto-stamped
+// `__type`/`__id` provenance (the directive runtime adds those) is the only reserved write, and it
+// is the runtime's job, not a plan's. With no reserved field left, this escape hatch is
+// removed (a domain plan only ever calls the schema-checked `set`/`addToSet`/`setEntry`).
+
+/** Add items to a set field. The field's element type must be string[]. */
+export function addToSet<
+  A extends Target,
+  K extends {
+    [P in keyof Fields<A>]: FieldValue<Fields<A>[P]> extends string[] ? P : never;
+  }[keyof Fields<A>] &
+    string,
+>(agg: A, field: K, items: readonly string[]): FieldOp {
+  return { ...addressOf(agg), field, kind: "addToSet", items };
+}
+
+/** Set one entry of a map field. The map's value type is checked. */
+export function setEntry<
+  A extends Target,
+  K extends {
+    [P in keyof Fields<A>]: FieldValue<Fields<A>[P]> extends Record<string, unknown> ? P : never;
+  }[keyof Fields<A>] &
+    string,
+>(
+  agg: A,
+  field: K,
+  key: string,
+  value: FieldValue<Fields<A>[K]> extends Record<string, infer V> ? V : never,
+): FieldOp {
+  return { ...addressOf(agg), field, kind: "setEntry", entryKey: key, value };
+}
+
+export type { Field };

package/src/ordered_read.ts

@@ -0,0 +1,228 @@
+// 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.
+
+/**
+ * `first(id)` / `take(id, n)` builders — ORDER-SENSITIVE ROW reads.
+ *
+ * These are deterministic ONLY under a declared total order. The type-level guardrail
+ * (spec §2.3): a `first` or `take` is UN-CONSTRUCTIBLE without `.orderBy(key)` — the
+ * `*NeedsOrder` intermediate types expose ONLY `.where(...)` and `.orderBy(key)` as their
+ * finishing method. A `first("x").of(Listing)` without `.orderBy(...)` is NOT assignable
+ * to `DomainModule.firsts` → COMPILE ERROR.
+ *
+ * This is the OPPOSITE type-state to count/sum/min/max/exists:
+ *   * count/sum/min/max/exists assert the ABSENCE of `.orderBy` (they are order-INDEPENDENT
+ *     reductions; adding `.orderBy` would be loosening — LAW 3).
+ *   * first/take assert the PRESENCE of `.orderBy` (they are order-SENSITIVE; the finished
+ *     form is UN-CONSTRUCTIBLE without it — the positive guardrail from spec §2.3).
+ *
+ * KEY type constraint: `.orderBy(key)` is keyof-checked against `PredScalarKeys<F>` —
+ * the same scalar kinds (string|enum|ref|int) that produce an EAV index needle. Sets,
+ * maps, json, and evidence fields are rejected because an order over a collection is
+ * UNDEFINED and therefore non-deterministic (LAW 1).
+ *
+ * TOTAL ORDER: the lowered SQL always appends `, aggregate_id` as a MANDATORY second
+ * ORDER-BY term (spec §3c). A non-unique `<key>` without the tiebreak would make LIMIT
+ * row-order-dependent = the death bug. The tiebreak is invisible to the accessor (the
+ * dev declared the sort key; the engine adds the tiebreak automatically). The `order_key`
+ * field is NON-OPTIONAL in the IR (can never be absent — the no-fallback discipline,
+ * `manifest.rs:389-397`).
+ *
+ * NO ORDER-INDEPENDENT SURFACE: first/take expose NO `.where`-free form without
+ * `.orderBy`, and no `.by(...)` group-by (row reads are not partitioned — they return
+ * the top-n entities globally, possibly filtered by predicate). This is coherent: a
+ * "top-n per group" is a different primitive (window function) and out of Slice 2a scope.
+ */
+import type { AggregateHandle } from "./aggregate.js";
+import type { Field } from "./fields.js";
+import { type Predicate, type CanonicalPred, predBuilder, canonicalizePred, type PredScalarKeys } from "./predicate.js";
+
+// ─── IR ───────────────────────────────────────────────────────────────────────
+
+/**
+ * A FINISHED ordered-read declaration (the read-engine's input shape). The MANDATORY
+ * `orderKey` (non-optional at both TS and manifest/Rust levels) is the load-bearing
+ * total-order guarantee. `limit` distinguishes `first` (implicit 1) from `take(n)`.
+ *
+ * ADVERSARIAL CONTRACT: `orderKey` MUST be declared and MUST be a scalar field of the
+ * `of`-aggregate. The manifest-load Rust validation (`manifest.rs`) rejects any
+ * `OrderedReadSpec` whose `order_key` is absent or not a scalar field of `of` — LOUD
+ * reject, no fallback (the `manifest.rs:389-397` discipline).
+ */
+export interface OrderedReadDecl {
+  readonly id: string;
+  /** The aggregate TYPE id the read returns, e.g. `ListingAggregate`. */
+  readonly of: string;
+  /**
+   * The REQUIRED total-order key (a declared scalar field of `of`). Non-optional: the
+   * order-sensitive read is UN-CONSTRUCTIBLE without it (type-level guardrail). The
+   * lowered SQL appends `, aggregate_id` as a mandatory tiebreak (spec §3c).
+   */
+  readonly orderKey: string;
+  /** Whether to sort DESCENDING. Default `false` (ascending). */
+  readonly orderDesc: boolean;
+  /**
+   * The optional predicate: ONLY aggregates satisfying this predicate are candidates.
+   * ABSENT ⇒ every aggregate of the `of`-type is in the candidate set.
+   */
+  readonly where?: CanonicalPred;
+  /**
+   * `1` for `first(id)`, `n` for `take(id, n)`. Both are strictly `LIMIT n` applied
+   * AFTER the full `ORDER BY <key>, aggregate_id` (spec §3 line 49).
+   */
+  readonly limit: number;
+}
+
+// ─── `first` type-state chain ────────────────────────────────────────────────
+
+/**
+ * Intermediate state for `first`: only `.where(...)` and `.orderBy(key)` are available.
+ * `.orderBy(key)` is the ONLY finishing method → `FirstDecl`. Without it, the builder
+ * is NOT assignable to `DomainModule.firsts` (`FirstDecl[]`). This is the positive
+ * guardrail (spec §2.3): the finished form is UN-CONSTRUCTIBLE without a declared order.
+ */
+export interface FirstNeedsOrder<F extends Record<string, Field> = Record<string, Field>> {
+  readonly id: string;
+  readonly of: string;
+  /** Attach a PREDICATE: only aggregates satisfying it are considered. Optional. */
+  where(fn: (p: ReturnType<typeof predBuilder<F>>) => Predicate<F>): FirstNeedsOrder<F>;
+  /**
+   * Declare the TOTAL ORDER key — the ONLY finishing method. `key` is keyof-checked
+   * against the aggregate's scalar fields (`PredScalarKeys<F>`). Returns a finished
+   * `OrderedReadDecl`. Optional `.desc()` reversal is controlled by the `desc` parameter
+   * (default `false` → ascending).
+   */
+  orderBy(key: PredScalarKeys<F>, desc?: boolean): OrderedReadDecl;
+}
+
+/**
+ * The INITIAL, un-typed `first` — its ONLY method is `.of(...)`. A `first(id)` without
+ * `.of(...)` cannot be used as a declaration.
+ */
+export interface TypelessFirst {
+  readonly id: string;
+  of<F extends Record<string, Field>>(aggregate: AggregateHandle<string, F>): FirstNeedsOrder<F>;
+}
+
+// ─── `take` type-state chain ─────────────────────────────────────────────────
+
+/**
+ * Intermediate state for `take(n)`: only `.where(...)` and `.orderBy(key)` are available.
+ * Identical to `FirstNeedsOrder` but carries `limit > 1`. The ONLY finishing method is
+ * `.orderBy(key)` → `OrderedReadDecl` with `limit = n`.
+ */
+export interface TakeNeedsOrder<F extends Record<string, Field> = Record<string, Field>> {
+  readonly id: string;
+  readonly of: string;
+  readonly limit: number;
+  /** Attach a PREDICATE: only aggregates satisfying it are candidates. Optional. */
+  where(fn: (p: ReturnType<typeof predBuilder<F>>) => Predicate<F>): TakeNeedsOrder<F>;
+  /**
+   * Declare the TOTAL ORDER key — the ONLY finishing method. Mirrors `FirstNeedsOrder`.
+   */
+  orderBy(key: PredScalarKeys<F>, desc?: boolean): OrderedReadDecl;
+}
+
+/**
+ * The INITIAL, un-typed `take` — its ONLY method is `.of(...)`. A `take(id, n)` without
+ * `.of(...)` cannot be used as a declaration.
+ */
+export interface TypelessTake {
+  readonly id: string;
+  readonly limit: number;
+  of<F extends Record<string, Field>>(aggregate: AggregateHandle<string, F>): TakeNeedsOrder<F>;
+}
+
+// ─── Internal factories ───────────────────────────────────────────────────────
+
+function makeFirstNeedsOrder<F extends Record<string, Field>>(
+  id: string,
+  ofType: string,
+  where: CanonicalPred | undefined,
+): FirstNeedsOrder<F> {
+  return {
+    id,
+    of: ofType,
+    where(fn: (p: ReturnType<typeof predBuilder<F>>) => Predicate<F>): FirstNeedsOrder<F> {
+      const pred = fn(predBuilder<F>());
+      const canonical = canonicalizePred(pred as Predicate<Record<string, Field>>);
+      return makeFirstNeedsOrder<F>(id, ofType, canonical);
+    },
+    orderBy(key: PredScalarKeys<F>, desc = false): OrderedReadDecl {
+      return {
+        id,
+        of: ofType,
+        orderKey: key as string,
+        orderDesc: desc,
+        ...(where !== undefined ? { where } : {}),
+        limit: 1,
+      };
+    },
+  };
+}
+
+function makeTakeNeedsOrder<F extends Record<string, Field>>(
+  id: string,
+  ofType: string,
+  limit: number,
+  where: CanonicalPred | undefined,
+): TakeNeedsOrder<F> {
+  return {
+    id,
+    of: ofType,
+    limit,
+    where(fn: (p: ReturnType<typeof predBuilder<F>>) => Predicate<F>): TakeNeedsOrder<F> {
+      const pred = fn(predBuilder<F>());
+      const canonical = canonicalizePred(pred as Predicate<Record<string, Field>>);
+      return makeTakeNeedsOrder<F>(id, ofType, limit, canonical);
+    },
+    orderBy(key: PredScalarKeys<F>, desc = false): OrderedReadDecl {
+      return {
+        id,
+        of: ofType,
+        orderKey: key as string,
+        orderDesc: desc,
+        ...(where !== undefined ? { where } : {}),
+        limit,
+      };
+    },
+  };
+}
+
+// ─── Public entry points ──────────────────────────────────────────────────────
+
+/**
+ * Begin a `first` declaration. Returns a `TypelessFirst`: until `.of(aggregate)` and
+ * `.orderBy(key)` are called (in order), no finished declaration exists. `first(id)` →
+ * `.of(T)` → `.orderBy(key)` is the ONLY path to a usable `OrderedReadDecl` with limit=1.
+ */
+export function first(id: string): TypelessFirst {
+  return {
+    id,
+    of<F extends Record<string, Field>>(aggregate: AggregateHandle<string, F>): FirstNeedsOrder<F> {
+      return makeFirstNeedsOrder<F>(id, aggregate.id, undefined);
+    },
+  };
+}
+
+/**
+ * Begin a `take(n)` declaration. Returns a `TypelessTake`: until `.of(aggregate)` and
+ * `.orderBy(key)` are called, no finished declaration exists. `take(id, n)` → `.of(T)` →
+ * `.orderBy(key)` is the ONLY path to a usable `OrderedReadDecl` with limit=n.
+ *
+ * `n` MUST be ≥ 1. `n = 1` is equivalent to `first` but a distinct declaration id.
+ */
+export function take(id: string, n: number): TypelessTake {
+  if (n < 1) throw new Error(`take(${id}, ${n}): n must be ≥ 1`);
+  return {
+    id,
+    limit: n,
+    of<F extends Record<string, Field>>(aggregate: AggregateHandle<string, F>): TakeNeedsOrder<F> {
+      return makeTakeNeedsOrder<F>(id, aggregate.id, n, undefined);
+    },
+  };
+}

package/src/predicate.ts

@@ -0,0 +1,203 @@
+// 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.
+
+/**
+ * Predicate algebra for maintained counts and sums (Slice 1).
+ *
+ * GRAMMAR (Slice 1 — equality + AND/OR; no join, no order-sensitive op):
+ *
+ *   pred    := clause | and(pred, …) | or(pred, …)
+ *   clause  := field<K>.eq(v) | field<K>.ne(v)
+ *   field   := a declared scalar field of the count/sum's `of`-aggregate
+ *              (string | enum | ref | int — the EAV-index-probeable kinds)
+ *   value   := a literal matching the field's declared type
+ *
+ * The predicate is a SMALL ALGEBRAIC VALUE — structurally non-SQL, non-code.
+ * A dev CANNOT type a non-deterministic or injection-bearing predicate (they
+ * cannot write a `WHERE` clause; they compose typed `.field(K).eq(v)` clauses).
+ * This satisfies:
+ *   LAW 1  — determinism by construction (no raw SQL; the predicate evaluates
+ *             over the HLC-sorted fold, never over a live query).
+ *   LAW 2  — no raw SQL in a maintained projection: the predicate folds into
+ *             the Rust diff-maintenance step, NOT into SQL text.
+ *
+ * NOTE: `field` is restricted to the count/sum's OWN aggregate's scalar fields.
+ * A joined-edge predicate (referencing a related aggregate) is explicitly OUT OF
+ * SLICE 1 — that requires cross-aggregate invalidation (not built here).
+ * The grammar §1.1 + the `ScalarKeys<F>` constraint enforce this statically: a
+ * joined-edge field is not in `F`, so `field("joinedEdgeKey")` is a compile error.
+ *
+ * ORDER-SENSITIVE GUARDRAIL: count/sum expose NO `.first`/`.take`/`.orderBy`.
+ * Any future order-sensitive primitive MUST require `.orderBy` to construct
+ * (the positive guardrail from spec §2.3). The ABSENCE of those methods here is
+ * the precondition assertion: a red test the moment Slice 2 lands `first/take`
+ * without the guard. Do NOT add a dead `.orderBy` to count/sum — that is
+ * loosening (LAW 3); assert the absence, preserve it.
+ *
+ * VALUE CANONICALISATION: all predicate `value`s are stored as `string` in the
+ * IR (following the `EqFilter.value:string` precedent in `query/compile.ts:56`).
+ * For an `int` field the string stores the decimal representation; the Rust
+ * evaluator parses it to `Value::Int(n)` for comparison. For enum/string/ref
+ * fields it is compared against `Value::Str(s)` DIRECTLY (not the serde-tagged
+ * `{"Str":s}` form — that JSON-wrap is a SQL-needle artifact for the report
+ * compiler; in-Rust fold maintenance compares `Value`s directly).
+ */
+
+import type { Field, FieldValue } from "./fields.js";
+
+// ─── scalar-field key extraction (mirrors report.ts ScalarKeys) ───────────────
+
+/**
+ * The subset of an aggregate's field-map keys whose field kind is scalar
+ * (string | enum | ref | int) — the only kinds that produce an EAV needle the
+ * maintained-count predicate can probe. set/map/json/evidence are NOT included:
+ * a predicate over a collection field is undefined/non-deterministic.
+ *
+ * `int` IS included (unlike the report.ts `ScalarKeys` which limits to
+ * string|enum|ref|json): a count/sum predicate may filter on an integer field
+ * (e.g. `priority eq 1`). The in-Rust evaluator compares `Value::Int(n)` when
+ * the field is int-kind.
+ */
+export type PredScalarKeys<F extends Record<string, Field>> = {
+  [K in keyof F]: F[K] extends Field<unknown, "string" | "enum" | "ref" | "int"> ? K : never;
+}[keyof F] &
+  string;
+
+// ─── predicate IR (the wire shape lowered into the manifest) ──────────────────
+
+/**
+ * A single equality or inequality clause.
+ *
+ * `value` is ALWAYS a `string` in the IR (canonical):
+ *   - string/enum/ref fields → compared against `Value::Str(value)` in Rust.
+ *   - int fields             → the Rust evaluator parses `value` to `i64` and
+ *                              compares against `Value::Int(n)`. Parse failures
+ *                              are a manifest-validation error, not a runtime one.
+ *
+ * ABSENT-FIELD SEMANTICS (determinism requirement — see §7-D of the contract):
+ *   `eq` over an absent field evaluates to FALSE (unset ≠ any literal).
+ *   `ne` over an absent field evaluates to TRUE  (unset ≠ any literal).
+ * This must be identical on both the OLD and NEW sides of the incremental diff
+ * (the symmetry requirement — lib.rs §3.1).
+ */
+export type PredClause<F extends Record<string, Field> = Record<string, Field>> =
+  | { readonly kind: "eq"; readonly field: PredScalarKeys<F> & string; readonly value: string }
+  | { readonly kind: "ne"; readonly field: PredScalarKeys<F> & string; readonly value: string };
+
+/**
+ * A predicate tree: a single clause, or a boolean combination of sub-predicates.
+ *
+ * Slice 1 supports `eq`/`ne` + AND/OR of clause-trees. NO nesting beyond
+ * AND/OR-of-clauses is required for the `publishedCount` proof
+ * (`status eq "approved"` is a single clause). The tree is modelled to avoid a
+ * forced 2nd pass when OR of clauses is needed.
+ *
+ * CONTRACT: AND/OR are evaluated over the count/sum's OWN aggregate's folded
+ * state ONLY — no cross-aggregate join. The `F` type parameter enforces this:
+ * every `field` key is `keyof F` for the `of`-aggregate's field map.
+ */
+export type Predicate<F extends Record<string, Field> = Record<string, Field>> =
+  | PredClause<F>
+  | { readonly kind: "and"; readonly clauses: readonly Predicate<F>[] }
+  | { readonly kind: "or"; readonly clauses: readonly Predicate<F>[] };
+
+// ─── builder surface (handed to the .where(p => …) lambda) ───────────────────
+
+/**
+ * The typed predicate builder handed to `.where(p => …)`. `F` is the field map
+ * of the count/sum's `of`-aggregate, so:
+ *   - `p.field("unknownField")` is a COMPILE error (not in `keyof F`).
+ *   - `p.field("status").eq("unknown")` is a COMPILE error when `status` is
+ *     `t.enum(["draft","submitted","approved","archived"])` and `"unknown"` is
+ *     not a member.
+ *   - `p.field("status").eq(42)` is a COMPILE error (int ≠ enum value type).
+ *
+ * This is the typed analogue of `report.ts:268-282` `WhereBuilder<F>`, but
+ * produces a MAINTAINED-COUNT `Predicate<F>` instead of the entity-graph `Filter`
+ * (which lowers to sealed SQL — a different path, not reused here).
+ */
+export interface PredBuilder<F extends Record<string, Field>> {
+  /** Pick a scalar field of the `of`-aggregate by its exact (keyof-checked) name. */
+  field<K extends PredScalarKeys<F>>(
+    key: K,
+  ): {
+    /** Equality: count/include only when this field's value equals [v]. */
+    eq(v: FieldValue<F[K]>): PredClause<F>;
+    /** Inequality: count/include only when this field's value differs from [v]. */
+    ne(v: FieldValue<F[K]>): PredClause<F>;
+  };
+  /** Logical AND of two or more sub-predicates. */
+  and(...cs: Predicate<F>[]): Predicate<F>;
+  /** Logical OR of two or more sub-predicates. */
+  or(...cs: Predicate<F>[]): Predicate<F>;
+}
+
+/** Construct a `PredBuilder` for the aggregate whose field map is `F`. */
+export function predBuilder<F extends Record<string, Field>>(): PredBuilder<F> {
+  return {
+    field<K extends PredScalarKeys<F>>(key: K) {
+      return {
+        eq: (v: FieldValue<F[K]>): PredClause<F> => ({
+          kind: "eq",
+          field: key,
+          // Canonical: store as string (int fields: decimal repr; enum/string/ref: as-is).
+          value: String(v),
+        }),
+        ne: (v: FieldValue<F[K]>): PredClause<F> => ({
+          kind: "ne",
+          field: key,
+          value: String(v),
+        }),
+      };
+    },
+    and(...cs: Predicate<F>[]): Predicate<F> {
+      return { kind: "and", clauses: cs };
+    },
+    or(...cs: Predicate<F>[]): Predicate<F> {
+      return { kind: "or", clauses: cs };
+    },
+  };
+}
+
+// ─── canonical predicate (manifest-stable serialisation) ─────────────────────
+
+/**
+ * The manifest-stable (canonical) predicate shape: clauses sorted by
+ * `(field, kind, value)`, AND/OR connectives preserved. A byte-identical
+ * predicate produces a byte-identical canonical form — the hash is stable.
+ *
+ * OMIT-WHEN-ABSENT: a count/sum with NO predicate omits `where` entirely from
+ * the canonical manifest (same discipline as the `by?` field in `CanonicalCount`).
+ * Only a COUNT/SUM WITH a predicate carries a `where` key; predicate-free counts
+ * are byte-identical to the form before `where` existed (golden hashes stable).
+ */
+export type CanonicalPred =
+  | { readonly kind: "eq"; readonly field: string; readonly value: string }
+  | { readonly kind: "ne"; readonly field: string; readonly value: string }
+  | { readonly kind: "and"; readonly clauses: readonly CanonicalPred[] }
+  | { readonly kind: "or"; readonly clauses: readonly CanonicalPred[] };
+
+/**
+ * Canonicalize a `Predicate` into a `CanonicalPred`. Clauses within AND/OR are
+ * sorted deterministically by their string serialisation so the canonical form
+ * is insertion-order–independent (identical predicate logic → identical manifest
+ * fragment → identical hash, regardless of the order clauses were composed).
+ */
+export function canonicalizePred(pred: Predicate<Record<string, Field>>): CanonicalPred {
+  if (pred.kind === "eq" || pred.kind === "ne") {
+    return { kind: pred.kind, field: pred.field, value: pred.value };
+  }
+  // AND / OR: recurse + sort children by their JSON serialisation.
+  const clauses = [...pred.clauses]
+    .map(canonicalizePred)
+    .sort((a, b) => {
+      const sa = JSON.stringify(a);
+      const sb = JSON.stringify(b);
+      return sa < sb ? -1 : sa > sb ? 1 : 0;
+    });
+  return { kind: pred.kind, clauses };
+}