@classytic/repo-core 0.27.1 → 0.28.0

package/CHANGELOG.md

@@ -4,6 +4,90 @@ All notable changes to `@classytic/repo-core` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.28.0] - 2026-09-14
+
+### Changed — BREAKING: `RetryPolicy.shouldRetry` no longer defaults to retrying everything
+
+`shouldRetry` defaulted to `() => true`, with a comment conceding it was unsafe
+and asking callers to pass their own. That is a documented hazard, not a fence:
+a policy added for network blips also re-ran the write on a duplicate key, a
+validation failure and a permission denial — three times, with backoff. Against
+a slow-but-succeeding server and a non-idempotent write, that is a double write.
+
+The default is now **`isTransientError`** (exported from `./repository`): retry
+a failure that MAY not have happened — failover, write conflict, lock timeout,
+socket error — never one the server answered deterministically. A 4xx-shaped
+`statusCode` is treated as final, since `HttpError` carries one and every kit
+maps validation and permission failures onto it.
+
+**Migration:** a caller relying on retry-everything passes `shouldRetry: () => true`
+explicitly. The point is that it is now a decision rather than an inheritance.
+Tests exercising retry MECHANICS should pass a predicate too, so they stop
+depending on how a generic `Error` happens to be classified.
+
+### Added
+
+- **`resumeToken` on `ChangeEvent`, `startAfter` on `WatchOptions`.** `watch()`
+  already accepted a resume token but a consumer had no way to obtain one, so
+  the documented at-least-once-across-restarts contract was unfulfillable.
+  Persist the last event's `resumeToken` and hand it back as `resumeAfter` (or
+  `startAfter`, which also resumes past an invalidate event) to continue from
+  that point. Additive — a kit whose feed is not resumable leaves the field
+  absent.
+
+- **`AggRequest.countDistinctStrategy`** — `'accumulator'` (default) or
+  `'grouped'`. The default holds every distinct value of a group in that
+  group's accumulator, so memory grows with the data and MongoDB caps it at
+  100MB; `'grouped'` pre-groups by the distinct field so each value becomes a
+  row instead, and nothing accumulates. Results are identical — including that
+  a missing field is not a distinct value while an explicit `null` is. Kits
+  refuse the measure combinations they cannot recombine (`avg`, `percentile`,
+  `stddev`, a second `countDistinct`) rather than approximating them.
+
+- **`prev` / `hasPrev` on `KeysetPaginationResultCore`** — the backward half of
+  cursor pagination, for kits that implement a `before` cursor (mongokit does,
+  >= 3.39.0). Both are OPTIONAL, so a kit that only pages forward is unchanged.
+
+  `prev === undefined` means *"this kit does not answer the question"*, NOT
+  *"there is no previous page"*. A UI must read `hasPrev` to decide whether to
+  offer the control and treat absent as unknown — reading `undefined` as `false`
+  hides a control that should be there.
+
+### Changed
+
+- **`validateKeysetSort` accepts mixed sort directions.** `{ priority: 1,
+  createdAt: -1 }` — the ESR-shaped compound index — used to throw. The keyset
+  predicate is a tuple comparison whose operator is chosen per position, so the
+  directions never needed to agree; rejecting them pushed callers onto offset
+  `skip(n)`, the cost keyset exists to avoid. `_id` now keeps the direction the
+  caller gave it, and still follows the primary field when absent.
+
+  **A kit's filter builder must read the direction PER FIELD** to consume this
+  safely. mongokit's `buildKeysetFilter` does (>= 3.39.0). A kit that derives
+  one operator from the primary field will now silently mis-paginate a
+  mixed-direction sort instead of being protected by the throw — audit yours
+  before upgrading.
+
+### Fixed
+
+- **A cached `getAll` page was served to a caller that asked for a different
+  count strategy.** `countStrategy` / `countLimit` were missing from
+  `DEFAULT_SHAPE_KEYS_BY_OP.getAll`, so every strategy shared one cache key —
+  and the strategies disagree about `total` BY DESIGN: `'none'` reports `0`,
+  `'capped'` reports a flagged ceiling, `'exact'` reports the truth. A list
+  asking for an exact count could therefore render `0 results` over a full page
+  of rows, with nothing reporting an error. Both keys are now on the allowlist.
+
+  `mode` remains off it deliberately — it selects which ENVELOPE comes back, and
+  offset vs keyset are already separated by `page` vs `after`.
+
+  **On deploy this invalidates existing `getAll` cache entries once** (the key
+  shape changed); the next read repopulates them.
+
+  Pinned by mongokit's `plugin-composition-security.test.ts`, whose
+  `countStrategy` case had been `it.skip`ped with a comment documenting the hole
+  rather than closing it.
+
 ## [0.27.1] - 2026-09-11
 
 ### Fixed

