@classytic/repo-core 0.5.0 → 0.6.0

package/dist/repository/capabilities.d.mts

@@ -0,0 +1,159 @@
+//#region src/repository/capabilities.d.ts
+/**
+ * Runtime capability descriptor — the feature-detection contract every
+ * kit declares so hosts (and arc) can branch on backend support at boot
+ * instead of discovering an `UnsupportedOperationError` at runtime.
+ *
+ * One shape, two consumers:
+ *
+ *   - **Runtime**: `repo.capabilities.arrayOperators` tells a kit-portable
+ *     host whether `$push` / `$pull` updates will work before it ships a
+ *     write that throws on SQLite.
+ *   - **Conformance**: the cross-kit test harness declares the same shape
+ *     (`ConformanceFeatures` in `@classytic/repo-core/testing` is an alias
+ *     of this type) — the flags a kit declares at runtime are exactly the
+ *     scenarios the conformance suite exercises. One source of truth; the
+ *     two can't drift.
+ *
+ * **Stability contract.** Adding a flag is additive — kits that don't
+ * declare a new optional key default to "not supported", the conservative
+ * read. Renaming or removing a flag is a breaking change.
+ *
+ * **Naming convention.** Flag names match the surface they gate
+ * (`percentile` → `AggMeasure.op === 'percentile'`, `changeStreams` →
+ * `StandardRepo.watch`). When in doubt, grep the contract types and use
+ * the same identifier.
+ */
+/**
+ * Per-aggregate-op support matrix. Some aggregate ops aren't portable
+ * across every backend — `percentile` requires Mongo 7+'s `$percentile`
+ * accumulator or SQL's `PERCENTILE_CONT`, neither of which sqlitekit
+ * ships. Kits opt INTO support; absent keys mean "not supported".
+ */
+interface AggregateOpsSupport {
+  /**
+   * `{ op: 'percentile', field, p }` measure. Mongokit (Mongo 7+)
+   * supports it; sqlitekit throws by design (no native function).
+   * Hosts targeting percentile dashboards pin to a kit that supports it.
+   */
+  percentile?: boolean;
+  /**
+   * `{ op: 'stddev', field }` / `{ op: 'stddevPop', field }` measures.
+   * Mongokit supports both via native `$stdDevSamp` / `$stdDevPop`
+   * (Welford). Sqlitekit throws — SQLite has no native STDDEV and
+   * the computational formula is numerically unstable. Hosts pin
+   * to mongokit / future pgkit when stddev is load-bearing.
+   */
+  stddev?: boolean;
+  /**
+   * `topN: { partitionBy, sortBy, limit, ties }` filter. Both
+   * mongokit and sqlitekit support it as of repo-core 0.4.x; the
+   * flag exists for future kits that may not ship window-function
+   * equivalents.
+   */
+  topN?: boolean;
+  /**
+   * `dateBuckets: { ..., interval: { every, unit } }` custom-bin
+   * form. Kits that only support named-bucket form can leave this
+   * `false`; tests for `'minute'` / `'hour'` named intervals are
+   * gated separately via `dateBucketSubMinute`.
+   */
+  customDateBuckets?: boolean;
+  /**
+   * Sub-day-granularity named buckets (`'minute'` / `'hour'`).
+   * Older kits may only support day+ named intervals; flag exists
+   * to gate those scenarios cleanly.
+   */
+  dateBucketSubMinute?: boolean;
+  /**
+   * Per-request `cache?: AggCacheOptions` slot — TTL / tags / SWR /
+   * bypass / `repo.invalidateAggregateCache(tags)`. Both mongokit
+   * and sqlitekit support it as of repo-core 0.4.x. Future kits
+   * without the wiring can leave this false to skip cache scenarios.
+   *
+   * Independent of which CACHE BACKEND the harness wires — test
+   * scenarios construct their own `createMemoryCacheAdapter()` so
+   * this flag is purely "does the kit honour the request slot".
+   */
+  cache?: boolean;
+}
+/**
+ * Per-kit capability flags. Every `StandardRepo` implementation declares
+ * one of these as `readonly capabilities` — the runtime twin of the
+ * conformance harness's feature declaration.
+ *
+ * Hosts that target multiple kits feature-detect once at boot:
+ *
+ * ```ts
+ * if (!repo.capabilities.arrayOperators) {
+ *   // SQL kit — model tags as a join table instead of $push on a JSON column
+ * }
+ * ```
+ */
+interface RepoCapabilities {
+  /** `withTransaction(fn)` — D1 throws, standalone Mongo throws 263. */
+  transactions: boolean;
+  /**
+   * True if calling `withTransaction` inside another `withTransaction`
+   * callback is expected to work. Mongo's driver supports it via the
+   * same session; SQL drivers typically reject it.
+   */
+  nestedTransactions: boolean;
+  /** `findOneAndUpdate` with upsert: true. */
+  upsert: boolean;
+  /** `isDuplicateKeyError(err)` classifier. */
+  duplicateKeyError: boolean;
+  /** `distinct(field)`. */
+  distinct: boolean;
+  /**
+   * Portable `aggregate({ measures, groupBy, having })`. Coarse
+   * top-level flag. Per-op flags live on `aggregateOps` for asymmetric
+   * capabilities (percentile, custom date bins, etc.).
+   */
+  aggregate: boolean;
+  /**
+   * Per-op feature matrix for the aggregate surface. Optional —
+   * absent matrix or absent key both mean "not supported", so kits
+   * opt INTO ops they implement.
+   */
+  aggregateOps?: AggregateOpsSupport;
+  /** `getOrCreate(filter, data)`. */
+  getOrCreate: boolean;
+  /** `count(filter)` and `exists(filter)`. */
+  countAndExists: boolean;
+  /**
+   * `purgeByField(field, value, strategy, options)` — compliance-grade
+   * tenant cleanup primitive.
+   */
+  purgeByField?: boolean;
+  /**
+   * Mongo-style array update operators (`$push`, `$pull`, `$addToSet`,
+   * `$pop`, `$pullAll`). Mongokit: native. Sqlitekit: implemented over
+   * JSON TEXT columns via `json_insert` / `json_each` rewrites — see
+   * the sqlitekit docs for the supported subset.
+   */
+  arrayOperators?: boolean;
+  /**
+   * Filter IR `regex` op. Mongokit: native `$regex`. Sqlitekit throws
+   * unless the host registers a `REGEXP` SQL function on the connection.
+   */
+  regexFilter?: boolean;
+  /**
+   * `watch(filter?)` change feed — `AsyncIterable<ChangeEvent<TDoc>>`.
+   * Mongokit: Mongo change streams (replica set required). Kits without
+   * a native feed leave this false and omit the method.
+   */
+  changeStreams?: boolean;
+  /**
+   * `lean: true` read option — return plain objects instead of driver
+   * documents. SQL kits return plain rows always (trivially true);
+   * mongokit opts in once reads honor the flag.
+   */
+  lean?: boolean;
+  /** Portable `lookupPopulate(options)` join IR. */
+  lookupPopulate?: boolean;
+  /** `cursor(filter, options)` streaming reads (AsyncIterable batches). */
+  streaming?: boolean;
+}
+//#endregion
+export { AggregateOpsSupport, RepoCapabilities };

