@classytic/repo-core 0.27.1 → 0.29.0

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;
@@ -814,7 +844,7 @@ type AggCacheOptions = CacheOptions;
  * | --------------- | ------------------------------ | ------------------------ | ----------- |
  * | `allowDiskUse`  | `aggregate({ allowDiskUse })`  | ignored (planner spills) | per-driver  |
  * | `maxTimeMs`     | `aggregate({ maxTimeMS })`     | ignored (sync driver)    | per-driver  |
- * | `indexHint`     | `aggregate({ hint })`          | ignored (planner-driven) | per-driver  |
+ * | `indexHint`     | `{ leadingKeys }` checked; else `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-
@@ -844,10 +874,11 @@ interface AggExecutionHints {
    */
   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.
+   * Index hint. The PORTABLE form is `{ leadingKeys: string[] }` — an expectation that an index
+   * leading with those fields serves this read. It is never forced: mongokit checks a declared
+   * index matches (and throws a configuration error naming what is declared if none does); kits
+   * whose planner picks indexes itself (sqlitekit) ignore it. Any other shape is kit-specific and
+   * FORCED — mongokit sends a `{ field: 1 }` object or an index name as the driver `hint`.
    */
   indexHint?: unknown;
 }
@@ -1084,6 +1115,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 +1936,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 +1955,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/dist/schema/field-rules.mjs

@@ -158,17 +158,60 @@ function mergeFieldRuleConstraints(schemas, schemaOptions) {
 		for (const [field, rule] of Object.entries(rules)) {
 			const prop = properties[field];
 			if (!prop || typeof prop !== "object") continue;
-			if (rule.minLength != null && prop["minLength"] == null) prop["minLength"] = rule.minLength;
-			if (rule.maxLength != null && prop["maxLength"] == null) prop["maxLength"] = rule.maxLength;
-			if (rule.min != null && prop["minimum"] == null) prop["minimum"] = rule.min;
-			if (rule.max != null && prop["maximum"] == null) prop["maximum"] = rule.max;
-			if (rule.pattern != null && prop["pattern"] == null) prop["pattern"] = rule.pattern;
-			if (rule.enum != null && prop["enum"] == null) prop["enum"] = rule.enum;
+			for (const target of elementSchemas(prop)) {
+				if (rule.minLength != null && target["minLength"] == null) target["minLength"] = rule.minLength;
+				if (rule.maxLength != null && target["maxLength"] == null) target["maxLength"] = rule.maxLength;
+				if (rule.min != null && target["minimum"] == null) target["minimum"] = rule.min;
+				if (rule.max != null && target["maximum"] == null) target["maximum"] = rule.max;
+				if (rule.pattern != null && target["pattern"] == null) target["pattern"] = rule.pattern;
+				if (rule.enum != null && target["enum"] == null) target["enum"] = rule.enum;
+			}
 			if (rule.description != null && prop["description"] == null) prop["description"] = rule.description;
 			if (rule.nullable === true) applyNullable(prop);
 		}
 	}
 }
+/** Is this property typed as an array — `'array'` or a tuple that includes it? */
+function isArrayTyped(prop) {
+	const type = prop["type"];
+	return type === "array" || Array.isArray(type) && type.includes("array");
+}
+/**
+* Where a VALUE constraint (`enum`, `pattern`, `minLength`, …) belongs.
+*
+* On a scalar property: the property. On an array property: every ELEMENT
+* schema, never the array.
+*
+* Writing them onto the array is not merely redundant, it is wrong in two
+* different directions depending on the keyword, and neither one throws:
+*
+* - `enum` on an array compares the WHOLE array to each member, which a list
+*   of strings can never equal — so every write is refused, including one that
+*   omits the field, and the error names a field the caller did not send.
+* - `pattern`, `minLength`, `maxLength`, `minimum`, `maximum` are string /
+*   number keywords, and JSON Schema ignores them on an array — so the rule
+*   validates NOTHING while reading as enforced.
+*
+* `min`/`max` therefore bound each element's value, not the item count. That
+* keeps one meaning per keyword; reinterpreting them as `minItems` on arrays
+* only would make a rule's meaning depend on a type the author never wrote.
+*
+* A property with no `items` gets one, so the constraint is never dropped. A
+* tuple-form `items` (an array of schemas) constrains every position.
+*/
+function elementSchemas(prop) {
+	if (Array.isArray(prop["anyOf"])) {
+		const branches = prop["anyOf"].filter((b) => b !== null && typeof b === "object" && isArrayTyped(b));
+		if (branches.length > 0) return branches.flatMap((b) => elementSchemas(b));
+	}
+	if (!isArrayTyped(prop)) return [prop];
+	const items = prop["items"];
+	if (Array.isArray(items)) return items.filter((s) => s !== null && typeof s === "object");
+	if (items && typeof items === "object") return [items];
+	const created = {};
+	prop["items"] = created;
+	return [created];
+}
 /**
 * Widen a JSON Schema property to also accept `null`.
 *

package/dist/schema/standard-schema.mjs

@@ -1,4 +1,4 @@
-import { ERROR_CODES } from "../errors/types.mjs";
+import { ERROR_CODES } from "../errors/codes.mjs";
 //#region src/schema/standard-schema.ts
 /**
 * Standard Schema integration — the validator-agnostic validation slot.

package/dist/testing/idempotency-conformance.d.mts

@@ -0,0 +1,15 @@
+import { IdempotencyClaimStore } from "../idempotency/index.mjs";
+//#region src/testing/idempotency-conformance.d.ts
+interface IdempotencyConformanceHarness {
+  /** A store over an EMPTY backend, per scenario. */
+  createStore(): IdempotencyClaimStore | Promise<IdempotencyClaimStore>;
+}
+/** The contract's cases, runner-agnostic — each `run` throws on failure. */
+declare function idempotencyStoreCases(harness: IdempotencyConformanceHarness): {
+  readonly name: string;
+  readonly run: () => Promise<void>;
+}[];
+/** Register every contract case as a vitest test against `harness.createStore()`. */
+declare function runIdempotencyStoreConformance(harness: IdempotencyConformanceHarness): void;
+//#endregion
+export { IdempotencyConformanceHarness, idempotencyStoreCases, runIdempotencyStoreConformance };