@classytic/repo-core 0.4.2 → 0.6.0

package/dist/repository/base.mjs

@@ -1,4 +1,7 @@
 import { HookEngine } from "../hooks/engine.mjs";
+import { HOOK_PRIORITY } from "../hooks/priority.mjs";
+import { registerRepositoryEvents } from "../events/emit.mjs";
+import { validateStandardSchema } from "../schema/standard-schema.mjs";
 import { validatePluginOrder } from "./plugin-types.mjs";
 //#region src/repository/base.ts
 /**
@@ -18,6 +21,28 @@ var RepositoryBase = class {
 		for (let i = 0; i < plugins.length; i++) assertValidPlugin(plugins[i], this.modelName, i);
 		validatePluginOrder(plugins, this.modelName, options.pluginOrderChecks ?? "warn", options.onPluginOrderWarning);
 		for (const plugin of plugins) this.use(plugin);
+		if (options.schema) this._registerSchemaValidation(options.schema, options.updateSchema);
+		if (options.events) registerRepositoryEvents(this, options.events);
+	}
+	/**
+	* Wire Standard Schema validation into the write lifecycle. Validator
+	* output replaces the payload so schema-declared coercions and defaults
+	* flow into the write.
+	*/
+	_registerSchemaValidation(schema, updateSchema) {
+		const validation = { priority: HOOK_PRIORITY.VALIDATION };
+		this.on("before:create", async (context) => {
+			if (context.data === void 0) return;
+			context.data = await validateStandardSchema(schema, context.data);
+		}, validation);
+		this.on("before:createMany", async (context) => {
+			if (!Array.isArray(context.dataArray)) return;
+			context.dataArray = await Promise.all(context.dataArray.map((doc) => validateStandardSchema(schema, doc)));
+		}, validation);
+		if (updateSchema) this.on("before:update", async (context) => {
+			if (context.data === void 0) return;
+			context.data = await validateStandardSchema(updateSchema, context.data);
+		}, validation);
 	}
 	/** Install a plugin (object with `apply(repo)` or a plain function). */
 	use(plugin) {

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,6 +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, QueryOptions, RepositorySession, StandardRepo, UpdateManyResult, WriteOptions } from "./types.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 QueryOptions, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, STANDARD_REPO_OPTION_KEYS, type StandardRepo, type StandardRepoOptionKey, type UpdateInput, type UpdateManyResult, type WriteOptions, nestDottedKeys, nestDottedKeysAll, validatePluginOrder };
+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 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,4 +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";
-export { PLUGIN_ORDER_CONSTRAINTS, RepositoryBase, STANDARD_REPO_OPTION_KEYS, nestDottedKeys, nestDottedKeysAll, validatePluginOrder };
+import { throwIfAborted, withRetry } from "./resilience.mjs";
+import { runChunkedPurge } from "./purge.mjs";
+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.d.mts

@@ -0,0 +1,57 @@
+import { TenantPurgeOptions, TenantPurgeResult, TenantPurgeStrategy } from "./types.mjs";
+
+//#region src/repository/purge.d.ts
+/**
+ * Strategies that perform a write. `skip` is handled by the orchestrator
+ * before the port is ever consulted, so ports only deal with the three
+ * writing variants.
+ */
+type WritingPurgeStrategy = Exclude<TenantPurgeStrategy, {
+  type: 'skip';
+}>;
+/**
+ * Driver-facing port the orchestrator drives. Each kit implements one
+ * closure over its driver primitives + the purge predicate.
+ *
+ * **Plugin-bypass invariant.** Implementations MUST bypass tenant
+ * scoping in plugin hooks — the caller's `field = value` predicate IS
+ * the authoritative scope; a tenant-injecting hook would narrow to the
+ * wrong tenant. Pass `bypassTenant: true` on inner Repository calls
+ * (which keeps audit / cache hooks active but disables tenant injection).
+ *
+ * **Throughput contract.** Implementations should issue the minimum
+ * number of round-trips a chunk requires:
+ *
+ *   - `hard` on SQLite: `DELETE FROM t WHERE field = ? LIMIT n` — 1 RT
+ *   - `hard` on Mongo: `find(filter, {_id:1}).limit(n)` + `deleteMany`
+ *     — 2 RTs (Mongo has no DELETE LIMIT)
+ *   - `soft`: read ids + updateMany with `$set: {deleted, deletedAt}` — 2 RTs
+ *   - `anonymize` static fields: read ids + updateMany — 2 RTs
+ *   - `anonymize` with function-form replacers: read docs +
+ *     `bulkWrite([updateOne, …])` — 2 RTs (vs N+1 with per-doc fan-out)
+ */
+interface PurgePort {
+  /**
+   * Process one chunk under the given strategy. Returns the row count
+   * actually touched (≤ `limit`). The orchestrator loops until this
+   * returns less than `limit` (natural exit) or the abort signal fires.
+   *
+   * Returning `0` signals "no more matching rows"; the orchestrator
+   * exits. Returning a partial batch (`< limit`) is also a terminal
+   * signal — saves one round-trip on the last chunk.
+   */
+  purgeChunk(strategy: WritingPurgeStrategy, limit: number): Promise<number>;
+}
+/**
+ * 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
+ * input (`batchSize < 1`).
+ *
+ * @param strategy  Strategy declaration — `skip` short-circuits.
+ * @param options   Chunking + signal + progress + optional retry.
+ * @param port      Kit-specific driver glue (one `purgeChunk` method).
+ */
+declare function runChunkedPurge(strategy: TenantPurgeStrategy, options: TenantPurgeOptions, port: PurgePort): Promise<TenantPurgeResult>;
+//#endregion
+export { PurgePort, WritingPurgeStrategy, runChunkedPurge };

package/dist/repository/purge.mjs

@@ -0,0 +1,83 @@
+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
+* input (`batchSize < 1`).
+*
+* @param strategy  Strategy declaration — `skip` short-circuits.
+* @param options   Chunking + signal + progress + optional retry.
+* @param port      Kit-specific driver glue (one `purgeChunk` method).
+*/
+async function runChunkedPurge(strategy, options, port) {
+	const start = Date.now();
+	if (strategy.type === "skip") return {
+		strategy: "skip",
+		processed: 0,
+		ok: true,
+		durationMs: Date.now() - start,
+		skipReason: strategy.reason
+	};
+	const batchSize = options.batchSize ?? 1e3;
+	if (!Number.isInteger(batchSize) || batchSize < 1) throw new Error("purgeByField: batchSize must be a positive integer");
+	const retry = options.retry;
+	let processed = 0;
+	try {
+		while (true) {
+			if (options.signal?.aborted) return {
+				strategy: strategy.type,
+				processed,
+				ok: false,
+				durationMs: Date.now() - start
+			};
+			const chunkSize = await withRetry(() => port.purgeChunk(strategy, batchSize), retry, options.signal);
+			if (chunkSize === 0) break;
+			processed += chunkSize;
+			if (options.onProgress) await options.onProgress({
+				processed,
+				chunkSize,
+				elapsedMs: Date.now() - start
+			});
+			if (chunkSize < batchSize) break;
+		}
+	} catch (err) {
+		return {
+			strategy: strategy.type,
+			processed,
+			ok: false,
+			durationMs: Date.now() - start,
+			error: {
+				message: err instanceof Error ? err.message : String(err),
+				chunkOffset: processed
+			}
+		};
+	}
+	return {
+		strategy: strategy.type,
+		processed,
+		ok: true,
+		durationMs: Date.now() - start
+	};
+}
+//#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 };