package/dist/repository/index.d.mts

@@ -3,7 +3,9 @@ import { UpdateInput } from "../update/types.mjs";
 import { nestDottedKeys, nestDottedKeysAll } from "./agg-output.mjs";
 import { PLUGIN_ORDER_CONSTRAINTS, Plugin, PluginFunction, PluginType, validatePluginOrder } from "./plugin-types.mjs";
 import { RepositoryBase, RepositoryBaseOptions } from "./base.mjs";
+import { AggregateOpsSupport, RepoCapabilities } from "./capabilities.mjs";
 import { STANDARD_REPO_OPTION_KEYS, StandardRepoOptionKey } from "./options.mjs";
-import { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ClaimTransition, ClaimVersionTransition, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindAllOptions, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, PurgeRetryPolicy, QueryOptions, RepositorySession, StandardRepo, TenantPurgeOptions, TenantPurgeProgress, TenantPurgeResult, TenantPurgeStrategy, UpdateManyResult, WriteOptions } from "./types.mjs";
+import { RetryPolicy, throwIfAborted, withRetry } from "./resilience.mjs";
+import { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ChangeEvent, ClaimTransition, ClaimVersionTransition, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindAllOptions, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, TenantPurgeOptions, TenantPurgeProgress, TenantPurgeResult, TenantPurgeStrategy, UpdateManyResult, WatchOptions, WriteOptions } from "./types.mjs";
 import { PurgePort, WritingPurgeStrategy, runChunkedPurge } from "./purge.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 BulkCreateResult, type BulkWriteOperation, type BulkWriteResult, type ClaimTransition, type ClaimVersionTransition, type DeleteManyResult, type DeleteOptions, type DeleteResult, 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 PurgeRetryPolicy, type QueryOptions, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, STANDARD_REPO_OPTION_KEYS, type StandardRepo, type StandardRepoOptionKey, type TenantPurgeOptions, type TenantPurgeProgress, type TenantPurgeResult, type TenantPurgeStrategy, type UpdateInput, type UpdateManyResult, type WriteOptions, type WritingPurgeStrategy, nestDottedKeys, nestDottedKeysAll, runChunkedPurge, validatePluginOrder };
