@githolon/dsl 0.1.0

package/src/engine_entry.ts

@@ -0,0 +1,449 @@
+// 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 GENERIC ENGINE ENTRY — `registerEngine(config)` (#M4, the one-command compiler).
+ *
+ * Every tenant engine bundle used to HAND-COPY the same ~500 lines of machinery
+ * (`emit_engine.ts` / `emit_nomos_engine.ts`): duck-typed module scans, the
+ * `(domain, directiveId)` registry, the derived/combined/invariant registries, the
+ * five `planReport` dispatch branches, `portsFromHost`, and the `globalThis.plan`
+ * assignments. Worse, `emit_engine.ts` kept a SECOND hand-maintained module list
+ * inside its agg-invariant registry — a live drift trap (it had already drifted:
+ * the list omitted `co2_repairs`).
+ *
+ * This module IS that machinery, hoisted into `@githolon/dsl` once. A generated entry
+ * shrinks to imports + one call:
+ *
+ *     import * as guestbook from "./domains/guestbook.js";
+ *     import { registerEngine } from "@githolon/dsl/engine-entry";
+ *     registerEngine({ domains: { guestbook: [guestbook] } });
+ *
+ * EVERY registry — directives, deriveds, combineds, relation invariants, aggregate
+ * invariants — derives from the SAME `domains` map, so the drift trap is structurally
+ * gone. A domain key maps to an ORDERED module list, spread-merged later-wins (the
+ * `identity = {...identityCore, ...co2_identity}` pattern), so a tenant can compose
+ * framework + tenant modules under one dispatch key.
+ *
+ * ENGINE-BUNDLE-SAFE: this file (and everything it reaches) imports NO node builtin —
+ * it must bundle under esbuild `--platform=neutral` into the sealed QuickJS lump.
+ * The contracts mirrored here (wire shapes, vacuous-holds, strikes-conditional
+ * return) are documented at the original sites; see `emit_engine.ts` in the co2
+ * tenant package for the long-form rationale of each branch.
+ */
+import { executeDirectiveToIntent } from "./wire_encode.js";
+import type { Directive } from "./directive.js";
+import type { AggregateHandle, AggregateInvariantFn, AggregateInvariantVerdict } from "./aggregate.js";
+import type { Ports } from "./ctx.js";
+import type { WireEvent, WireHlc } from "./wire.js";
+import type { DerivedDecl } from "./derived.js";
+import type { CombinedDecl } from "./combined.js";
+import type { InvariantBody, InvariantEvidence, InvariantVerdict } from "./relation.js";
+import type { QueryRow } from "./report.js";
+
+/** One bundled domain module: a bag of named exports the entry scans by SHAPE. */
+export type DomainModuleExports = Record<string, unknown>;
+
+/** A report: declarative query + render; the host feeds rows, the engine renders. */
+export interface EngineReport {
+  render(rows: QueryRow[]): string;
+}
+
+/** The one declarative input: dispatch key → ORDERED module list (later wins). */
+export interface EngineEntryConfig {
+  /**
+   * Domain dispatch key → the modules composing it, spread-merged IN ORDER
+   * (later overrides earlier on a name collision — the `identity` union pattern).
+   */
+  readonly domains: Record<string, readonly DomainModuleExports[]>;
+  /** Optional report registry: `reportId` → a factory `(actor) => Report`. */
+  readonly reports?: Record<string, (actor: string) => EngineReport>;
+}
+
+interface RegistryEntry {
+  directive: Directive<unknown>;
+  agg: AggregateHandle;
+}
+
+/** Collect every exported `AggregateHandle` from a domain module, by wire id. */
+function aggregatesOf(mod: DomainModuleExports): Map<string, AggregateHandle> {
+  const out = new Map<string, AggregateHandle>();
+  for (const v of Object.values(mod)) {
+    if (
+      v &&
+      typeof v === "object" &&
+      (v as { __isAggregateHandle?: boolean }).__isAggregateHandle === true
+    ) {
+      const h = v as AggregateHandle;
+      out.set(h.id, h);
+    }
+  }
+  return out;
+}
+
+/** Collect every exported `Directive` from a domain module, by directive id. */
+function directivesOf(mod: DomainModuleExports): Map<string, Directive<unknown>> {
+  const out = new Map<string, Directive<unknown>>();
+  for (const v of Object.values(mod)) {
+    if (
+      v &&
+      typeof v === "object" &&
+      typeof (v as { id?: unknown }).id === "string" &&
+      typeof (v as { plan?: unknown }).plan === "function" &&
+      typeof (v as { aggregateId?: unknown }).aggregateId === "string"
+    ) {
+      const d = v as Directive<unknown>;
+      out.set(d.id, d);
+    }
+  }
+  return out;
+}
+
+/** Collect every exported `DerivedDecl` (disambiguated from combineds by the JOIN axis). */
+function derivedsOf(mod: DomainModuleExports): DerivedDecl[] {
+  const out: DerivedDecl[] = [];
+  for (const v of Object.values(mod)) {
+    if (
+      v &&
+      typeof v === "object" &&
+      typeof (v as { id?: unknown }).id === "string" &&
+      typeof (v as { of?: unknown }).of === "string" &&
+      typeof (v as { fn?: unknown }).fn === "function" &&
+      typeof (v as { refField?: unknown }).refField !== "string" &&
+      typeof (v as { reads?: unknown }).reads !== "string"
+    ) {
+      out.push(v as DerivedDecl);
+    }
+  }
+  return out;
+}
+
+/** Collect every exported `CombinedDecl` (the `refField`+`reads` JOIN axis marks it). */
+function combinedsOf(mod: DomainModuleExports): CombinedDecl[] {
+  const out: CombinedDecl[] = [];
+  for (const v of Object.values(mod)) {
+    if (
+      v &&
+      typeof v === "object" &&
+      typeof (v as { id?: unknown }).id === "string" &&
+      typeof (v as { of?: unknown }).of === "string" &&
+      typeof (v as { refField?: unknown }).refField === "string" &&
+      typeof (v as { reads?: unknown }).reads === "string" &&
+      typeof (v as { fn?: unknown }).fn === "function"
+    ) {
+      out.push(v as CombinedDecl);
+    }
+  }
+  return out;
+}
+
+/** Spread-merge a domain key's ORDERED module list (later wins on collision). */
+function mergeModules(mods: readonly DomainModuleExports[]): DomainModuleExports {
+  let merged: DomainModuleExports = {};
+  for (const m of mods) merged = { ...merged, ...m };
+  return merged;
+}
+
+/**
+ * Build a DSL `ctx` (Ports) from the host-injected `__ports` scalars. `clock()`
+ * synthesises a `WireHlc` from the scalar (the engine leg DISCARDS the produced
+ * intent's HLC — the committed HLC/id is host-injected in Rust); `id()` derives a
+ * deterministic per-dispatch value; `rng()` replays the captured draw.
+ */
+function portsFromHost(): Ports {
+  const hostPorts = (globalThis as { __ports?: { clock(): number; rng(): number } }).__ports;
+  const clockScalar = hostPorts ? hostPorts.clock() : 0;
+  const rngValue = hostPorts ? hostPorts.rng() : 0;
+  let idCounter = 0;
+  return {
+    clock(): WireHlc {
+      return { physical: clockScalar, logical: 0, replica: 0 };
+    },
+    id(): string {
+      idCounter += 1;
+      return `eng-${clockScalar}-${idCounter}`;
+    },
+    rng(): number {
+      return rngValue;
+    },
+  };
+}
+
+/** The compiled engine surface `registerEngine` returns (and assigns onto `globalThis`). */
+export interface RegisteredEngine {
+  plan(job: unknown): WireEvent[] | { events: WireEvent[]; strikes: string[] };
+  planReport(job: unknown): string;
+}
+
+/**
+ * Build ALL registries from the one `domains` map, wire the five dispatch paths, and
+ * assign `globalThis.plan` + `globalThis.planReport` (the lump is eval'd as a classic
+ * script and `globalThis` is FROZEN before dispatch — registration must happen at
+ * top-level eval, which calling this at module top level does).
+ */
+export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
+  const mergedByDomain = new Map<string, DomainModuleExports>();
+  for (const [domainName, mods] of Object.entries(config.domains)) {
+    mergedByDomain.set(domainName, mergeModules(mods));
+  }
+
+  // ── (domain, directiveId) → {directive, agg} ──────────────────────────────────
+  const REGISTRY = new Map<string, RegistryEntry>();
+  for (const [domainName, mod] of mergedByDomain) {
+    const aggs = aggregatesOf(mod);
+    const dirs = directivesOf(mod);
+    for (const [dirId, directive] of dirs) {
+      const agg = aggs.get(directive.aggregateId);
+      if (agg === undefined) {
+        // A directive targeting an aggregate not exported by its module is an
+        // authoring bug; surface it lazily (only if that directive is invoked).
+        continue;
+      }
+      REGISTRY.set(`${domainName}\u0000${dirId}`, { directive, agg });
+    }
+  }
+
+  // ── aggregate type → derived / combined decls (fn bodies ship HERE, never the ledger) ──
+  const DERIVED_REGISTRY = new Map<string, DerivedDecl[]>();
+  const COMBINED_REGISTRY = new Map<string, CombinedDecl[]>();
+  for (const mod of mergedByDomain.values()) {
+    for (const d of derivedsOf(mod)) {
+      const list = DERIVED_REGISTRY.get(d.of) ?? [];
+      list.push(d);
+      DERIVED_REGISTRY.set(d.of, list);
+    }
+    for (const c of combinedsOf(mod)) {
+      const list = COMBINED_REGISTRY.get(c.of) ?? [];
+      list.push(c);
+      COMBINED_REGISTRY.set(c.of, list);
+    }
+  }
+
+  // ── relation id → cross-workspace invariant body (off the directives' declaredRelations) ──
+  const INVARIANT_REGISTRY = new Map<string, InvariantBody>();
+  for (const { directive } of REGISTRY.values()) {
+    const relations = (directive as { declaredRelations?: unknown }).declaredRelations;
+    if (!Array.isArray(relations)) continue;
+    for (const rel of relations) {
+      const r = rel as { id?: unknown; hasInvariant?: unknown; invariant?: unknown };
+      if (typeof r.id !== "string" || r.hasInvariant !== true) continue;
+      if (typeof r.invariant !== "function") {
+        // A relation declaring `hasInvariant` MUST ship an executable body — fail-closed.
+        throw new Error(
+          `engine bundle: relation "${r.id}" declares hasInvariant but ships no executable ` +
+            `invariant body — the gate would have nothing to evaluate (cross_workspace.md §2.1).`,
+        );
+      }
+      INVARIANT_REGISTRY.set(r.id, r.invariant as InvariantBody);
+    }
+  }
+
+  // ── aggregate type → aggregate-invariant body — from the SAME map (no second list) ──
+  const AGG_INVARIANT_REGISTRY = new Map<string, AggregateInvariantFn>();
+  for (const mod of mergedByDomain.values()) {
+    for (const v of Object.values(mod)) {
+      if (
+        v &&
+        typeof v === "object" &&
+        (v as { __isAggregateHandle?: boolean }).__isAggregateHandle === true &&
+        (v as { hasInvariant?: boolean }).hasInvariant === true
+      ) {
+        const h = v as AggregateHandle & { invariant?: AggregateInvariantFn };
+        if (typeof h.invariant !== "function") {
+          // A handle declaring `hasInvariant` MUST ship an executable body — fail-closed.
+          throw new Error(
+            `engine bundle: aggregate "${h.id}" declares hasInvariant but ships no executable ` +
+              `invariant body — the gate would have nothing to evaluate (#250).`,
+          );
+        }
+        AGG_INVARIANT_REGISTRY.set(h.id, h.invariant);
+      }
+    }
+  }
+
+  const REPORTS: Record<string, (actor: string) => EngineReport> = config.reports ?? {};
+
+  // ── the five planReport dispatch branches (wire shapes are the host oracle's contract) ──
+
+  function planInvariant(job: {
+    intent?: { invariant?: { relation?: string }; evidence?: InvariantEvidence };
+  }): string {
+    const relationId = job.intent?.invariant?.relation;
+    if (typeof relationId !== "string") {
+      throw new Error(
+        `engine invariant: job.intent.invariant must carry {relation}; got ${JSON.stringify(job.intent)}`,
+      );
+    }
+    const body = INVARIANT_REGISTRY.get(relationId);
+    if (body === undefined) {
+      throw new Error(`engine invariant: no invariant registered for relation "${relationId}"`);
+    }
+    const evidence = job.intent?.evidence;
+    if (evidence === undefined || typeof evidence !== "object") {
+      throw new Error(
+        `engine invariant: job.intent must carry {evidence}; got ${JSON.stringify(job.intent)}`,
+      );
+    }
+    const verdict: InvariantVerdict = body(evidence);
+    return JSON.stringify(verdict);
+  }
+
+  function planAggInvariant(job: {
+    intent?: { aggregateInvariant?: { of?: string } };
+    priorState?: Record<string, unknown>;
+  }): string {
+    // WIRE SHAPE (the host oracle's contract, EXACT): `{ aggregateInvariant: { of: "<type>" } }`.
+    const aggregateType = job.intent?.aggregateInvariant?.of;
+    if (typeof aggregateType !== "string") {
+      throw new Error(
+        `engine aggregateInvariant: job.intent.aggregateInvariant must carry {of}; got ${JSON.stringify(job.intent)}`,
+      );
+    }
+    const body = AGG_INVARIANT_REGISTRY.get(aggregateType);
+    // VACUOUS HOLDS: a type with NO declared invariant trivially holds — `{accept:true}`,
+    // NOT a throw (the oracle fails CLOSED on a throw, wrongly rejecting every create).
+    if (body === undefined) {
+      return JSON.stringify({ accept: true } satisfies AggregateInvariantVerdict);
+    }
+    const snapshot = (job.priorState ?? {}) as Record<string, unknown>;
+    const verdict: AggregateInvariantVerdict = body(snapshot);
+    return JSON.stringify(verdict);
+  }
+
+  function planDerive(job: {
+    intent?: { derive?: { of?: string } };
+    priorState?: Record<string, unknown>;
+  }): string {
+    const ofType = job.intent?.derive?.of;
+    if (typeof ofType !== "string") {
+      throw new Error(
+        `engine derive: job.intent.derive must carry {of}; got ${JSON.stringify(job.intent)}`,
+      );
+    }
+    const fields = DERIVED_REGISTRY.get(ofType) ?? [];
+    const prior = (job.priorState ?? {}) as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const d of fields) {
+      const value = d.fn(prior);
+      out[d.id] = value === undefined ? null : value;
+    }
+    return JSON.stringify(out);
+  }
+
+  function planCombine(job: {
+    intent?: { combine?: { of?: string } };
+    priorState?: Record<string, unknown>;
+    queryRows?: Record<string, Record<string, unknown> | null> | (Record<string, unknown> | null)[];
+  }): string {
+    const ofType = job.intent?.combine?.of;
+    if (typeof ofType !== "string") {
+      throw new Error(
+        `engine combine: job.intent.combine must carry {of}; got ${JSON.stringify(job.intent)}`,
+      );
+    }
+    const fields = COMBINED_REGISTRY.get(ofType) ?? [];
+    const owner = (job.priorState ?? {}) as Record<string, unknown>;
+    // Preferred: related rows keyed by combined field id (iteration-order independent);
+    // the array path remains for older callers (declaration order).
+    const relatedById =
+      job.queryRows !== undefined && !Array.isArray(job.queryRows) ? job.queryRows : undefined;
+    const relatedArray = Array.isArray(job.queryRows) ? job.queryRows : [];
+    const out: Record<string, unknown> = {};
+    for (let i = 0; i < fields.length; i += 1) {
+      const c = fields[i]!;
+      const row = relatedById !== undefined ? relatedById[c.id] : relatedArray[i];
+      const value = c.fn(owner, row == null ? undefined : (row as Record<string, unknown>));
+      out[c.id] = value === undefined ? null : value;
+    }
+    return JSON.stringify(out);
+  }
+
+  function planReport(job: {
+    intent?: {
+      report?: string;
+      actor?: string;
+      derive?: { of?: string };
+      combine?: { of?: string };
+      invariant?: { relation?: string };
+      aggregateInvariant?: { of?: string };
+      evidence?: InvariantEvidence;
+    };
+    queryRows?: unknown[];
+    priorState?: Record<string, unknown>;
+  }): string {
+    // Branch order mirrors emit_engine.ts: aggregateInvariant → invariant → derive →
+    // combine → report (the gate's most recent dispatch key wins over older fan-outs).
+    if (job.intent?.aggregateInvariant !== undefined) {
+      return planAggInvariant(
+        job as { intent?: { aggregateInvariant?: { of?: string } }; priorState?: Record<string, unknown> },
+      );
+    }
+    if (job.intent?.invariant !== undefined) {
+      return planInvariant(
+        job as { intent?: { invariant?: { relation?: string }; evidence?: InvariantEvidence } },
+      );
+    }
+    if (job.intent?.derive !== undefined) {
+      return planDerive(
+        job as { intent?: { derive?: { of?: string } }; priorState?: Record<string, unknown> },
+      );
+    }
+    if (job.intent?.combine !== undefined) {
+      return planCombine(
+        job as unknown as {
+          intent?: { combine?: { of?: string } };
+          priorState?: Record<string, unknown>;
+          queryRows?:
+            | Record<string, Record<string, unknown> | null>
+            | (Record<string, unknown> | null)[];
+        },
+      );
+    }
+    const reportId = job.intent?.report;
+    const actor = job.intent?.actor;
+    if (typeof reportId !== "string" || typeof actor !== "string") {
+      throw new Error(
+        `engine report: job.intent must carry {report, actor}; got ${JSON.stringify(job.intent)}`,
+      );
+    }
+    const factory = REPORTS[reportId];
+    if (factory === undefined) {
+      throw new Error(`engine report: no report registered for "${reportId}"`);
+    }
+    const rows = (Array.isArray(job.queryRows) ? job.queryRows : []) as QueryRow[];
+    return factory(actor).render(rows);
+  }
+
+  function plan(job: {
+    intent?: { domain?: string; directiveId?: string; payload?: unknown };
+  }): WireEvent[] | { events: WireEvent[]; strikes: string[] } {
+    const intent = job.intent ?? {};
+    const domain = intent.domain;
+    const directiveId = intent.directiveId;
+    if (typeof domain !== "string" || typeof directiveId !== "string") {
+      throw new Error(
+        `engine plan: job.intent must carry {domain, directiveId}; got ${JSON.stringify(intent)}`,
+      );
+    }
+    const entry = REGISTRY.get(`${domain}\u0000${directiveId}`);
+    if (entry === undefined) {
+      throw new Error(`engine plan: no directive registered for (${domain}, ${directiveId})`);
+    }
+    const ctx = portsFromHost();
+    const wire = executeDirectiveToIntent(entry.directive, entry.agg, intent.payload as never, ctx);
+    // Emit {events, strikes} ONLY when a strike is present, else the bare event array —
+    // so every strikes-free directive canonicalizes byte-identically to the pre-strikeout contract.
+    return wire.strikes.length ? { events: wire.events, strikes: wire.strikes } : wire.events;
+  }
+
+  // The engine evals the bundle as a classic script and FREEZES globalThis before
+  // dispatch — assign both entries NOW, at top-level eval.
+  (globalThis as { plan?: unknown }).plan = plan;
+  (globalThis as { planReport?: unknown }).planReport = planReport;
+
+  return { plan, planReport } as RegisteredEngine;
+}

