@classytic/repo-core 0.3.0 → 0.4.0

package/dist/repository/types.d.mts

@@ -1,7 +1,8 @@
 import { Filter } from "../filter/types.mjs";
 import { OffsetPaginationResult } from "../pagination/types.mjs";
-import { LookupPopulateOptions, LookupPopulateResult } from "../lookup/types.mjs";
+import { LookupPopulateOptions, LookupPopulateResult, LookupSpec } from "../lookup/types.mjs";
 import { UpdateInput } from "../update/types.mjs";
+import { CacheOptions } from "../cache/options.mjs";
 
 //#region src/repository/types.d.ts
 /**
@@ -82,9 +83,173 @@ interface FindOneAndUpdateOptions extends QueryOptions {
   /** Insert when no doc matches. Default: false. */
   upsert?: boolean;
 }
-/** Result of a single delete — matches mongokit's shape. */
+/**
+ * Transition spec for `StandardRepo.claim()` — a CAS state change.
+ *
+ * Most state machines key off a `status` field (the default), so the
+ * common shape is just `{ from, to }`. Use the `field` key when the
+ * state lives on a different column (`phase`, `state`, `step`, etc.).
+ *
+ * For state machines whose "ready to claim" predicate isn't expressible
+ * by the state field alone — paused guards, retry-time guards,
+ * heartbeat-staleness, sub-document `$elemMatch` predicates — see the
+ * `where` field below.
+ *
+ * **Cross-package stability contract.** This shape is the canonical
+ * source of truth that mongokit's `Repository.claim`, sqlitekit's
+ * `claim`, and primitives' `ClaimableRepo<TDoc>` (in
+ * `@classytic/primitives/state-machine`) ALL conform to. Primitives
+ * stays dep-free by mirroring this shape structurally with
+ * `Record<string, unknown>` for the options slot — kits implement it
+ * with their own option-bag refinements (mongokit's `SessionOptions
+ * & { idField?, upsert? }`, sqlitekit's analogous shape) which remain
+ * structurally compatible.
+ *
+ * Editors: changing field names, removing slots, or narrowing
+ * existing parameter types here is a contract-level break. Adding
+ * new optional fields is additive — fine. The conformance test in
+ * mongokit's `tests/unit/standard-repo-assignment.test-d.ts`
+ * (wired into `prepublishOnly`) catches drift at the kit boundary.
+ */
+interface ClaimTransition {
+  /**
+   * Document field carrying the state. Defaults to `'status'` —
+   * matches the convention across `streamline`, `@classytic/order`,
+   * `revenue`, and `invoice` packages.
+   */
+  field?: string;
+  /**
+   * Required current value of the state field for the CAS to match.
+   *
+   * **Single value or array.** Pass a literal (`from: 'pending'`) for a
+   * single-source transition, or an array (`from: ['pending',
+   * 'approved']`) when the transition is legal from multiple states —
+   * compiles to `[field]: { $in: [...] }` on mongokit and
+   * `[field] IN (?, ?, ...)` on SQL kits. Real-world frequency:
+   * commission has 4 sites (`voidRecord`, `markClawedBack`,
+   * `endAgreement`, `_transition`) keyed off multi-source transitions;
+   * media-kit's error path catches failures from either `pending` or
+   * `processing`. Without array support these sites fall back to raw
+   * `findOneAndUpdate` and lose the ergonomic + plugin-routed claim
+   * benefits.
+   *
+   * **`from === to` is allowed** — idempotent re-claim with a payload
+   * write is a valid pattern (yard's `reviseDeparture` writes
+   * `departed → departed` to update fields atomically while asserting
+   * the row hasn't moved on). The CAS still returns `null` if the row
+   * left the source state, so race-loss semantics hold.
+   *
+   * **Upsert + array from:** when `upsert: true` is set on the call
+   * options and `from` is an array, mongo / SQL kits skip the literal-
+   * value insert behavior for that field — only a literal `from`
+   * value lands on the inserted row. Use a literal `from` if you need
+   * the inserted row to carry that source-state value (rare).
+   */
+  from: unknown | readonly unknown[];
+  /**
+   * Target value written to the state field on success. Always a
+   * literal — claim writes one target value per call.
+   */
+  to: unknown;
+  /**
+   * Additional filter predicates AND-merged into the CAS query
+   * alongside `{ [idField]: id, [field]: from }`. Use for guards
+   * the state field alone can't express. NOTE: this is the same
+   * `where` slot supported on `ClaimVersionTransition`.
+   *
+   *   - `{ paused: { $ne: true } }` — skip paused docs
+   *   - `{ retryAfter: { $lte: now } }` — only fire when the timer
+   *     elapsed
+   *   - `{ $or: [{ lastHeartbeat: { $lt: stale } }, ...] }` —
+   *     heartbeat-staleness, multi-condition match
+   *   - `{ steps: { $elemMatch: { status: 'pending' } } }` —
+   *     sub-document predicates
+   *
+   * Real-world data: of streamline's 21 atomic-claim sites, only 1
+   * fits the bare `{ [idField]: id, [field]: from }` shape; the
+   * other 20 carry compound predicates of exactly this shape. Same
+   * pattern across `revenue`, `order`, `invoice`. Without this field,
+   * `claim` covers the textbook example but misses every real-world
+   * state machine in the ecosystem.
+   *
+   * Null-on-race semantics unchanged: if no doc matches the full
+   * compound filter (state field OR any `where` predicate), `claim`
+   * returns `null`. The caller can't distinguish "lost race" from
+   * "guard predicate failed" — both mean "don't proceed."
+   *
+   * Cross-kit notes:
+   *   - Mongokit: ANDed into the `findOneAndUpdate` filter.
+   *   - SQL kits: ANDed into the `WHERE` clause (raw column literals
+   *     accepted; portable Filter IR is compiled).
+   *   - Prismakit: merged as additional keys on the `where` object.
+   */
+  where?: Record<string, unknown>;
+}
+/**
+ * Transition spec for `StandardRepo.claimVersion()` — optimistic-
+ * concurrency CAS via a version stamp. Sibling to `ClaimTransition`;
+ * different mental model:
+ *
+ *   - `claim` is a state machine: "move from status A to status B,
+ *     atomically".
+ *   - `claimVersion` is optimistic locking: "I expect version N; if
+ *     it still is, apply this update and bump the version".
+ *
+ * The CAS round-trip:
+ *
+ * ```ts
+ * findOneAndUpdate(
+ *   { _id, [versionField]: from, ...where },          // CAS match
+ *   { ...update, $inc: { [versionField]: by ?? 1 } }, // bump on success
+ * );
+ * ```
+ *
+ * Returns `null` when the row is missing, the version doesn't match
+ * (race-loss), or any `where` predicate fails. Same null-on-race
+ * semantics as `claim`.
+ */
+interface ClaimVersionTransition {
+  /**
+   * Field carrying the version stamp. Defaults to `'version'` —
+   * matches the convention across `@classytic/order`, `leave`,
+   * `payrun`.
+   */
+  field?: string;
+  /**
+   * Required current value of the version field for the CAS to
+   * match. **`undefined` is admitted** for first-write CAS — matches
+   * docs whose version field is missing OR null. Lean reads return
+   * `version: number | undefined` because field defaults are absent
+   * on fresh-from-DB POJOs; tolerating `undefined` removes the
+   * `?? 0` ceremony at every call site. The implementation
+   * initializes via `$set` on the first-write path (since `$inc`
+   * can't apply to a null-valued field on mongo).
+   */
+  from: number | undefined;
+  /**
+   * Increment step. Defaults to `1`. Use `by: -1` for unusual
+   * decrement-on-CAS patterns; not common.
+   */
+  by?: number;
+  /**
+   * Additional filter predicates AND-merged into the CAS query
+   * alongside `{ [idField]: id, [versionField]: from }`. Same
+   * compound-CAS semantic as `ClaimTransition.where` — paused
+   * guards, status guards (yard's `{ _id, status, version }`
+   * pattern), sub-document `$elemMatch`. Without this, callers had
+   * to fall back to raw `findOneAndUpdate` for state+version CAS.
+   */
+  where?: Record<string, unknown>;
+}
+/**
+ * Result of a single delete — what the kit returns AND what the wire
+ * emits (data and wire shapes are identical, like the pagination types).
+ *
+ * Miss handling is `null` (matches `update()`, `Map.get`, `Array.find`
+ * conventions) — kits return `Promise<DeleteResult | null>`. Callers
+ * check `if (!result)` for "nothing was deleted".
+ */
 interface DeleteResult {
-  success: boolean;
   message: string;
   /** Primary key of the removed doc (string form). */
   id?: string;
@@ -93,6 +258,16 @@ interface DeleteResult {
   /** For batch-variant implementations that surface the count inline. */
   count?: number;
 }
+/**
+ * Result of a bulk create — what kits return from `createMany()` AND
+ * what the wire emits. `data` is the inserted docs (kits may omit when
+ * caller passed `returnDocs: false`); `count` is the number successfully
+ * inserted.
+ */
+interface BulkCreateResult<T = unknown> {
+  data?: T[];
+  count?: number;
+}
 /** Result of a batch delete. */
 interface DeleteManyResult {
   acknowledged?: boolean;
@@ -186,83 +361,627 @@ interface BulkWriteResult {
  * Kit compilers normalize unknown ops to a runtime error — keep the set
  * tight so aggregations compile identically everywhere.
  */
+/**
+ * Optional per-measure predicate. When set, the measure aggregates
+ * ONLY over rows matching the predicate within each group — semantic
+ * equivalent of SQL's `SUM(amount) FILTER (WHERE status = 'paid')`
+ * and Mongo's `{ $sum: { $cond: [<expr>, '$amount', 0] } }`.
+ *
+ * Lets one query compute `paid_revenue` + `total_revenue` +
+ * `refund_count` side-by-side, instead of running N pre-filtered
+ * pipelines and stitching the rows together at the call site. The
+ * #1 dashboard-query lever; cuts query count + DB load proportional
+ * to the number of distinct slices in a typical KPI tile group.
+ *
+ * Accepts the same `FilterInput` shape every other slot does (Filter
+ * IR or plain record). References BASE columns + joined-alias paths
+ * (when `lookups` are configured), same as the top-level `filter`.
+ *
+ * Does NOT replace the top-level `AggRequest.filter` — that narrows
+ * the rows feeding into ALL measures; per-measure `where` narrows
+ * within the group AFTER the top-level filter has already applied.
+ *
+ * @example
+ * ```ts
+ * await orders.aggregate({
+ *   groupBy: 'category',
+ *   measures: {
+ *     totalRevenue: { op: 'sum', field: 'amount' },
+ *     paidRevenue:  { op: 'sum', field: 'amount', where: eq('status', 'paid') },
+ *     refundCount:  { op: 'count', where: eq('status', 'refunded') },
+ *   },
+ * });
+ * ```
+ */
 type AggMeasure = {
   op: 'count';
   field?: string;
+  where?: FilterInput;
 } | {
   op: 'countDistinct';
   field: string;
+  where?: FilterInput;
 } | {
   op: 'sum';
   field: string;
+  where?: FilterInput;
 } | {
   op: 'avg';
   field: string;
+  where?: FilterInput;
 } | {
   op: 'min';
   field: string;
+  where?: FilterInput;
 } | {
   op: 'max';
   field: string;
+  where?: FilterInput;
+} | {
+  /**
+   * Continuous percentile — interpolates between adjacent values
+   * when the requested rank falls between two rows. Equivalent to
+   * SQL's `PERCENTILE_CONT(p) WITHIN GROUP (ORDER BY field)` and
+   * Mongo's `$percentile` with `method: 'approximate'` (Mongo 7+).
+   *
+   * `p` is the percentile in `[0, 1]` (e.g. `0.5` for median,
+   * `0.95` for P95 latency).
+   *
+   * **Kit support is asymmetric.** Mongokit (≥3.13) maps to
+   * `$percentile`; sqlitekit throws `UnsupportedOperationError`
+   * (SQLite has no native percentile function and emulating via
+   * window functions is approximate + slow). Hosts targeting
+   * percentile dashboards pin to a backend that supports it
+   * (mongokit, future pgkit's `PERCENTILE_CONT`).
+   */
+  op: 'percentile';
+  field: string;
+  p: number;
+  where?: FilterInput;
+} | {
+  /**
+   * Sample standard deviation — `sqrt(variance / (n - 1))`.
+   * Equivalent to SQL's `STDDEV_SAMP()` and Mongo's
+   * `$stdDevSamp`. Use `'stddevPop'` for population stddev
+   * (`/ n` instead of `/ (n - 1)`); pick `'stddev'` (sample) by
+   * default — that's what every BI tool reports without
+   * qualification, and matches `numpy.std(ddof=1)`.
+   *
+   * **Kit support is asymmetric.** Mongokit uses native
+   * `$stdDevSamp` (numerically stable Welford algorithm).
+   * Sqlitekit throws `UnsupportedOperationError` — SQLite ships
+   * no native `STDDEV` aggregate and emulating via the
+   * computational formula `sqrt(sum(x²) - sum(x)²/n / (n-1))`
+   * is numerically unstable for typical dashboard data
+   * (catastrophic cancellation when values are near-equal). Hosts
+   * needing stddev dashboards pin to mongokit or future pgkit.
+   */
+  op: 'stddev';
+  field: string;
+  where?: FilterInput;
+} | {
+  /** Population standard deviation (`/ n`). See `'stddev'` for
+   * the sample variant + per-kit support matrix (identical). */
+  op: 'stddevPop';
+  field: string;
+  where?: FilterInput;
 };
 /**
- * Portable aggregation request. Compiles to SQL (`SELECT ... WHERE ...
- * GROUP BY ... HAVING ... ORDER BY ... LIMIT ... OFFSET`) on sqlitekit /
- * pgkit and to a `[$match, $group, $match, $sort, $limit, $skip]`
- * pipeline on mongokit. Output shape is identical either way: one row
- * per group, keyed by `groupBy` fields + measure aliases.
+ * Tie-breaking strategy for `AggTopN.ties`. Mirrors the three SQL
+ * window-rank functions; mongokit maps the same names to
+ * `$rank` / `$denseRank` / `$documentNumber`.
+ *
+ *   - `'rank'`        — `RANK()`. Ties share a rank; gaps after.
+ *                        e.g. `[100, 100, 80] → ranks 1, 1, 3`.
+ *   - `'dense_rank'`  — `DENSE_RANK()`. Ties share a rank; no gaps.
+ *                        e.g. `[100, 100, 80] → ranks 1, 1, 2`.
+ *   - `'row_number'`  — `ROW_NUMBER()`. Each row gets a unique rank
+ *                        regardless of ties; tie-broken arbitrarily.
+ *                        e.g. `[100, 100, 80] → ranks 1, 2, 3`.
+ *
+ * Default: `'rank'`. Choose `'row_number'` when you need EXACTLY N
+ * rows per partition with no chance of overshoot from ties.
+ */
+type AggTopNTies = 'rank' | 'dense_rank' | 'row_number';
+/**
+ * Top-N-per-group spec — keep only the top `limit` rows per
+ * partition, ranked by `sortBy`. The classic "top 3 products per
+ * category" / "top 5 customers per region" dashboard primitive.
+ *
+ * **Semantics.** Each unique combination of `partitionBy` columns
+ * forms a partition. Within each partition, rows are ranked by
+ * `sortBy` (descending by default — typical "top N" intent). The
+ * top `limit` rows from each partition land in the result; the rest
+ * are dropped.
+ *
+ * **Compile target.**
+ *
+ *   - **Mongokit** — `$setWindowFields` + `$match: { rank: { $lte: limit } }`.
+ *     Mongo 5+. The window stage runs AFTER `$group` / `$project`,
+ *     so `partitionBy` and `sortBy` may reference both group keys
+ *     and measure aliases.
+ *   - **Sqlitekit** — `RANK() / DENSE_RANK() / ROW_NUMBER() OVER
+ *     (PARTITION BY ... ORDER BY ...)` wrapped in a subquery, with
+ *     a `WHERE rank <= limit` outer filter. SQLite ≥3.25 (Sept 2018).
+ *
+ * **Cross-kit shape contract.** The output row shape doesn't change
+ * — top-N just drops rows that didn't make the cut. Internal rank
+ * column is stripped before the row reaches the caller.
+ *
+ * @example "Top 3 products per category by revenue"
+ * ```ts
+ * await orders.aggregate({
+ *   groupBy: ['category', 'product'],
+ *   measures: { revenue: { op: 'sum', field: 'amount' } },
+ *   topN: {
+ *     partitionBy: 'category',
+ *     sortBy: { revenue: -1 },
+ *     limit: 3,
+ *   },
+ *   sort: { category: 1, revenue: -1 },
+ * });
+ * ```
+ *
+ * @example "Top 1 highest spender per region per month"
+ * ```ts
+ * await orders.aggregate({
+ *   dateBuckets: { month: { field: 'createdAt', interval: 'month' } },
+ *   groupBy: ['region', 'customerId'],
+ *   measures: { spent: { op: 'sum', field: 'amount' } },
+ *   topN: {
+ *     partitionBy: ['region', 'month'],
+ *     sortBy: { spent: -1 },
+ *     limit: 1,
+ *     ties: 'row_number',  // exactly one winner per partition
+ *   },
+ * });
+ * ```
+ */
+interface AggTopN {
+  /**
+   * Group columns or `dateBuckets` aliases that define each partition.
+   * Must be a subset of `groupBy` + `dateBuckets` keys — kits validate
+   * at compile time and throw on a mismatch.
+   *
+   * Pass a single string for a one-column partition; an array for
+   * compound partitions.
+   */
+  partitionBy: string | readonly string[];
+  /**
+   * Ranking sort within each partition. Keys are measure aliases,
+   * `groupBy` columns, or `dateBuckets` aliases — the same surface
+   * as the top-level `sort`. Defaults to descending intent (top N
+   * by revenue → `{ revenue: -1 }`).
+   */
+  sortBy: Record<string, 1 | -1>;
+  /** Max rows to keep per partition. Must be a positive integer. */
+  limit: number;
+  /**
+   * Tie-breaking strategy. Default `'rank'`. See `AggTopNTies` for
+   * the three options.
+   */
+  ties?: AggTopNTies;
+}
+/**
+ * Per-request cache options for `aggregate()` / `aggregatePaginate()`.
+ *
+ * **Unified with the canonical `CacheOptions`** at `@classytic/repo-core/cache`.
+ * Same shape across CRUD, aggregate, and every kit — TanStack Query-
+ * inspired `staleTime` / `gcTime` model, `swr` flag, `tags` for group
+ * invalidation, `bypass` for refresh buttons, `enabled` for opt-out,
+ * `key` for explicit override.
+ *
+ * Kept here as a re-export so existing `import { AggCacheOptions }`
+ * paths keep working — they resolve to the same type.
+ */
+type AggCacheOptions = CacheOptions;
+/**
+ * Driver-tunable knobs forwarded to the kit's native aggregation API.
+ * Each kit honors the hints it can; unsupported keys are ignored
+ * (never thrown) — keeps the IR portable while letting hosts opt into
+ * backend-specific performance levers without dropping to kit-native
+ * pipelines.
+ *
+ * **Per-kit support matrix:**
+ *
+ * | Hint            | mongokit                       | sqlitekit                | future kits |
+ * | --------------- | ------------------------------ | ------------------------ | ----------- |
+ * | `allowDiskUse`  | `aggregate({ allowDiskUse })`  | ignored (planner spills) | per-driver  |
+ * | `maxTimeMs`     | `aggregate({ maxTimeMS })`     | ignored (sync driver)    | per-driver  |
+ * | `indexHint`     | `aggregate({ hint })`          | ignored (planner-driven) | per-driver  |
+ *
+ * **Hosts that need a hint to work** must pin the kit version that
+ * supports it via peer-deps. Falling back to "ignored" keeps mixed-
+ * kit fleets working — if a sqlitekit user asks for `allowDiskUse`,
+ * they get the same query they would have without it (SQLite's
+ * planner spills to disk automatically).
+ *
+ * **Why sqlitekit ignores `maxTimeMs`:** better-sqlite3 (the reference
+ * driver) is synchronous — there is no event-loop tick during a query
+ * for a watchdog to interrupt. `db.pragma('busy_timeout', n)` is a
+ * connection-level wait-for-lock setting, NOT a query timeout, and is
+ * already configured at driver init. For workloads that need
+ * cancellable queries pin to mongokit / pgkit, or run sqlitekit on
+ * libsql (async driver) where statement-level abort is feasible.
+ */
+interface AggExecutionHints {
+  /**
+   * Allow the aggregation to spill intermediate results to disk when
+   * the in-memory limit is exceeded. Mongo: `allowDiskUse: true`.
+   * SQL: typically a no-op (the query planner already manages spill).
+   */
+  allowDiskUse?: boolean;
+  /**
+   * Server-side query timeout in milliseconds. Mongo: `maxTimeMS`.
+   * Aborted queries throw a kit-native timeout error — wire it to
+   * your error handler if you want graceful degradation.
+   */
+  maxTimeMs?: number;
+  /**
+   * Index hint passed to the planner. Kit-specific shape:
+   * mongokit accepts `{ field: 1 }` or an index name string;
+   * sqlitekit ignores (the SQLite planner picks indexes itself).
+   * Use sparingly — most aggregations plan correctly without hints.
+   */
+  indexHint?: unknown;
+}
+/**
+ * Time-unit primitive for bucket sizing. Use `AggDateBucketInterval`
+ * (the union below) at API boundaries — this type is the underlying
+ * unit set both the named buckets (`'month'`) and the custom-bin
+ * shape (`{ every: 15, unit: 'minute' }`) draw from.
+ */
+type AggDateBucketUnit = 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+/**
+ * Granularity for time-bucket grouping. Two surface forms:
+ *
+ * 1. **Named buckets** — string-shape, emit canonical ISO-shaped labels:
+ *
+ *   - `'minute'`  → `'YYYY-MM-DDTHH:MM'`  (`'2026-04-15T10:30'`)
+ *   - `'hour'`    → `'YYYY-MM-DDTHH:00'`  (`'2026-04-15T10:00'`)
+ *   - `'day'`     → `'YYYY-MM-DD'`        (`'2026-04-15'`)
+ *   - `'week'`    → `'YYYY-Www'`          (`'2026-W15'`, ISO 8601 week)
+ *   - `'month'`   → `'YYYY-MM'`           (`'2026-04'`)
+ *   - `'quarter'` → `'YYYY-Qn'`           (`'2026-Q2'`)
+ *   - `'year'`    → `'YYYY'`              (`'2026'`)
+ *
+ * 2. **Custom bins** — object-shape, for arbitrary intervals like
+ *    "every 15 minutes" or "every 6 hours":
+ *
+ *   ```ts
+ *   { every: 15, unit: 'minute' }   // 00:00, 00:15, 00:30, ...
+ *   { every: 6,  unit: 'hour'   }   // 00:00, 06:00, 12:00, ...
+ *   { every: 7,  unit: 'day'    }   // weekly bins anchored on epoch
+ *   ```
+ *
+ *    Custom bins emit ISO-shaped labels matching the largest unit
+ *    granularity that disambiguates the bin start (e.g. 15-minute bins
+ *    emit `'YYYY-MM-DDTHH:MM'`; 6-hour bins emit `'YYYY-MM-DDTHH:00'`).
+ *    `every` must be a positive integer; `unit` is the same set as
+ *    named buckets minus quarter (which only makes sense as `every: 1`).
+ *
+ *  **All bucketing is UTC.** Kits that need wall-clock semantics for
+ *  "this month in America/Los_Angeles" pre-shift the column at the
+ *  application layer — keeping the IR timezone-free dodges per-kit
+ *  tz library mismatches (mongo's `$dateToString` and SQLite's
+ *  `strftime` use different IANA tables).
+ *
+ *  The bucket label is sortable lexicographically — that's the whole
+ *  point of the format. `ORDER BY month ASC` yields chronological
+ *  order without parsing the string back into a date.
+ */
+type AggDateBucketInterval = AggDateBucketUnit | {
+  /** Number of `unit`-sized chunks per bin. Must be a positive integer. */every: number; /** Base unit. `quarter` and `year` aren't supported in custom-bin form. */
+  unit: Exclude<AggDateBucketUnit, 'quarter' | 'year'>;
+};
+/**
+ * Time-bucket group expression. Promotes a date column into a
+ * synthetic group key bucketed by the chosen interval.
+ *
+ * **Why a separate slot, not inline in `groupBy`.** A computed
+ * expression isn't a column reference. Each kit needs the
+ * `field + interval` pair to emit its dialect (`$dateToString` on
+ * Mongo, `strftime` on SQLite, `DATE_TRUNC` on PG). Keeping it on its
+ * own slot lets `groupBy` stay a plain column-name list — no shape
+ * change for existing callers.
+ *
+ * The bucket alias (the key in `dateBuckets`) becomes a regular group
+ * key — it counts as a `groupBy` participant for cardinality, sort,
+ * and pagination. Reference it in `having` / `sort` by alias.
+ *
+ * @example
+ * ```ts
+ * await orders.aggregate({
+ *   filter: { status: 'paid' },
+ *   dateBuckets: { month: { field: 'createdAt', interval: 'month' } },
+ *   measures: { revenue: { op: 'sum', field: 'amount' } },
+ *   sort: { month: 1 },
+ * });
+ * // rows: [
+ * //   { month: '2026-01', revenue: 12345 },
+ * //   { month: '2026-02', revenue: 18900 },
+ * // ]
+ * ```
+ */
+interface AggDateBucket {
+  /**
+   * The date / timestamp column to bucket. May be a dotted path into a
+   * joined alias when `lookups` is configured.
+   *
+   * **Storage shape kits must accept:** ISO-8601 strings (the canonical
+   * cross-kit shape from arc + kit serializers), millisecond epoch
+   * numbers, and native Date / BSON Date values. SQLite's TEXT-stored
+   * timestamps in `'YYYY-MM-DD HH:MM:SS'` form also work.
+   */
+  field: string;
+  /** Bucket granularity. */
+  interval: AggDateBucketInterval;
+}
+/**
+ * Portable aggregation request. Compiles to SQL (`SELECT ... FROM ...
+ * [LEFT JOIN ...] WHERE ... GROUP BY ... HAVING ... ORDER BY ... LIMIT ...
+ * OFFSET`) on sqlitekit / pgkit and to a `[$match, $lookup*, $group,
+ * $match, $sort, $limit, $skip]` pipeline on mongokit. Output shape is
+ * identical either way: one row per group, keyed by `groupBy` fields
+ * + measure aliases.
  *
  * Without `groupBy`: returns a single row of scalar aggregates over the
  * full filtered set. With `groupBy`: one row per distinct group.
  *
- * `filter` and `having` both reuse the Filter IR — `filter` narrows the
- * rows that feed into the aggregate (WHERE), `having` narrows the
- * aggregated result (HAVING). Use `having` to reference measure aliases
- * (`{ field: 'revenue', op: 'gt', value: 1000 }`); kit compilers
+ * **Compile order (every kit MUST follow):**
+ *
+ *   1. `filter`   — pre-aggregate predicate, applied to BASE rows
+ *                   BEFORE joins. Drives index selection. (WHERE / `$match`)
+ *   2. `lookups`  — joins, processed in array order. Each `LookupSpec`
+ *                   contributes one stage. Joined rows land at the
+ *                   alias declared in `LookupSpec.as` (or `from` when
+ *                   `as` omitted).
+ *   3. `groupBy`  — one row per distinct combination of group keys.
+ *                   May reference dotted paths into joined aliases:
+ *                   `'category.parent'` groups by the joined
+ *                   `category` row's `parent` field.
+ *   4. `measures` — aggregate functions applied to the grouped rows.
+ *                   `measure.field` accepts the same dotted-path syntax
+ *                   as `groupBy` for joined fields.
+ *   5. `having`   — post-aggregate predicate, references measure
+ *                   aliases. (HAVING)
+ *   6. `sort`     — order grouped rows. Keys are `groupBy` fields,
+ *                   measure aliases, or dotted paths into joined rows.
+ *   7. `limit` / `offset` — row cap + skip.
+ *
+ * **Filter IR usage:** `filter` and `having` both reuse the Filter IR.
+ * `filter` narrows the rows that feed into the aggregate; `having`
+ * narrows the aggregated result. Reference measure aliases in `having`
+ * (`{ field: 'revenue', op: 'gt', value: 1000 }`) — kit compilers
  * substitute the aggregate expression when the field matches a measure.
  *
- * Power features that don't translate across backends — `$lookup`,
- * `$unwind`, window functions, CTEs — stay kit-native. Reach for
- * mongokit's `aggregatePipeline` or sqlitekit's raw `repo.db` when you
- * need them.
+ * **Tenant / policy filter alignment.** Hosts (or arc) MUST inject
+ * tenant-scope predicates as the LEFT-MOST clause of `filter` so the
+ * leading-key index is hit first. Order matters at scale: an
+ * unscoped aggregate on a billion-row collection scans the world.
+ *
+ * **Power features that stay kit-native.** Window functions, CTEs,
+ * pipeline-form `$lookup` with `let`, sub-aggregations, lateral
+ * correlated subqueries — reach for `aggregatePipeline` (mongokit) or
+ * raw Drizzle (`repo.db`) (sqlitekit). The portable IR draws a
+ * deliberate ceiling at "joins + grouping + measures."
  */
 interface AggRequest {
-  /** Pre-aggregate predicate. Reuses Filter IR; compiles to WHERE / `$match`. */
+  /** Pre-aggregate predicate on the BASE rows (before joins). Reuses
+   * Filter IR; compiles to WHERE / `$match`. Place tenant-scope
+   * predicates first for correct index selection. */
   filter?: unknown;
-  /** Grouping columns. Single string, array of strings, or omitted for scalar aggregation. */
+  /**
+   * Optional cross-table joins. Compiled BEFORE the grouping pipeline
+   * so `groupBy` / `measure.field` / `having` / `sort` may reference
+   * `joinedAlias.field` paths. Reuses the same `LookupSpec` IR that
+   * `lookupPopulate()` accepts — kits that already ship
+   * `lookupPopulate` reuse their compile path (mongokit emits
+   * `$lookup` stages, sqlitekit emits `LEFT JOIN`).
+   *
+   * **Per-lookup `where`** narrows the foreign side BEFORE the join
+   * runs. Always set when joining a high-cardinality table — without
+   * it, you join the world and post-filter, which doesn't scale.
+   *
+   * **Per-lookup `select`** projects only required columns from the
+   * joined row. Reduces row size and prevents accidental exposure of
+   * sensitive fields on the joined side.
+   *
+   * **Kit support is graceful-fail.** A kit that doesn't support
+   * `lookups` in its `aggregate()` throws an
+   * `UnsupportedOperationError` with a clear message at request time.
+   * Hosts pin their kit version via peer-deps to get the support
+   * window they need.
+   */
+  lookups?: readonly LookupSpec[];
+  /** Grouping columns. Single string, array of strings, or omitted for
+   * scalar aggregation. May reference dotted paths into joined aliases
+   * when `lookups` is present (e.g. `'category.parent'`). */
   groupBy?: string | readonly string[];
+  /**
+   * Synthetic time-bucket group keys. Each entry promotes a date
+   * column into a group key bucketed at the chosen granularity
+   * (`day` / `week` / `month` / `quarter` / `year`). The map key
+   * becomes a column in the output row holding the canonical
+   * ISO-shaped bucket label.
+   *
+   * Bucketed keys participate in grouping just like `groupBy` columns
+   * — `sort: { month: 1 }`, `having: { field: 'month', op: 'gte', ... }`,
+   * pagination cardinality all treat them as first-class.
+   *
+   * Aliases must NOT collide with `groupBy` field names or `measures`
+   * aliases — the row shape would be ambiguous. Kits surface a
+   * collision as a runtime error.
+   */
+  dateBuckets?: Record<string, AggDateBucket>;
   /**
    * Named aggregations. At least one key required — an empty `measures`
-   * bag is a wiring bug (nothing to compute).
+   * bag is a wiring bug (nothing to compute). `measure.field` accepts
+   * the same dotted-path syntax as `groupBy` for joined fields.
    */
   measures: Record<string, AggMeasure>;
   /** Post-aggregate predicate. Reuses Filter IR; references measure aliases. */
   having?: unknown;
-  /** Order the grouped rows. Keys may be `groupBy` fields or measure aliases. */
+  /** Order the grouped rows. Keys may be `groupBy` fields, measure
+   * aliases, or dotted paths into joined rows. */
   sort?: Record<string, 1 | -1>;
   /** Row cap; applied after `having` + `sort`. */
   limit?: number;
   /** Skip N grouped rows. Paginated callers use `aggregatePaginate` instead. */
   offset?: number;
+  /**
+   * Top-N-per-group filter. Keeps only the top `limit` rows per
+   * partition, ranked by `sortBy`. See `AggTopN` for full semantics.
+   *
+   * Composes with everything else — applies AFTER group / measures /
+   * having so `sortBy` may reference measure aliases. Composes with
+   * the top-level `sort` (which orders the FINAL row set, not within
+   * each partition).
+   */
+  topN?: AggTopN;
+  /**
+   * Driver-tunable performance knobs (allowDiskUse, maxTimeMs,
+   * indexHint). See `AggExecutionHints` for the per-kit support
+   * matrix. Hints a kit doesn't support are silently ignored — the
+   * IR stays portable while letting hosts opt into backend-specific
+   * levers without dropping to kit-native pipelines.
+   */
+  executionHints?: AggExecutionHints;
+  /**
+   * Per-request cache options (TTL, tags, bypass, SWR). See
+   * `AggCacheOptions` for full semantics. Caching is **opt-in per
+   * call** — omit this slot (or set `ttl: 0`) and the request
+   * bypasses the cache layer entirely. Requires the repo to have a
+   * `CacheAdapter` configured (`new Repository(model, plugins, {},
+   * { aggregateCache: adapter })`); throws at request time when
+   * caching is requested but no adapter is wired.
+   */
+  cache?: AggCacheOptions;
 }
 /**
- * Paginated variant of `AggRequest`. Returns the standard offset
- * pagination envelope — same shape as `getAll({ page, limit })` so UI
- * code renders aggregates and raw document lists with the same
- * pagination primitives.
+ * Paginated variant of `AggRequest`. Two pagination modes are
+ * supported, picked by which fields are set:
+ *
+ * - **Offset** (default) — pass `page` (1-indexed) + `limit`. Returns
+ *   the canonical offset envelope (`{ method: 'offset', data, total,
+ *   pages, hasNext, hasPrev, page, limit }`). Same shape as
+ *   `getAll({ page, limit })` so UI code renders aggregates and raw
+ *   document lists with the same pagination primitives.
+ *
+ * - **Keyset** — pass `pagination: 'keyset'` (or supply `after`).
+ *   Cursor-based: each response returns an opaque `next` token that
+ *   the caller passes back as `after` to fetch the following page.
+ *   `sort` is required (the cursor encodes the sort-key tuple of the
+ *   last row); aliases referenced in `sort` must be either
+ *   `groupBy` columns, `dateBuckets` aliases, or `measures` aliases.
+ *
+ * Keyset pagination scales to arbitrary group counts because it never
+ * scans skipped rows — `WHERE (k1, k2) > (a, b)` uses the
+ * `groupBy + sort` index path. Offset's `OFFSET N` skip is O(N), so it
+ * stalls past ~10–100k groups even with the right index. Reach for
+ * keyset on dashboards with deep result sets, infinite-scroll UI, and
+ * any time `total` doesn't have to render.
+ *
+ * ## Index requirements (don't skip this for big-data workloads)
+ *
+ * The keyset advantage **vanishes without the right index**. The
+ * compiled query is:
+ *
+ * ```sql
+ * SELECT ...groupCols, ...measures
+ * FROM <table>
+ * WHERE <filter>
+ * GROUP BY <groupCols>
+ * HAVING (sortKey1, sortKey2, ...) > (?, ?, ...)   -- cursor predicate
+ * ORDER BY <sortKey1, sortKey2>
+ * LIMIT <pageSize>
+ * ```
+ *
+ * On large tables (10M+ rows) you MUST have:
+ *
+ * 1. **A composite index covering `filter` columns + `groupBy` columns**
+ *    in roughly that order. Without this, every page rescans the base
+ *    table — the cursor predicate runs on the post-`GROUP BY` set, so
+ *    if grouping itself is a full scan, keyset gives no advantage over
+ *    offset.
+ *
+ * 2. **Sort keys aligned with the index leftmost prefix.** When `sort`
+ *    is on a measure alias (e.g. `revenue desc`), no index can help —
+ *    the engine must compute every group before sorting. Such sorts
+ *    are O(N log N) per page even with keyset; consider materializing
+ *    the aggregate into a roll-up table and paginating that instead.
+ *
+ * **Examples** (mongokit / Mongo dialect; sqlitekit takes the same
+ * shape via Drizzle schema indexes):
+ *
+ * ```ts
+ * // groupBy: ['organizationId', 'category']  +  sort: { category: 1 }
+ * Schema.index({ organizationId: 1, category: 1 });
+ *
+ * // filter: { active: true } + groupBy: ['userId'] + sort: { userId: 1 }
+ * Schema.index({ active: 1, userId: 1 });
+ *
+ * // dateBuckets: { day: { field: 'createdAt', unit: 'day' } }
+ * //   + sort: { day: -1 } — cursor compares on the bucket expression,
+ * // so the index must cover `createdAt` (the planner pushes the bucket
+ * // through to a range scan):
+ * Schema.index({ createdAt: -1 });
+ * ```
+ *
+ * If `EXPLAIN` shows a `COLLSCAN` / `SCAN TABLE` on a keyset query,
+ * your index is missing or in the wrong order. Mongo's
+ * `db.coll.aggregate(...).explain('executionStats')` and SQLite's
+ * `EXPLAIN QUERY PLAN` both surface this.
  */
 interface AggPaginationRequest extends Omit<AggRequest, 'limit' | 'offset'> {
-  /** 1-indexed page number. Defaults to 1. */
-  page?: number;
   /** Rows per page. Defaults to the kit's standard limit. */
   limit?: number;
+  /**
+   * Pagination mode. `offset` (default) returns
+   * `{ method: 'offset', ... }`; `keyset` returns
+   * `{ method: 'keyset', ... }`. Setting `after` implies `'keyset'`.
+   */
+  pagination?: 'offset' | 'keyset';
+  /** 1-indexed page number. Used by `offset` mode only. Defaults to 1. */
+  page?: number;
   /**
    * `exact` runs `COUNT(DISTINCT groupBy)` (or `COUNT(*)` for scalar
    * aggregates) alongside the data query. `none` skips the count
    * entirely — the envelope's `total` / `pages` are 0 and `hasNext` is
-   * derived from a `LIMIT N+1` peek. Defaults to `exact`.
+   * derived from a `LIMIT N+1` peek. Defaults to `exact`. Used by
+   * `offset` mode only — `keyset` never runs a count.
    */
   countStrategy?: 'exact' | 'none';
+  /**
+   * Opaque cursor from a prior keyset response's `next` field. When
+   * set, returns the page following the row identified by the cursor.
+   * Implies `pagination: 'keyset'`.
+   *
+   * Format is kit-defined and opaque — consumers MUST round-trip it
+   * verbatim. Cross-kit cursor compatibility is not guaranteed.
+   */
+  after?: string;
+}
+/**
+ * Keyset-paginated aggregation envelope. Returned by
+ * `aggregatePaginate(req)` when `pagination: 'keyset'` (or `after` is
+ * set). Mirrors the keyset shape `MinimalRepo.getAll()` produces for
+ * raw doc lists, so UI components can branch on `method` once and
+ * render either case identically.
+ */
+interface KeysetAggPaginationResult<TRow extends AggRow = AggRow> {
+  method: 'keyset';
+  /** Aggregated rows for this page. */
+  data: TRow[];
+  /** Page size echoed back. */
+  limit: number;
+  /** True when another page exists after this one. */
+  hasMore: boolean;
+  /**
+   * Opaque cursor for the next page. `null` when `hasMore` is false.
+   * Consumers pass this back as `req.after` verbatim.
+   */
+  next: string | null;
 }
 /**
  * Shape of each row returned by `aggregate` / `aggregatePaginate`.
@@ -270,6 +989,30 @@ interface AggPaginationRequest extends Omit<AggRequest, 'limit' | 'offset'> {
  * aliases. Values are SQL-native scalars — numbers for count / sum /
  * avg, the group-by column's native type for group keys.
  *
+ * **Joined-alias paths in `groupBy` produce NESTED output rows.**
+ * Same convention `lookupPopulate` uses, so cross-operation row
+ * shapes stay consistent across all read primitives.
+ *
+ * ```ts
+ * await orders.aggregate({
+ *   lookups: [{ from: 'category', localField: 'categoryId',
+ *               foreignField: '_id', as: 'category', single: true }],
+ *   groupBy: ['status', 'category.code'],
+ *   measures: { count: 'count', revenue: 'sum:totalPrice' },
+ * });
+ *
+ * // → { rows: [
+ * //     { status: 'pending', category: { code: 'BOOKS' }, count: 12, revenue: 800 },
+ * //     ...
+ * //   ]}
+ * ```
+ *
+ * Both mongokit and sqlitekit normalize dotted-path groupBy keys to
+ * nested objects on the returned row. Use repo-core's
+ * `nestDottedKeys()` helper from `repository/agg-output.js` if you
+ * receive flat-dotted rows from a future kit that hasn't normalized
+ * yet, or build them yourself in tests.
+ *
  * Generic defaults to `Record<string, unknown>` because cross-kit
  * callers usually don't need the narrower type — cast at the call
  * site with your own `interface RevenueByCategory { ... }` if you do.
@@ -361,10 +1104,13 @@ interface MinimalRepo<TDoc> {
   /** Update by primary key. Returns the updated doc or null. */
   update(id: string, data: Partial<TDoc>, options?: WriteOptions): Promise<TDoc | null>;
   /**
-   * Delete by primary key. Pass `{ mode: 'hard' }` to bypass soft-delete
-   * interception (kits without soft-delete accept and ignore the flag).
+   * Delete by primary key. Returns the {@link DeleteResult} on success or
+   * `null` on miss (matches the `update()` null-on-miss convention).
+   *
+   * Pass `{ mode: 'hard' }` to bypass soft-delete interception (kits
+   * without soft-delete accept and ignore the flag).
    */
-  delete(id: string, options?: DeleteOptions): Promise<DeleteResult>;
+  delete(id: string, options?: DeleteOptions): Promise<DeleteResult | null>;
 }
 /**
  * Recommended repository contract. Every method beyond `MinimalRepo` is
@@ -404,6 +1150,95 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
    * Kits dispatch via `isUpdateSpec(update)` from `@classytic/repo-core/update`.
    */
   findOneAndUpdate?(filter: FilterInput, update: UpdateInput, options?: FindOneAndUpdateOptions): Promise<TDoc | null>;
+  /**
+   * Atomic compare-and-swap state transition. Standardized shape for
+   * the canonical state-machine write that every domain package was
+   * hand-rolling on top of `findOneAndUpdate`:
+   *
+   * ```ts
+   * findOneAndUpdate(
+   *   { _id: id, [field]: from },                 // CAS — match only when state matches
+   *   { $set: { [field]: to, ...patch } },        // transition + patch
+   * );
+   * ```
+   *
+   * Returns the post-update doc on success; `null` when:
+   *   - the row doesn't exist, OR
+   *   - the row's `field` value isn't `from` (someone else transitioned
+   *     first — the standard race-loss signal)
+   *
+   * **Cross-kit portable.** Mongokit compiles to the `findOneAndUpdate`
+   * above. SQL kits compile to
+   * `UPDATE x SET ... WHERE id = ? AND <field> = <from> RETURNING *`.
+   * Prismakit compiles to `prisma.x.updateMany({ where: { id, [field]:
+   * from }, data: ... })` then a `findUnique` when `count > 0`. Same
+   * input, same null-on-race semantics across every backend.
+   *
+   * **Pairs with `@classytic/primitives/state-machine`.** Use
+   * `defineStateMachine()` for the domain "is `from → to` a legal
+   * transition?" gate (compile-time table + `assertTransition()` early
+   * throw); use `claim()` for the concurrency "did we win the
+   * transition vs concurrent writers?" gate (runtime null on race).
+   * The two layers compose:
+   *
+   * ```ts
+   * ORDER_MACHINE.assertTransition(id, current, 'shipped');
+   * const claimed = await repo.claim(id, { from: current, to: 'shipped' });
+   * if (!claimed) throw new ConcurrentTransitionError(id, current, 'shipped');
+   * ```
+   *
+   * **Required.** Both mongokit and sqlitekit ship `claim` as a class
+   * primitive. Downstream domain packages (~10 in classytic alone) all
+   * carry FSM verbs depending on it — none gracefully degrade.
+   * Required-on-the-contract removes the boilerplate `if (repo.claim)
+   * { ... }` at every call site and surfaces missing implementations
+   * at the conformance gate instead of at runtime.
+   *
+   * @param id - Document primary key value
+   * @param transition - `{ from, to }` (defaults to the `status` field)
+   *   or `{ field, from, to }` for state machines keyed off a non-`status`
+   *   column (`phase`, `state`, etc.)
+   * @param patch - Extra fields written alongside the transition (e.g.
+   *   `{ lastHeartbeat: now, workerId: 'w-12' }`). Field-shape only —
+   *   for raw operators use `findOneAndUpdate` directly.
+   * @returns The updated document, or `null` when the CAS lost / no match
+   */
+  claim(id: string, transition: ClaimTransition, patch?: Partial<TDoc>, options?: WriteOptions): Promise<TDoc | null>;
+  /**
+   * Atomic optimistic-concurrency CAS via a version stamp. Sibling to
+   * `claim` for the optimistic-locking pattern: "I read at version
+   * N, write back only if no one's incremented since."
+   *
+   * Builds:
+   *
+   * ```ts
+   * findOneAndUpdate(
+   *   { _id, [versionField]: from, ...where },
+   *   { ...update, $inc: { [versionField]: by ?? 1 } },
+   * );
+   * ```
+   *
+   * Returns the post-update doc on success, `null` when:
+   *   - the row is missing,
+   *   - the version doesn't match `from` (race-loss),
+   *   - any `where` predicate fails.
+   *
+   * **Cross-kit portable.** Mongokit emits the operator update
+   * directly. SQL kits compile to
+   * `UPDATE x SET ... [versionField] = coalesce([versionField], 0) + by
+   *  WHERE id = ? AND [versionField] = ? RETURNING *`.
+   *
+   * **Required.** Same rationale as `claim`. Mongokit and sqlitekit
+   * both ship a class primitive; downstream domain packages that need
+   * versioned writes (`@classytic/order`, `leave`, `payrun`) carry
+   * verbs depending on it.
+   *
+   * @param update - Mongo-operator-shape (`{ $set, $inc, $unset }`)
+   *   OR field-shape (auto-wrapped in `$set`). Mixed shapes throw —
+   *   mongo would silently drop the flat keys. SQL kits accept the
+   *   same shape and compile down to flat column writes.
+   */
+  claimVersion(id: string, transition: ClaimVersionTransition, update: Record<string, unknown>, options?: WriteOptions): Promise<TDoc | null>;
   /**
    * Classify an error from a write as a unique-constraint violation.
    * Arc's idempotency + outbox adapters need this to distinguish
@@ -424,7 +1259,33 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
   } | null>;
   distinct?<T = unknown>(field: string, filter?: FilterInput, options?: QueryOptions): Promise<T[]>;
   findAll?(filter?: FilterInput, options?: QueryOptions): Promise<TDoc[]>;
-  getOrCreate?(filter: FilterInput, data: Partial<TDoc>, options?: WriteOptions): Promise<TDoc | null>;
+  /**
+   * Atomic "look up by filter, insert `data` if missing, return the doc."
+   *
+   * Returns `{ doc, created }` so the caller can disambiguate the two
+   * outcomes without a follow-up read. `created: true` means *this*
+   * caller's `data` won the race and was just inserted; `created: false`
+   * means a doc matching `filter` already existed and was returned
+   * unchanged. This discriminator is load-bearing for race-detection in
+   * idempotency stores, lock acquisition, and "ensure-exists" flows —
+   * a bare `TDoc` return (without `created`) cannot answer the question
+   * the method is named for.
+   *
+   * Implementations:
+   *   - mongokit: `findOneAndUpdate({ filter }, { $setOnInsert: data },
+   *     { upsert: true, returnDocument: 'after', includeResultMetadata: true })`
+   *     and read `created = !!result.lastErrorObject?.upserted`.
+   *   - sqlitekit: `INSERT … ON CONFLICT DO NOTHING RETURNING *` — when
+   *     a row is returned, `created: true`; otherwise follow with
+   *     `SELECT … WHERE filter` and return `created: false`.
+   *   - Other kits: must preserve "single atomic round-trip" where
+   *     possible; a non-atomic fallback is acceptable but should be
+   *     documented.
+   */
+  getOrCreate?(filter: FilterInput, data: Partial<TDoc>, options?: WriteOptions): Promise<{
+    doc: TDoc;
+    created: boolean;
+  }>;
   createMany?(items: Partial<TDoc>[], options?: WriteOptions): Promise<TDoc[]>;
   /**
    * Apply the same update to every matching document. Required — every
@@ -461,27 +1322,53 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
    */
   bulkWrite?(operations: readonly BulkWriteOperation<TDoc>[]): Promise<BulkWriteResult>;
   /**
-   * Portable aggregation. Compiles to `SELECT ... GROUP BY ...` on SQL
-   * kits and to a `[$match, $group, $sort, $limit]` pipeline on mongokit.
-   * Output shape (`{ rows }`) is identical across backends — dashboards
-   * and admin tooling read the same result regardless of the driver.
+   * Portable aggregation. Compiles to `SELECT ... [LEFT JOIN ...] GROUP
+   * BY ...` on SQL kits and to a `[$match, $lookup*, $group, $sort,
+   * $limit]` pipeline on mongokit. Output shape (`{ rows }`) is
+   * identical across backends — dashboards and admin tooling read the
+   * same result regardless of the driver.
+   *
+   * **Cross-table joins.** When `req.lookups` is set, the kit compiles
+   * each `LookupSpec` as a join stage BEFORE the group/measure
+   * pipeline. `groupBy`, `measure.field`, `having`, and `sort` may
+   * then reference dotted paths into the joined aliases (e.g.
+   * `'category.parent'`). Lookups in `aggregate` reuse the same
+   * `LookupSpec` IR a kit's `lookupPopulate()` accepts — same
+   * compile path, same semantics.
    *
-   * Distinct from kit-native aggregation APIs (mongokit's
-   * `aggregatePipeline(stages)`, sqlitekit's raw `repo.db`) by design:
-   * those take backend-specific inputs and return backend-specific
-   * shapes, suited for joins / unwinds / window functions / CTEs. The
-   * portable `aggregate` covers the filter + group + measures + sort +
-   * limit subset that every backend supports — and nothing else, so
-   * the behavior stays identical across drivers.
+   * **Kit support for `lookups` is incremental.** A kit that
+   * implements `aggregate` but NOT yet `aggregate-with-lookups`
+   * SHOULD throw `UnsupportedOperationError` at request time when
+   * `req.lookups` is present, with a message telling the caller to
+   * upgrade. Hosts pin via peer-deps; the API contract (this
+   * interface) does NOT change as kits add support — additive only.
+   *
+   * **Boundary** — kit-native aggregation APIs (mongokit's
+   * `aggregatePipeline(stages)`, sqlitekit's raw `repo.db`) remain
+   * the escape hatch for window functions, CTEs, pipeline-form
+   * `$lookup` with `let`, and lateral subqueries. The portable
+   * `aggregate` covers the filter + lookups + group + measures +
+   * having + sort + limit subset that every backend supports —
+   * deliberately nothing else, so behavior stays identical across
+   * drivers.
    */
   aggregate?<TRow extends AggRow = AggRow>(req: AggRequest): Promise<AggResult<TRow>>;
   /**
-   * Paginated aggregation. Returns the standard offset envelope so UI
-   * code paginates aggregated dashboards with the same primitives as
-   * raw document lists. `countStrategy: 'none'` skips the distinct-
-   * group count for infinite-scroll use.
+   * Paginated aggregation. Returns one of two envelope shapes,
+   * discriminated by `method`:
+   *
+   * - **`offset`** (default) — standard offset envelope. Same shape
+   *   `getAll({ page, limit })` produces for raw document lists.
+   *   `countStrategy: 'none'` skips the distinct-group count for
+   *   infinite-scroll use.
+   * - **`keyset`** (when `req.pagination === 'keyset'` or `req.after`
+   *   is set) — cursor-based envelope. Scales to arbitrary group
+   *   counts because it never scans skipped rows.
+   *
+   * UI components branch on `result.method` once and render either
+   * envelope identically.
    */
-  aggregatePaginate?<TRow extends AggRow = AggRow>(req: AggPaginationRequest): Promise<OffsetPaginationResult<TRow>>;
+  aggregatePaginate?<TRow extends AggRow = AggRow>(req: AggPaginationRequest): Promise<OffsetPaginationResult<TRow> | KeysetAggPaginationResult<TRow>>;
   /**
    * Paginated join. Compiles the portable `LookupSpec[]` to `$lookup`
    * stages on mongokit or `LEFT JOIN` + `json_object()` / `json_group_array()`
@@ -520,4 +1407,4 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
   withTransaction?<T>(fn: (txRepo: StandardRepo<TDoc>) => Promise<T>, options?: Record<string, unknown>): Promise<T>;
 }
 //#endregion
-export { AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, BulkWriteOperation, BulkWriteResult, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindOneAndUpdateOptions, InferDoc, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, UpdateManyResult, WriteOptions };
+export { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ClaimTransition, ClaimVersionTransition, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, UpdateManyResult, WriteOptions };