+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 BulkCreateResult, type BulkWriteOperation, type BulkWriteResult, type ChangeEvent, type ClaimTransition, type ClaimVersionTransition, type DeleteManyResult, type DeleteOptions, type DeleteResult, 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 RepoCapabilities, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, type RetryPolicy, STANDARD_REPO_OPTION_KEYS, type StandardRepo, type StandardRepoOptionKey, type TenantPurgeOptions, type TenantPurgeProgress, type TenantPurgeResult, type TenantPurgeStrategy, type UpdateInput, type UpdateManyResult, type WatchOptions, type WriteOptions, type WritingPurgeStrategy, nestDottedKeys, nestDottedKeysAll, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };

package/dist/repository/index.mjs

@@ -2,5 +2,6 @@ import { nestDottedKeys, nestDottedKeysAll } from "./agg-output.mjs";
 import { PLUGIN_ORDER_CONSTRAINTS, validatePluginOrder } from "./plugin-types.mjs";
 import { RepositoryBase } from "./base.mjs";
 import { STANDARD_REPO_OPTION_KEYS } from "./options.mjs";
+import { throwIfAborted, withRetry } from "./resilience.mjs";
 import { runChunkedPurge } from "./purge.mjs";
-export { PLUGIN_ORDER_CONSTRAINTS, RepositoryBase, STANDARD_REPO_OPTION_KEYS, nestDottedKeys, nestDottedKeysAll, runChunkedPurge, validatePluginOrder };
+export { PLUGIN_ORDER_CONSTRAINTS, RepositoryBase, STANDARD_REPO_OPTION_KEYS, nestDottedKeys, nestDottedKeysAll, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };

package/dist/repository/options.d.mts

@@ -40,13 +40,17 @@
  *   boundary.
  * - `requestId` — request correlation id for trace stitching across
  *   logs, events, and downstream service calls.
+ * - `traceId` — distributed-tracing trace id (W3C traceparent /
+ *   OpenTelemetry). Observability plugins read it to join repo spans
+ *   onto the host's trace; distinct from `requestId`, which is the
+ *   host's own correlation id and may outlive a single trace.
  *
  * Frameworks should treat this set as the canonical forward list:
  * peel matching keys off the request context, drop them into the
  * options bag, and let kit plugins read what they implement. Unknown
  * ctx keys do NOT forward — the bag stays narrow.
  */