package/dist/cache/plugin/context.mjs

@@ -52,7 +52,9 @@ const DEFAULT_SHAPE_KEYS_BY_OP = Object.freeze({
 		"lean",
 		"page",
 		"limit",
-		"after"
+		"after",
+		"countStrategy",
+		"countLimit"
 	],
 	count: ["filter", "filters"],
 	exists: ["filter", "filters"],

package/dist/pagination/keyset.mjs

@@ -38,8 +38,6 @@ function validateKeysetSort(sort, allowedPrimaryFields) {
 	if (allowedPrimaryFields && allowedPrimaryFields.length > 0) {
 		for (const key of nonIdKeys) if (!allowedPrimaryFields.includes(key)) throw new Error(`Keyset sort field "${key}" is not in the strictKeysetSortFields allowlist. Allowed: ${allowedPrimaryFields.join(", ")}. (Protects against lossy null/non-null keyset boundaries.)`);
 	}
-	for (const key of nonIdKeys) if (sort[key] !== primaryDirection) throw new Error("All sort fields must share the same direction for keyset pagination");
-	if (keys.includes("_id") && sort["_id"] !== primaryDirection) throw new Error("_id direction must match primary field direction");
 	if (!keys.includes("_id")) return normalizeSort({
 		...sort,
 		_id: primaryDirection

package/dist/pagination/types.d.mts

@@ -124,6 +124,18 @@ interface KeysetPaginationResultCore<TDoc> {
   hasMore: boolean;
   /** Cursor token for the next page, or `null` when there is none. */
   next: string | null;
+  /**
+   * Cursor token for the PREVIOUS page, or `null` when this is the first.
+   * Feed it back as `before` to walk backwards.
+   *
+   * Optional so a kit that only pages forward is unchanged — but `undefined`
+   * means "this kit does not answer the question", NOT "there is no previous
+   * page". A UI must read {@link hasPrev} to decide whether to offer the
+   * control, and treat absent as unknown rather than as `false`.
+   */
+  prev?: string | null;
+  /** Whether a previous page exists. Absent when the kit does not track it. */
+  hasPrev?: boolean;
 }
 /**
  * Keyset-paginated result envelope.

package/dist/repository/index.d.mts

@@ -1,7 +1,7 @@
 import { LookupPopulateOptions, LookupPopulateResult, LookupRow, LookupSpec } from "../lookup/types.mjs";
 import { UpdateInput } from "../update/types.mjs";
 import { nestDottedKeys, nestDottedKeysAll } from "./agg-output.mjs";
-import { RetryPolicy, throwIfAborted, withRetry } from "./resilience.mjs";
+import { RetryPolicy, isTransientError, throwIfAborted, withRetry } from "./resilience.mjs";
 import { ArchiveOptions, ArchivePort, ArchiveProgress, ArchiveResult, ArchiveSink, runChunkedArchive } from "./archive.mjs";
 import { PLUGIN_ORDER_CONSTRAINTS, Plugin, PluginFunction, PluginType, validatePluginOrder } from "./plugin-types.mjs";
 import { RepositoryBase, RepositoryBaseOptions } from "./base.mjs";
@@ -12,4 +12,4 @@ import { STANDARD_REPO_OPTION_KEYS, StandardRepoOptionKey } from "./options.mjs"
 import { PurgePort, WritingPurgeStrategy, runChunkedPurge } from "./purge.mjs";
 import { ReadOnlyRepoOptions, ReadOnlyRepositoryError, asReadOnlyRepo, isReadOnlyRepo } from "./read-only.mjs";
 import { RetryingTransactionOptions, retryingTransaction } from "./retrying-transaction.mjs";
-export { type AggCacheOptions, type AggDateBucket, type AggDateBucketInterval, type AggDateBucketUnit, type AggExecutionHints, type AggMeasure, type AggPaginationRequest, type AggRequest, type AggResult, type AggRow, type AggTopN, type AggTopNTies, type AggregateOpsSupport, type ArchiveOptions, type ArchivePort, type ArchiveProgress, type ArchiveResult, type ArchiveSink, type BulkCreateResult, type BulkWriteOperation, type BulkWriteResult, type ChangeEvent, type ClaimTransition, type ClaimVersionTransition, type CursorOptions, type DeleteManyResult, type DeleteOptions, type DeleteResult, type DistributionConfig, type DistributionMissHandler, type FilterInput, type FindAllOptions, type FindOneAndUpdateOptions, type InferDoc, type KeysetAggPaginationResult, type LookupPopulateOptions, type LookupPopulateResult, type LookupRow, type LookupSpec, type MinimalRepo, PLUGIN_ORDER_CONSTRAINTS, type PaginationParams, type Plugin, type PluginFunction, type PluginType, type PurgePort, type QueryOptions, type ReadOnlyRepoOptions, ReadOnlyRepositoryError, type RepoCapabilities, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, type RetryPolicy, type RetryingTransactionOptions, STANDARD_REPO_OPTION_KEYS, type StandardRepo, type StandardRepoOptionKey, type TenantPurgeOptions, type TenantPurgeProgress, type TenantPurgeResult, type TenantPurgeStrategy, type TransactionHandle, type TransitionArgs, type TransitionMachine, type UpdateInput, type UpdateManyResult, type WatchOptions, type WriteOptions, type WritingPurgeStrategy, asReadOnlyRepo, createDistributionGuard, filterReferencesKey, isReadOnlyRepo, nestDottedKeys, nestDottedKeysAll, retryingTransaction, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };
+export { type AggCacheOptions, type AggDateBucket, type AggDateBucketInterval, type AggDateBucketUnit, type AggExecutionHints, type AggMeasure, type AggPaginationRequest, type AggRequest, type AggResult, type AggRow, type AggTopN, type AggTopNTies, type AggregateOpsSupport, type ArchiveOptions, type ArchivePort, type ArchiveProgress, type ArchiveResult, type ArchiveSink, type BulkCreateResult, type BulkWriteOperation, type BulkWriteResult, type ChangeEvent, type ClaimTransition, type ClaimVersionTransition, type CursorOptions, type DeleteManyResult, type DeleteOptions, type DeleteResult, type DistributionConfig, type DistributionMissHandler, type FilterInput, type FindAllOptions, type FindOneAndUpdateOptions, type InferDoc, type KeysetAggPaginationResult, type LookupPopulateOptions, type LookupPopulateResult, type LookupRow, type LookupSpec, type MinimalRepo, PLUGIN_ORDER_CONSTRAINTS, type PaginationParams, type Plugin, type PluginFunction, type PluginType, type PurgePort, type QueryOptions, type ReadOnlyRepoOptions, ReadOnlyRepositoryError, type RepoCapabilities, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, type RetryPolicy, type RetryingTransactionOptions, STANDARD_REPO_OPTION_KEYS, type StandardRepo, type StandardRepoOptionKey, type TenantPurgeOptions, type TenantPurgeProgress, type TenantPurgeResult, type TenantPurgeStrategy, type TransactionHandle, type TransitionArgs, type TransitionMachine, type UpdateInput, type UpdateManyResult, type WatchOptions, type WriteOptions, type WritingPurgeStrategy, asReadOnlyRepo, createDistributionGuard, filterReferencesKey, isReadOnlyRepo, isTransientError, nestDottedKeys, nestDottedKeysAll, retryingTransaction, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };

package/dist/repository/index.mjs

@@ -1,5 +1,5 @@
 import { nestDottedKeys, nestDottedKeysAll } from "./agg-output.mjs";
-import { throwIfAborted, withRetry } from "./resilience.mjs";
+import { isTransientError, throwIfAborted, withRetry } from "./resilience.mjs";
 import { runChunkedArchive } from "./archive.mjs";
 import { PLUGIN_ORDER_CONSTRAINTS, validatePluginOrder } from "./plugin-types.mjs";
 import { RepositoryBase } from "./base.mjs";
@@ -8,4 +8,4 @@ import { STANDARD_REPO_OPTION_KEYS } from "./options.mjs";
 import { runChunkedPurge } from "./purge.mjs";
 import { ReadOnlyRepositoryError, asReadOnlyRepo, isReadOnlyRepo } from "./read-only.mjs";
 import { retryingTransaction } from "./retrying-transaction.mjs";
-export { PLUGIN_ORDER_CONSTRAINTS, ReadOnlyRepositoryError, RepositoryBase, STANDARD_REPO_OPTION_KEYS, asReadOnlyRepo, createDistributionGuard, filterReferencesKey, isReadOnlyRepo, nestDottedKeys, nestDottedKeysAll, retryingTransaction, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };
+export { PLUGIN_ORDER_CONSTRAINTS, ReadOnlyRepositoryError, RepositoryBase, STANDARD_REPO_OPTION_KEYS, asReadOnlyRepo, createDistributionGuard, filterReferencesKey, isReadOnlyRepo, isTransientError, nestDottedKeys, nestDottedKeysAll, retryingTransaction, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };

package/dist/repository/resilience.d.mts

@@ -9,24 +9,26 @@
  * never drifts between call sites.
  */
 /**
- * Retry policy for transient failures (network blips, write conflicts,
- * busy-locks, connection resets).
+ * The default `shouldRetry`: retry a failure that may not have happened, never
+ * one that definitely did.
  *
- * **Don't retry blindly.** Validation errors, schema errors, permission
- * errors are NOT transient — retrying just delays the same failure.
- * Mongo `WriteConflict`, SQLite `SQLITE_BUSY`, `ECONNRESET` ARE transient
- * — backoff + retry recovers. Pass `shouldRetry` to narrow when you know
- * your driver's error taxonomy:
+ * This used to be `() => true`, with a comment conceding it was unsafe and
+ * asking callers to pass their own. That is a documented hazard rather than a
+ * fence — a policy set for network blips also re-ran the write on a duplicate
+ * key, a validation failure and a permission denial, three times, with backoff.
+ * For a non-idempotent write that is not a slow failure, it is a double write.
  *
- * ```ts
- * retryPolicy: {
- *   maxAttempts: 3,         // default 3 when block present
- *   baseDelayMs: 100,       // exponential: 100ms, 200ms, 400ms
- *   shouldRetry: (err) =>
- *     /WriteConflict|SQLITE_BUSY|ECONNRESET/i.test(String(err)),
- * }
- * ```
+ * Retried: replica-set failover, write conflicts, lock timeouts, socket errors
+ * — states where the outcome is genuinely unknown.
+ *
+ * NOT retried: anything the server answered deterministically. A 4xx-shaped
+ * `statusCode` is treated as final, since repo-core's own `HttpError` carries
+ * one and every kit maps validation/permission failures onto it.
+ *
+ * Pass `shouldRetry: () => true` to restore the old behaviour explicitly — the
+ * point is that it is now a choice someone made, not a default they inherited.
  */
+declare function isTransientError(err: unknown): boolean;
 interface RetryPolicy {
   /** Max attempts (including the first try). Default 3 when a policy is present. */
   maxAttempts?: number;
@@ -42,10 +44,13 @@ interface RetryPolicy {
    */
   jitter?: boolean;
   /**
-   * Decide whether a given error is transient. Default: retry every error —
-   * kept for back-compat, but UNSAFE as a shared default (it re-runs side
-   * effects on deterministic failures); pass an explicit predicate.
-   * `retryingTransaction` always does.
+   * Decide whether a given error is transient.
+   *
+   * Defaults to {@link isTransientError}: retry a failure that MAY not have
+   * happened (failover, write conflict, socket error), never one that
+   * definitely did (duplicate key, validation, permission). Pass
+   * `() => true` to retry everything — allowed, but as a decision rather
+   * than an inheritance.
    */
   shouldRetry?: (err: unknown, attempt: number) => boolean;
 }
@@ -66,4 +71,4 @@ declare function withRetry<T>(fn: () => Promise<T>, policy: RetryPolicy | undefi
  */
 declare function throwIfAborted(signal: AbortSignal | undefined): void;
 //#endregion
-export { RetryPolicy, throwIfAborted, withRetry };
+export { RetryPolicy, isTransientError, throwIfAborted, withRetry };

package/dist/repository/resilience.mjs

@@ -1,5 +1,69 @@
 //#region src/repository/resilience.ts
 /**
+* Resilience primitives — the single retry/abort contract every kit and
+* every chunked orchestrator (purge, batch imports, outbox relays) uses.
+*
+* One `RetryPolicy` shape across the contract: `QueryOptions.retryPolicy`,
+* `TenantPurgeOptions.retry`, and any kit-internal retry loop all accept
+* the same three knobs. One `withRetry` implementation so backoff math
+* never drifts between call sites.
+*/
+/**
+* Retry policy for transient failures (network blips, write conflicts,
+* busy-locks, connection resets).
+*
+* **Don't retry blindly.** Validation errors, schema errors, permission
+* errors are NOT transient — retrying just delays the same failure.
+* Mongo `WriteConflict`, SQLite `SQLITE_BUSY`, `ECONNRESET` ARE transient
+* — backoff + retry recovers. Pass `shouldRetry` to narrow when you know
+* your driver's error taxonomy:
+*
+* ```ts
+* retryPolicy: {
+*   maxAttempts: 3,         // default 3 when block present
+*   baseDelayMs: 100,       // exponential: 100ms, 200ms, 400ms
+*   shouldRetry: (err) =>
+*     /WriteConflict|SQLITE_BUSY|ECONNRESET/i.test(String(err)),
+* }
+* ```
+*/
+/**
+* Error labels and names that mean "the operation may not have run — running
+* it again is safe". Duck-typed so `repo-core` stays driver-free: MongoDB sets
+* these labels, and other drivers surface the same idea under these names.
+*/
+const TRANSIENT_LABELS = ["RetryableWriteError", "TransientTransactionError"];
+const TRANSIENT_PATTERN = /WriteConflict|LockTimeout|NotWritablePrimary|NotPrimary|PrimarySteppedDown|InterruptedDueToReplStateChange|ShutdownInProgress|HostUnreachable|HostNotFound|NetworkTimeout|SocketException|ECONNRESET|ECONNREFUSED|ETIMEDOUT|EPIPE|SQLITE_BUSY|SQLITE_LOCKED|MongoNetworkError/i;
+/**
+* The default `shouldRetry`: retry a failure that may not have happened, never
+* one that definitely did.
+*
+* This used to be `() => true`, with a comment conceding it was unsafe and
+* asking callers to pass their own. That is a documented hazard rather than a
+* fence — a policy set for network blips also re-ran the write on a duplicate
+* key, a validation failure and a permission denial, three times, with backoff.
+* For a non-idempotent write that is not a slow failure, it is a double write.
+*
+* Retried: replica-set failover, write conflicts, lock timeouts, socket errors
+* — states where the outcome is genuinely unknown.
+*
+* NOT retried: anything the server answered deterministically. A 4xx-shaped
+* `statusCode` is treated as final, since repo-core's own `HttpError` carries
+* one and every kit maps validation/permission failures onto it.
+*
+* Pass `shouldRetry: () => true` to restore the old behaviour explicitly — the
+* point is that it is now a choice someone made, not a default they inherited.
+*/
+function isTransientError(err) {
+	if (err === null || typeof err !== "object") return false;
+	const e = err;
+	if (typeof e.hasErrorLabel === "function") for (const label of TRANSIENT_LABELS) try {
+		if (e.hasErrorLabel(label)) return true;
+	} catch {}
+	if (typeof e.statusCode === "number" && e.statusCode >= 400 && e.statusCode < 500) return false;
+	return TRANSIENT_PATTERN.test(`${String(e.name ?? "")} ${String(e.codeName ?? "")} ${String(e.code ?? "")} ${String(e.message ?? "")}`);
+}
+/**
 * Abortable sleep. A plain `setTimeout` promise holds the process through an
 * abort — a cancelled request would silently wait out its full backoff before
 * noticing. Listener is removed on the timer path so repeated retries don't
@@ -31,7 +95,7 @@ async function withRetry(fn, policy, signal) {
 	if (!policy) return fn();
 	const maxAttempts = policy.maxAttempts ?? 3;
 	const baseDelayMs = policy.baseDelayMs ?? 100;
-	const shouldRetry = policy.shouldRetry ?? (() => true);
+	const shouldRetry = policy.shouldRetry ?? isTransientError;
 	let lastErr;
 	for (let attempt = 0; attempt < maxAttempts; attempt++) {
 		signal?.throwIfAborted();
@@ -59,4 +123,4 @@ function throwIfAborted(signal) {
 	signal?.throwIfAborted();
 }
 //#endregion
-export { throwIfAborted, withRetry };
+export { isTransientError, throwIfAborted, withRetry };

package/dist/repository/types.d.mts

@@ -623,7 +623,37 @@ type AggMeasure = {
   op: 'count';
   field?: string;
   where?: FilterInput;
-} | {
+} |
+/**
+ * Exact distinct count. **Bounded by group memory — see the ceiling below
+ * before using it on a high-cardinality field.**
+ *
+ * It is computed by accumulating the distinct values themselves and taking
+ * the size, so every distinct value in a group is held in that group's
+ * accumulator at once. Cheap for `countDistinct` over a status or a region;
+ * expensive over a user id, an email, or a session token, where the
+ * accumulator grows with the data rather than with the answer.
+ *
+ * MongoDB caps a single group accumulator at 100MB. Past that the pipeline
+ * fails — loudly, which is the right outcome, but it fails at the size the
+ * data reaches rather than at the size anyone planned for.
+ *
+ * Mitigations, in the order worth trying:
+ *   1. narrow the groups (`where`, a tighter `groupBy`) so each accumulator
+ *      holds less;
+ *   2. pass `allowDiskUse` so the stage may spill instead of failing — it
+ *      makes the query slow rather than impossible, and does NOT make every
+ *      accumulator shape safe;
+ *   3. for genuinely unbounded cardinality, count distinct in its own
+ *      request grouped by `(group keys, the distinct field)` and sum the
+ *      rows — one pass more, no accumulator growth.
+ *
+ * There is deliberately no approximate mode: a distinct count that is
+ * quietly within a few percent is exactly the plausible-looking wrong number
+ * this contract exists to avoid. If an estimate is acceptable, the caller
+ * should ask for one explicitly rather than inherit it.
+ */
+{
   op: 'countDistinct';
   field: string;
   where?: FilterInput;
@@ -1084,6 +1114,32 @@ interface AggRequest {
    * each partition).
    */
   topN?: AggTopN;
+  /**
+   * How `countDistinct` is computed.
+   *
+   * - **`'accumulator'`** (default) — collect the distinct values, take the
+   *   size. One pass, and the cheapest thing there is while a group's distinct
+   *   values fit in memory. They are held in that group's accumulator at once,
+   *   so the cost grows with the DATA, not with the answer: fine over a status
+   *   or a region, and a 100MB accumulator failure over a user id or an email.
+   *
+   * - **`'grouped'`** — pre-group by the distinct field so each distinct value
+   *   becomes a row, then count rows. One extra `$group`, and nothing
+   *   accumulates: cardinality stops being a memory question. Slower on small
+   *   groups, which is why it is not the default.
+   *
+   * Results are IDENTICAL either way, including the parts that are easy to get
+   * wrong — a missing field is not a distinct value, an explicit `null` is, and
+   * `where` excludes rows from the count without excluding them from the other
+   * measures. `tests/integration/countdistinct-strategies.test.ts` asserts the
+   * two strategies agree row for row rather than asserting expected numbers,
+   * because a strategy that is merely self-consistent is the failure mode.
+   *
+   * `'grouped'` REFUSES a measure set it cannot re-aggregate (`avg`,
+   * `percentile`, `stddev`, or a second `countDistinct`) instead of returning a
+   * plausible wrong number — see the error for the alternatives.
+   */
+  countDistinctStrategy?: 'accumulator' | 'grouped';
   /**
    * Driver-tunable performance knobs (allowDiskUse, maxTimeMs,
    * indexHint). See `AggExecutionHints` for the per-kit support
@@ -1879,6 +1935,14 @@ interface ChangeEvent<TDoc = unknown> {
   doc?: TDoc;
   /** Commit timestamp as reported by the backend. */
   timestamp: Date;
+  /**
+   * Resume token for THIS event (kit-specific opaque shape — Mongo's
+   * change-document `_id`). Persist the last one you finished processing
+   * and hand it back as `WatchOptions.resumeAfter` / `startAfter` to
+   * continue from that point across restarts. Absent on backends whose
+   * feed is not resumable.
+   */
+  resumeToken?: unknown;
 }
 /** Options for `StandardRepo.watch()`. */
 interface WatchOptions {
@@ -1890,6 +1954,40 @@ interface WatchOptions {
    * for at-least-once consumption across restarts.
    */
   resumeAfter?: unknown;
+  /**
+   * Like `resumeAfter`, but also resumes past an invalidate event (Mongo
+   * `startAfter` — the token of the invalidate itself). Mutually exclusive
+   * with `resumeAfter`; kits reject a call that sets both.
+   */
+  startAfter?: unknown;
+  /**
+   * Ceiling on events held between the stream and a slower consumer.
+   * Default 1024. `0` disables the bound; any other non-positive-integer
+   * (negative, fractional, `Infinity`, `NaN`) is REFUSED rather than treated
+   * as unbounded — silently removing the ceiling is the failure this option
+   * exists to prevent.
+   *
+   * A change feed has no backpressure: the server pushes, and a kit bridging
+   * it into an async iterator buffers whatever the consumer has not reached.
+   * An unbounded buffer therefore turns a consumer that is merely SLOWER than
+   * the write rate into unbounded memory growth — and the symptom is an OOM
+   * far from the cause.
+   *
+   * Overflow ends the iterator with an error carrying `resumeToken` — the last
+   * event the consumer ACKNOWLEDGED, meaning the last one it came back from.
+   * Deliberately not the last DELIVERED event: resuming past one the consumer
+   * was still processing drops it. The error also carries `deliveredToken` for
+   * diagnostics; resuming from that reintroduces the loss.
+   *
+   * It never drops events either way. A change feed silently missing a delete
+   * is the kind of wrong that surfaces as a reconciliation mystery months
+   * later, so the asymmetry is chosen on purpose: redelivering costs a
+   * duplicate, skipping costs a lost write.
+   *
+   * A change stream is an INGESTION mechanism, not a durable queue. Consumers
+   * that must not miss events persist the resume token and stay idempotent.
+   */
+  maxBufferedEvents?: number;
 }
 /**
  * Options for `StandardRepo.cursor()` streaming reads. The open index

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/repo-core",
-  "version": "0.27.1",
+  "version": "0.28.0",
   "description": "Driver-agnostic repository primitives: hooks, Filter IR, operations, pagination, cache contract. Foundation for mongokit, sqlitekit, pgkit, and prismakit. Lean by design — no plugins ship here; each kit owns its own.",
   "type": "module",
   "sideEffects": false,