package/src/exists.ts

@@ -0,0 +1,170 @@
+// 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.
+
+/**
+ * `exists(id)` builder — a BOOLEAN PREDICATED MEMBERSHIP test over the `counts` table.
+ *
+ * `exists` is NOT a new maintained table — it is a TYPED READ over the SLICE-1 `counts`
+ * table (spec §3 line 47; §6 line 71). An `exists` declaration IS a count declaration
+ * in the IR: it serializes into the `counts` array in the manifest, and the read engine
+ * maintains it in the `counts` table as an ordinary count. The ONLY difference is in the
+ * GENERATED ACCESSOR: it returns `bool` = `count(id, gk) > 0`, not `int`.
+ *
+ * ZERO new Rust spec type, ZERO new table, ZERO new maintenance. This is the STRONGEST
+ * REUSE possible: `exists` cannot diverge from `count` (LAW 4 — one engine; LAW 3 —
+ * harden, not loosen: strengthens the existing count, adds nothing parallel).
+ *
+ * CORRECTNESS: `exists` resolved over `counts` (not `sums`) is correct precisely because
+ * `counts` increments membership ±1 and PRUNES ONLY AT n=0 (`lib.rs:1034`, `1141`) —
+ * `count > 0` is an exact "at least one member" test. `sums` cannot back `exists` (a
+ * genuine zero-sum group is indistinguishable from absence — `manifest.rs:274-276`).
+ *
+ * ORDER-SENSITIVE GUARDRAIL: exists exposes NO `.first`/`.take`/`.orderBy`. Membership
+ * is order-INDEPENDENT (whether any member matches is a set property). Assert the
+ * absence; do NOT add dead methods (LAW 3).
+ *
+ * EMPTY-GROUP SEMANTICS: `exists` returns `false` when the group is absent from the
+ * `counts` table (sparse pruning: count=0 rows are deleted, `lib.rs:1141`), and `true`
+ * when count ≥ 1. There is NO ambiguity with a zero-sum group (this uses `counts`, not
+ * `sums`). This is the CORRECT, HARD contract (LAW 3).
+ */
+import type { AggregateHandle } from "./aggregate.js";
+import type { Field } from "./fields.js";
+import { finishCount, type CountDecl, type AnyCount } from "./count.js";
+import { type Predicate, type CanonicalPred, predBuilder, canonicalizePred } from "./predicate.js";
+
+// ─── DSL shape ───────────────────────────────────────────────────────────────
+
+/**
+ * An `ExistsDecl` is a `CountDecl` carrying a marker that tells the codegen to emit a
+ * `bool` accessor (via `count > 0`) rather than an `int` accessor. The Rust read engine
+ * sees it as an ordinary `CountDecl` — the marker lives ONLY in the DSL/codegen layer.
+ */
+export interface ExistsDecl extends CountDecl {
+  /** Marker: tells the codegen to emit a `bool` accessor, NOT an `int` one. */
+  readonly _existsMarker: true;
+}
+
+/**
+ * The `ExistsBuilder` builder: carries `id` + `of` (grand-total usable) plus `.where(...)`
+ * and `.by(...)` methods. Mirrors `Count<F>` but the finished form is an `ExistsDecl`
+ * (which is a `CountDecl`). F is the `of`-aggregate's field map.
+ */
+export interface ExistsBuilder<F extends Record<string, Field> = Record<string, Field>> {
+  readonly id: string;
+  readonly of: string;
+  /** Attach a PREDICATE: only aggregates satisfying it count toward existence. */
+  where(fn: (p: ReturnType<typeof predBuilder<F>>) => Predicate<F>): ExistsBuilder<F>;
+  /** Partition by a GROUP-BY field: exists per distinct group-key value. */
+  by(field: string): ExistsDecl;
+}
+
+/**
+ * The INITIAL, un-typed exists — its ONLY method is `.of(...)`. A `exists(id)` without
+ * `.of(...)` cannot be used as a declaration: the aggregate type is not optional. Same
+ * un-constructible-without-of pattern as `count(id)` (`count.ts:104-120`).
+ */
+export interface TypelessExists {
+  readonly id: string;
+  of<F extends Record<string, Field>>(aggregate: AggregateHandle<string, F>): ExistsBuilder<F>;
+}
+
+/**
+ * Either form a domain may declare in `DomainModule.exists_`. A bare `ExistsBuilder`
+ * (grand-total) or a grouped `ExistsDecl`. Both satisfy `AnyExists`.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyExists = ExistsDecl | ExistsBuilder<any>;
+
+/** Narrow: an `ExistsBuilder` exposes a `by` METHOD; an `ExistsDecl` does not. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isExistsBuilder(e: AnyExists): e is ExistsBuilder<any> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return typeof (e as ExistsBuilder<any>).by === "function";
+}
+
+/**
+ * Normalize an `AnyExists` to a finished `ExistsDecl`. The grand-total builder
+ * becomes `{id, of, _existsMarker: true}` (no `by`); a grouped `.by(field)` result is
+ * already an `ExistsDecl` and passes through. Transfers the `_where` canonical predicate
+ * when present. The returned `ExistsDecl` is ALSO a `CountDecl` and is appended into
+ * the `counts` array in the manifest — the Rust engine sees no difference.
+ */
+export function finishExists(e: AnyExists): ExistsDecl {
+  if (isExistsBuilder(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,
+      of: b.of,
+      ...(w !== undefined ? { where: w } : {}),
+      _existsMarker: true,
+    };
+  }
+  return e;
+}
+
+/**
+ * Normalize an `AnyExists` to a `CountDecl` for manifest serialization. The `_existsMarker`
+ * is EXPLICITLY STRIPPED — the Rust read engine sees an ordinary count. Use `finishExists`
+ * for codegen (where the marker drives the bool vs int accessor shape); use this for
+ * manifest emit. The stripping is a destructuring reconstruction, NOT a cast, to ensure
+ * no extra keys bleed into the IR.
+ */
+export function existsAsCount(e: AnyExists): CountDecl {
+  const decl = finishExists(e);
+  // Explicitly reconstruct as a clean CountDecl (no _existsMarker, no extra keys).
+  return {
+    id: decl.id,
+    of: decl.of,
+    ...(decl.where !== undefined ? { where: decl.where } : {}),
+    ...(decl.by !== undefined ? { by: decl.by } : {}),
+  };
+}
+
+/** Internal factory so `.where(...)` can return a new ExistsBuilder without duplicating impl. */
+function makeExistsBuilder<F extends Record<string, Field>>(
+  id: string,
+  ofType: string,
+  where: CanonicalPred | undefined,
+): ExistsBuilder<F> {
+  const b = {
+    id,
+    of: ofType,
+    ...(where !== undefined ? { _where: where } : {}),
+    where(fn: (p: ReturnType<typeof predBuilder<F>>) => Predicate<F>): ExistsBuilder<F> {
+      const pred = fn(predBuilder<F>());
+      const canonical = canonicalizePred(pred as Predicate<Record<string, Field>>);
+      return makeExistsBuilder<F>(id, ofType, canonical);
+    },
+    by(field: string): ExistsDecl {
+      return {
+        id,
+        of: ofType,
+        ...(where !== undefined ? { where } : {}),
+        by: field,
+        _existsMarker: true,
+      };
+    },
+  } as unknown as ExistsBuilder<F>;
+  return b;
+}
+
+/**
+ * Begin an exists declaration. `id` is the exists' canonical name (e.g.
+ * `"hasPublished"`). Returns a `TypelessExists`: until `.of(aggregate)` is called, the
+ * aggregate type is unknown and no usable declaration exists.
+ */
+export function exists(id: string): TypelessExists {
+  return {
+    id,
+    of<F extends Record<string, Field>>(aggregate: AggregateHandle<string, F>): ExistsBuilder<F> {
+      return makeExistsBuilder<F>(id, aggregate.id, undefined);
+    },
+  };
+}