-declare const STANDARD_REPO_OPTION_KEYS: readonly ["organizationId", "userId", "user", "session", "requestId"];
+declare const STANDARD_REPO_OPTION_KEYS: readonly ["organizationId", "userId", "user", "session", "requestId", "traceId"];
 /**
  * Type-level union of canonical option keys. Use to constrain
  * framework helpers that thread request context into repo options:

package/dist/repository/options.mjs

@@ -40,6 +40,10 @@
 *   boundary.
 * - `requestId` — request correlation id for trace stitching across
 *   logs, events, and downstream service calls.
+* - `traceId` — distributed-tracing trace id (W3C traceparent /
+*   OpenTelemetry). Observability plugins read it to join repo spans
+*   onto the host's trace; distinct from `requestId`, which is the
+*   host's own correlation id and may outlive a single trace.
 *
 * Frameworks should treat this set as the canonical forward list:
 * peel matching keys off the request context, drop them into the
@@ -51,7 +55,8 @@ const STANDARD_REPO_OPTION_KEYS = [
 	"userId",
 	"user",
 	"session",
-	"requestId"
+	"requestId",
+	"traceId"
 ];
 //#endregion
 export { STANDARD_REPO_OPTION_KEYS };

package/dist/repository/purge.mjs

@@ -1,5 +1,25 @@
+import { withRetry } from "./resilience.mjs";
 //#region src/repository/purge.ts
 /**
+* Chunked tenant-purge orchestrator — kit-agnostic.
+*
+* Owns the loop / signal / progress / retry / error envelope for
+* `StandardRepo.purgeByField`. Each kit (mongokit, sqlitekit, future
+* pgkit) plugs in a `PurgePort` that knows how to talk to its driver;
+* the orchestrator drives the chunked work.
+*
+* **Why a single-method port** (`purgeChunk(strategy, limit)`): each
+* driver has different round-trip optima — sqlite hard-strategy compiles
+* to one `DELETE … LIMIT` (no SELECT), mongo hard-strategy needs SELECT
+* + deleteMany, anonymize-with-function-form needs SELECT + bulkWrite
+* to batch heterogeneous patches in one round-trip. A two-method port
+* (`selectChunkIds` + `applyStrategy`) forces 2 round-trips for every
+* kit; the single method lets each port pick its own access shape.
+*
+* Hexagonal pattern: the orchestrator is the use-case; `PurgePort` is
+* the driving port; each kit's port factory is the adapter.
+*/
+/**
 * Drive a chunked purge to completion. Returns a `TenantPurgeResult`
 * envelope describing what happened — never throws for in-strategy
 * errors (those wrap into `result.error`); only throws for invalid
@@ -30,7 +50,7 @@ async function runChunkedPurge(strategy, options, port) {
 				ok: false,
 				durationMs: Date.now() - start
 			};
-			const chunkSize = await runChunkWithRetry(() => port.purgeChunk(strategy, batchSize), retry);
+			const chunkSize = await withRetry(() => port.purgeChunk(strategy, batchSize), retry, options.signal);
 			if (chunkSize === 0) break;
 			processed += chunkSize;
 			if (options.onProgress) await options.onProgress({
@@ -59,25 +79,5 @@ async function runChunkedPurge(strategy, options, port) {
 		durationMs: Date.now() - start
 	};
 }
-/**
-* Run `fn` with exponential backoff when retry is enabled. Falls through
-* to a single attempt when `retry` is undefined (default behavior).
-*/
-async function runChunkWithRetry(fn, retry) {
-	if (!retry) return fn();
-	const maxAttempts = retry.maxAttempts ?? 3;
-	const baseDelayMs = retry.baseDelayMs ?? 100;
-	const shouldRetry = retry.shouldRetry ?? (() => true);
-	let lastErr;
-	for (let attempt = 0; attempt < maxAttempts; attempt++) try {
-		return await fn();
-	} catch (err) {
-		lastErr = err;
-		if (attempt === maxAttempts - 1) break;
-		if (!shouldRetry(err, attempt + 1)) break;
-		await new Promise((r) => setTimeout(r, baseDelayMs * 2 ** attempt));
-	}
-	throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
-}
 //#endregion
 export { runChunkedPurge };

package/dist/repository/resilience.d.mts

@@ -0,0 +1,55 @@
+//#region src/repository/resilience.d.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)),
+ * }
+ * ```
+ */
+interface RetryPolicy {
+  /** Max attempts (including the first try). Default 3 when a policy is present. */
+  maxAttempts?: number;
+  /** Base delay (ms) for exponential backoff. Default 100ms; doubles each attempt. */
+  baseDelayMs?: number;
+  /** Decide whether a given error is transient. Default: retry every error. */
+  shouldRetry?: (err: unknown, attempt: number) => boolean;
+}
+/**
+ * Run `fn` with exponential backoff when a policy is provided. Falls
+ * through to a single attempt when `policy` is undefined — callers wrap
+ * unconditionally and the no-policy path costs nothing.
+ *
+ * Honors `signal`: aborts between attempts (never mid-attempt) by
+ * rethrowing the signal's abort reason.
+ */
+declare function withRetry<T>(fn: () => Promise<T>, policy: RetryPolicy | undefined, signal?: AbortSignal): Promise<T>;
+/**
+ * Abort guard for op boundaries. Kits call this at the top of every
+ * operation (and between chunks of chunked work) when the caller passed
+ * `options.signal` — cancelled requests stop before the next driver
+ * round-trip instead of running to completion.
+ */
+declare function throwIfAborted(signal: AbortSignal | undefined): void;
+//#endregion
+export { RetryPolicy, throwIfAborted, withRetry };

package/dist/repository/resilience.mjs

@@ -0,0 +1,39 @@
+//#region src/repository/resilience.ts
+/**
+* Run `fn` with exponential backoff when a policy is provided. Falls
+* through to a single attempt when `policy` is undefined — callers wrap
+* unconditionally and the no-policy path costs nothing.
+*
+* Honors `signal`: aborts between attempts (never mid-attempt) by
+* rethrowing the signal's abort reason.
+*/
+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);
+	let lastErr;
+	for (let attempt = 0; attempt < maxAttempts; attempt++) {
+		signal?.throwIfAborted();
+		try {
+			return await fn();
+		} catch (err) {
+			lastErr = err;
+			if (attempt === maxAttempts - 1) break;
+			if (!shouldRetry(err, attempt + 1)) break;
+			await new Promise((r) => setTimeout(r, baseDelayMs * 2 ** attempt));
+		}
+	}
+	throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+}
+/**
+* Abort guard for op boundaries. Kits call this at the top of every
+* operation (and between chunks of chunked work) when the caller passed
+* `options.signal` — cancelled requests stop before the next driver
+* round-trip instead of running to completion.
+*/
+function throwIfAborted(signal) {
+	signal?.throwIfAborted();
+}
+//#endregion
+export { throwIfAborted, withRetry };

package/dist/repository/types.d.mts

@@ -2,7 +2,9 @@ import { Filter } from "../filter/types.mjs";
 import { OffsetPaginationResult } from "../pagination/types.mjs";
 import { LookupPopulateOptions, LookupPopulateResult, LookupSpec } from "../lookup/types.mjs";
 import { UpdateInput } from "../update/types.mjs";
+import { RepoCapabilities } from "./capabilities.mjs";
 import { CacheOptions } from "../cache/options.mjs";
+import { RetryPolicy } from "./resilience.mjs";
 
 //#region src/repository/types.d.ts
 /**
@@ -51,6 +53,18 @@ interface QueryOptions {
   user?: Record<string, unknown>;
   /** Arc request context (orgId, roles, requestId, ...). */
   context?: Record<string, unknown>;
+  /**
+   * Abort signal. Kits check it at the op boundary (and between chunks of
+   * chunked work) — cancelled requests stop before the next driver
+   * round-trip. Aborting never rolls back a write that already committed.
+   */
+  signal?: AbortSignal;
+  /**
+   * Retry transient driver failures with exponential backoff. Same shape
+   * everywhere (`TenantPurgeOptions.retry`, kit-internal loops) — see
+   * {@link RetryPolicy}. Default: no retry.
+   */
+  retryPolicy?: RetryPolicy;
   /** Driver-specific escape hatch — see JSDoc. */
   [key: string]: unknown;
 }
@@ -195,19 +209,7 @@ interface TenantPurgeOptions {
    * stay committed. A retry that eventually succeeds reports `ok: true`;
    * one that exhausts `maxAttempts` aborts with the underlying error.
    */
-  retry?: PurgeRetryPolicy;
-}
-/**
- * Retry policy for `purgeByField` chunk-level failures. See
- * `TenantPurgeOptions.retry` for the full contract.
- */
-interface PurgeRetryPolicy {
-  /** Max attempts per chunk (including the first try). Default 3. */
-  maxAttempts?: number;
-  /** Base delay (ms) for exponential backoff. Default 100ms. */
-  baseDelayMs?: number;
-  /** Decide whether a given error is transient. Default: retry every error. */
-  shouldRetry?: (err: unknown, attempt: number) => boolean;
+  retry?: RetryPolicy;
 }
 /** Chunk-level progress event for `purgeByField`. */
 interface TenantPurgeProgress {
@@ -1275,6 +1277,18 @@ interface MinimalRepo<TDoc> {
  * kit-native.
  */
 interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
+  /**
+   * Runtime capability descriptor — feature-detection at boot instead of
+   * `UnsupportedOperationError` at runtime. Required: every kit declares
+   * what its backend supports (`arrayOperators`, `changeStreams`,
+   * `aggregateOps.percentile`, ...) so kit-portable hosts and arc can
+   * branch once instead of try/catching per call.
+   *
+   * The same shape gates the cross-kit conformance suite
+   * (`ConformanceFeatures` is an alias) — runtime declaration and test
+   * coverage cannot drift.
+   */
+  readonly capabilities: RepoCapabilities;
   /**
    * Atomic compare-and-set. Match one document, mutate it, return the
    * post-update doc (or pre-update when `returnDocument: 'before'`).
@@ -1608,6 +1622,51 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
    * ```
    */
   withTransaction?<T>(fn: (txRepo: StandardRepo<TDoc>) => Promise<T>, options?: Record<string, unknown>): Promise<T>;
+  /**
+   * Portable change feed — `for await` over committed mutations:
+   *
+   * ```ts
+   * for await (const change of repo.watch!({ status: 'pending' })) {
+   *   if (change.operation === 'create') enqueue(change.doc!);
+   * }
+   * ```
+   *
+   * Backends differ wildly here, so the method is optional and gated by
+   * `capabilities.changeStreams`:
+   *   - mongokit — Mongo change streams (`Model.watch`); requires a
+   *     replica set. `fullDocument: 'updateLookup'` semantics for updates.
+   *   - SQL kits — typically absent (no native feed). Hosts that need
+   *     a feed on SQL pair the repo with `events` emission instead.
+   *
+   * The iterator ends when `options.signal` aborts. Errors from the
+   * underlying stream propagate to the consumer.
+   */
+  watch?(filter?: FilterInput, options?: WatchOptions): AsyncIterable<ChangeEvent<TDoc>>;
+}
+/** A single committed mutation observed by `watch()`. */
+interface ChangeEvent<TDoc = unknown> {
+  /** What happened. `replace` = full-document overwrite (Mongo `replaceOne`). */
+  operation: 'create' | 'update' | 'delete' | 'replace';
+  /** Primary key of the affected document. */
+  id?: unknown;
+  /**
+   * The post-image document — present on create/replace always, on update
+   * when the backend supports post-image lookup, absent on delete.
+   */
+  doc?: TDoc;
+  /** Commit timestamp as reported by the backend. */
+  timestamp: Date;
+}
+/** Options for `StandardRepo.watch()`. */
+interface WatchOptions {
+  /** End the iterator. The only portable way to stop a change feed. */
+  signal?: AbortSignal;
+  /**
+   * Resume token / cursor from a previous stream (kit-specific shape —
+   * Mongo resume tokens are opaque BSON). Hosts persist and replay it
+   * for at-least-once consumption across restarts.
+   */
+  resumeAfter?: unknown;
 }
 //#endregion
-export { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ClaimTransition, ClaimVersionTransition, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindAllOptions, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, PurgeRetryPolicy, QueryOptions, RepositorySession, StandardRepo, TenantPurgeOptions, TenantPurgeProgress, TenantPurgeResult, TenantPurgeStrategy, UpdateManyResult, WriteOptions };
+export { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ChangeEvent, ClaimTransition, ClaimVersionTransition, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindAllOptions, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, TenantPurgeOptions, TenantPurgeProgress, TenantPurgeResult, TenantPurgeStrategy, UpdateManyResult, WatchOptions, WriteOptions };

package/dist/schema/index.d.mts

@@ -1,4 +1,5 @@
+import { StandardSchemaV1, validateStandardSchema } from "./standard-schema.mjs";
 import { CrudSchemas, FieldRule, FieldRules, JsonSchema, SchemaBuilderOptions, ValidationResult } from "./types.mjs";
 import { applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, mergeFieldRuleConstraints, validateUpdateBody } from "./field-rules.mjs";
 import { SchemaGenerator, SchemaGeneratorContext, isSchemaGenerator } from "./generator.mjs";
-export { type CrudSchemas, type FieldRule, type FieldRules, type JsonSchema, type SchemaBuilderOptions, type SchemaGenerator, type SchemaGeneratorContext, type ValidationResult, applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, isSchemaGenerator, mergeFieldRuleConstraints, validateUpdateBody };
+export { type CrudSchemas, type FieldRule, type FieldRules, type JsonSchema, type SchemaBuilderOptions, type SchemaGenerator, type SchemaGeneratorContext, type StandardSchemaV1, type ValidationResult, applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, isSchemaGenerator, mergeFieldRuleConstraints, validateStandardSchema, validateUpdateBody };

package/dist/schema/index.mjs

@@ -1,3 +1,4 @@
+import { validateStandardSchema } from "./standard-schema.mjs";
 import { applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, mergeFieldRuleConstraints, validateUpdateBody } from "./field-rules.mjs";
 import { isSchemaGenerator } from "./generator.mjs";
-export { applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, isSchemaGenerator, mergeFieldRuleConstraints, validateUpdateBody };
+export { applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, isSchemaGenerator, mergeFieldRuleConstraints, validateStandardSchema, validateUpdateBody };

package/dist/schema/standard-schema.d.mts

@@ -0,0 +1,89 @@
+//#region src/schema/standard-schema.d.ts
+/**
+ * Standard Schema integration — the validator-agnostic validation slot.
+ *
+ * [Standard Schema](https://standardschema.dev) is the shared interface
+ * implemented by Zod 3.24+, Valibot 1.0+, ArkType 2.0+, Effect Schema and
+ * others. Vendoring the interface (officially encouraged — it's a
+ * types-only spec designed to be copied) keeps repo-core's zero-dependency
+ * guarantee while letting hosts plug ANY conforming validator into a
+ * repository:
+ *
+ * ```ts
+ * import { z } from 'zod';
+ *
+ * const repo = createRepository(UserModel, {
+ *   schema: z.object({ name: z.string(), email: z.string().email() }),
+ * });
+ * await repo.create({ name: 1 }); // throws HttpError 400 with validationErrors
+ * ```
+ *
+ * `RepositoryBase` wires `schema` / `updateSchema` into `before:create` /
+ * `before:createMany` / `before:update` hooks at `HOOK_PRIORITY.VALIDATION`
+ * — after policy plugins (so tenant-stamped fields are present) and before
+ * cache/observability.
+ */
+/** The Standard Schema interface. Any conforming validator satisfies it. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Validates unknown input values. */
+    readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+  /** The result interface of the validate function. */
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  /** The result interface if validation succeeds. */
+  interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** The non-existent issues. */
+    readonly issues?: undefined;
+  }
+  /** The result interface if validation fails. */
+  interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: readonly Issue[];
+  }
+  /** The issue interface of the failure output. */
+  interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+  /** The path segment interface of the issue. */
+  interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+  /** The Standard Schema types interface. */
+  interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+  /** Infers the input type of a Standard Schema. */
+  type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
+  /** Infers the output type of a Standard Schema. */
+  type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+}
+/**
+ * Validate `data` against a Standard Schema. Returns the schema's typed
+ * output (validators may coerce/transform) or throws an `HttpError` 400
+ * carrying `validationErrors` + structured `meta.issues` — the same wire
+ * shape every kit's own validation errors serialize to.
+ */
+declare function validateStandardSchema<TSchema extends StandardSchemaV1>(schema: TSchema, data: unknown): Promise<StandardSchemaV1.InferOutput<TSchema>>;
+//#endregion
+export { StandardSchemaV1, validateStandardSchema };