@classytic/repo-core 0.22.0 → 0.24.0

package/dist/repository/retrying-transaction.mjs

@@ -0,0 +1,35 @@
+import { neverTransient } from "../errors/conflict.mjs";
+import { withRetry } from "./resilience.mjs";
+//#region src/repository/retrying-transaction.ts
+/**
+* Run `fn` inside `repo.withTransaction`, re-running on transient conflicts.
+*
+* Throws immediately (no retry) when the repository cannot provide
+* transactions — a caller asking for transactional semantics on a backend
+* that cannot deliver them is a wiring error to surface at the call site,
+* not a mode to degrade through. Method presence alone is NOT the test: kits
+* expose `withTransaction` unconditionally and fail at BEGIN, so a
+* repository that publishes a capability descriptor is held to it
+* (`transactions !== true` — which `'unknown'` deliberately reports, failing
+* closed on an unconfirmed deployment).
+*/
+async function retryingTransaction(repo, fn, options = {}) {
+	if (typeof repo.withTransaction !== "function") throw new Error("retryingTransaction requires repository.withTransaction — this backend does not provide transactions (capability `transactions: false`). Wire a transactional kit, or drop the transactional envelope for this resource.");
+	const capabilities = repo.capabilities;
+	if (capabilities && capabilities.transactions !== true) throw new Error(`retryingTransaction: repository.withTransaction exists but the repository declares \`transactions: ${String(capabilities.transactions)}\` — this deployment cannot run transactions (standalone MongoDB, D1, or an unconfirmed topology). Every call would fail at BEGIN. Wire a transactional deployment, or drop the transactional envelope.`);
+	const isTransient = options.isTransient ?? (typeof repo.isTransientConflictError === "function" ? repo.isTransientConflictError.bind(repo) : neverTransient);
+	if ((options.retryOwner ?? capabilities?.transactionRetry ?? "managed") === "managed") return repo.withTransaction(fn, options.transactionOptions);
+	return withRetry(() => repo.withTransaction(fn, options.transactionOptions), {
+		maxAttempts: options.maxAttempts ?? 5,
+		baseDelayMs: options.baseDelayMs ?? 50,
+		maxDelayMs: options.maxDelayMs ?? 2e3,
+		jitter: true,
+		shouldRetry: (err, attempt) => {
+			if (!isTransient(err)) return false;
+			options.onRetry?.(err, attempt);
+			return true;
+		}
+	}, options.signal);
+}
+//#endregion
+export { retryingTransaction };

package/dist/repository/types.d.mts

@@ -23,6 +23,20 @@ type FilterInput = Filter | Record<string, unknown>;
  * the session through uses `unknown`; kits narrow at the boundary.
  */
 type RepositorySession = unknown;
+/**
+ * What a transaction callback receives BESIDE the tx-bound repository.
+ *
+ * `session` is the raw driver handle, exposed so work that lives OUTSIDE the
+ * repository can join the same transaction — the canonical consumer is an
+ * outbox writer: `outbox.store(event, { session: uow.session })` commits the
+ * event row atomically with the business write. Present when the driver has a
+ * per-transaction handle (Mongo's ClientSession); connection-bound backends
+ * (SQLite) pass an empty handle — their tx-bound repo IS the only join point.
+ * Kits MUST pass a handle object (possibly empty), never omit the argument.
+ */
+interface TransactionHandle {
+  session?: RepositorySession;
+}
 /**
  * Read-operation options. The index signature is the escape hatch kits use
  * for driver-specific flags (`populate`, `select`, `readPreference`,
@@ -72,6 +86,17 @@ interface QueryOptions {
 interface WriteOptions extends QueryOptions {
   /** Upsert on update/replace. */
   upsert?: boolean;
+  /**
+   * Optimistic-concurrency CAS. When set, the write applies ONLY if the
+   * stored version equals `ifVersion`; on mismatch the kit MUST throw
+   * `VersionConflictError` (`@classytic/repo-core/errors`) — never return
+   * `null`, which means not-found and would invite a blind retry that
+   * clobbers the concurrent write. A successful versioned write increments
+   * the stored version. Requires the `optimisticConcurrency` capability;
+   * kits without it MUST throw on the option rather than ignore it (a
+   * silently dropped guard is the defect, not a degraded mode).
+   */
+  ifVersion?: number;
 }
 /**
  * Options for the optional `findAll` verb.
@@ -1502,6 +1527,15 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
    * lives in the kit that knows its driver.
    */
   isDuplicateKeyError?(err: unknown): boolean;
+  /**
+   * Classify an error from a transactional write as a TRANSIENT concurrency
+   * conflict — one the backend expects callers to recover from by re-running
+   * the same work (Mongo `TransientTransactionError` label, PG 40001/40P01,
+   * `SQLITE_BUSY`, Prisma P2034). Consumed by `retryingTransaction`; same
+   * ownership rule as `isDuplicateKeyError` — the kit knows its driver.
+   * Absent = nothing retries (`neverTransient`), the safe default.
+   */
+  isTransientConflictError?(err: unknown): boolean;
   /** Find a single doc by compound filter (used by arc's AccessControl). */
   getOne?(filter: FilterInput, options?: QueryOptions): Promise<TDoc | null>;
   /** Alias many kits expose alongside `getOne`. Arc checks both names. */
@@ -1810,7 +1844,7 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
    * // Either both writes commit or neither does.
    * ```
    */
-  withTransaction?<T>(fn: (txRepo: StandardRepo<TDoc>) => Promise<T>, options?: Record<string, unknown>): Promise<T>;
+  withTransaction?<T>(fn: (txRepo: StandardRepo<TDoc>, uow?: TransactionHandle) => Promise<T>, options?: Record<string, unknown>): Promise<T>;
   /**
    * Portable change feed — `for await` over committed mutations:
    *
@@ -1870,4 +1904,4 @@ interface CursorOptions {
   [key: string]: unknown;
 }
 //#endregion
-export { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ChangeEvent, ClaimTransition, ClaimVersionTransition, CursorOptions, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindAllOptions, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, TenantPurgeOptions, TenantPurgeProgress, TenantPurgeResult, TenantPurgeStrategy, TransitionArgs, TransitionMachine, UpdateManyResult, WatchOptions, WriteOptions };
+export { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ChangeEvent, ClaimTransition, ClaimVersionTransition, CursorOptions, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindAllOptions, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, TenantPurgeOptions, TenantPurgeProgress, TenantPurgeResult, TenantPurgeStrategy, TransactionHandle, TransitionArgs, TransitionMachine, UpdateManyResult, WatchOptions, WriteOptions };

package/dist/tenant/index.d.mts

@@ -1,3 +1,3 @@
 import { ResolvedTenantConfig, TenantConfig, TenantFieldType, TenantStrategy } from "./types.mjs";
-import { DEFAULT_TENANT_CONFIG, resolveTenantConfig, resolveTenantField } from "./resolve.mjs";
-export { DEFAULT_TENANT_CONFIG, type ResolvedTenantConfig, type TenantConfig, type TenantFieldType, type TenantStrategy, resolveTenantConfig, resolveTenantField };
+import { DEFAULT_TENANT_CONFIG, assertNoLegacyTenantKeys, resolveTenantConfig, resolveTenantField } from "./resolve.mjs";
+export { DEFAULT_TENANT_CONFIG, type ResolvedTenantConfig, type TenantConfig, type TenantFieldType, type TenantStrategy, assertNoLegacyTenantKeys, resolveTenantConfig, resolveTenantField };

package/dist/tenant/index.mjs

@@ -1,2 +1,2 @@
-import { DEFAULT_TENANT_CONFIG, resolveTenantConfig, resolveTenantField } from "./resolve.mjs";
-export { DEFAULT_TENANT_CONFIG, resolveTenantConfig, resolveTenantField };
+import { DEFAULT_TENANT_CONFIG, assertNoLegacyTenantKeys, resolveTenantConfig, resolveTenantField } from "./resolve.mjs";
+export { DEFAULT_TENANT_CONFIG, assertNoLegacyTenantKeys, resolveTenantConfig, resolveTenantField };

package/dist/tenant/resolve.d.mts

@@ -28,5 +28,36 @@ declare function resolveTenantConfig(config?: TenantConfig | boolean): ResolvedT
  * scoping" and all return `false` — callers get one thing to branch on.
  */
 declare function resolveTenantField(config?: TenantConfig | boolean): string | false;
+/**
+ * Refuse a config that still carries a pre-consolidation tenant key.
+ *
+ * ## Why this belongs in repo-core and not in each kernel
+ *
+ * Kernels are migrating from a per-package tenant shape (`multiTenant`, plus a
+ * sibling `tenantFieldType` in some) onto {@link TenantConfig} under the key
+ * `tenant`. `@classytic/ledger` has landed; catalog, order, cart, crm, flow,
+ * party, review, transfer and yard have adopted the TYPE but still read
+ * `multiTenant`. Each of those is a future rename.
+ *
+ * The rename itself is trivial. What is not trivial is the failure mode when a
+ * CALLER misses it, because every one of these resolvers reads
+ * `resolveTenantConfig(config.tenant ?? false)`: an absent `tenant` resolves to
+ * `strategy: 'none'` — no tenant field, no tenant filter, every read spanning
+ * ALL tenants, no error, and figures that look plausible. A host that asked for
+ * tenancy gets none, silently.
+ *
+ * Nine packages each remembering to hand-roll that check is nine chances to
+ * forget, and the one that forgets is the one that ships the leak. So the guard
+ * lives beside the resolver every one of them already calls.
+ *
+ * Additive and non-breaking: nothing calls it until a package renames.
+ *
+ * @param config the raw, unresolved shape as the host supplied it
+ * @param pkg package name for the message (e.g. `'defineOrder'`)
+ * @param extra additional legacy keys this package is retiring, as
+ *   `[oldKey, newPath]` — pass `['tenantFieldType', 'tenant.fieldType']` when
+ *   the package carried a sibling field-type option.
+ */
+declare function assertNoLegacyTenantKeys(config: unknown, pkg: string, extra?: ReadonlyArray<readonly [string, string]>): void;
 //#endregion
-export { DEFAULT_TENANT_CONFIG, resolveTenantConfig, resolveTenantField };
+export { DEFAULT_TENANT_CONFIG, assertNoLegacyTenantKeys, resolveTenantConfig, resolveTenantField };

package/dist/tenant/resolve.mjs

@@ -71,5 +71,44 @@ function resolveTenantField(config) {
 	if (!resolved.enabled || resolved.strategy === "none") return false;
 	return resolved.tenantField;
 }
+/**
+* Refuse a config that still carries a pre-consolidation tenant key.
+*
+* ## Why this belongs in repo-core and not in each kernel
+*
+* Kernels are migrating from a per-package tenant shape (`multiTenant`, plus a
+* sibling `tenantFieldType` in some) onto {@link TenantConfig} under the key
+* `tenant`. `@classytic/ledger` has landed; catalog, order, cart, crm, flow,
+* party, review, transfer and yard have adopted the TYPE but still read
+* `multiTenant`. Each of those is a future rename.
+*
+* The rename itself is trivial. What is not trivial is the failure mode when a
+* CALLER misses it, because every one of these resolvers reads
+* `resolveTenantConfig(config.tenant ?? false)`: an absent `tenant` resolves to
+* `strategy: 'none'` — no tenant field, no tenant filter, every read spanning
+* ALL tenants, no error, and figures that look plausible. A host that asked for
+* tenancy gets none, silently.
+*
+* Nine packages each remembering to hand-roll that check is nine chances to
+* forget, and the one that forgets is the one that ships the leak. So the guard
+* lives beside the resolver every one of them already calls.
+*
+* Additive and non-breaking: nothing calls it until a package renames.
+*
+* @param config the raw, unresolved shape as the host supplied it
+* @param pkg package name for the message (e.g. `'defineOrder'`)
+* @param extra additional legacy keys this package is retiring, as
+*   `[oldKey, newPath]` — pass `['tenantFieldType', 'tenant.fieldType']` when
+*   the package carried a sibling field-type option.
+*/
+function assertNoLegacyTenantKeys(config, pkg, extra = []) {
+	if (config === null || typeof config !== "object") return;
+	const record = config;
+	const retired = [["multiTenant", "tenant"], ...extra];
+	for (const [key, became] of retired) {
+		if (record[key] === void 0) continue;
+		throw new Error(`${pkg}: \`${key}\` was renamed to \`${became}\`. It is REFUSED rather than ignored because ignoring it disables tenancy SILENTLY — no tenant field, no tenant filter, and every read spanning all tenants while returning plausible numbers. Move the value to \`tenant\` (\`tenant: false\` for a single-tenant deployment).`);
+	}
+}
 //#endregion
-export { DEFAULT_TENANT_CONFIG, resolveTenantConfig, resolveTenantField };
+export { DEFAULT_TENANT_CONFIG, assertNoLegacyTenantKeys, resolveTenantConfig, resolveTenantField };

package/dist/testing/conformance.mjs

@@ -1,3 +1,4 @@
+import { isVersionConflictError } from "../errors/conflict.mjs";
 import { and, anyOf as in_, eq, gt, isNull, like, ne, or } from "../filter/builders.mjs";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 //#region src/testing/conformance.ts
@@ -1176,6 +1177,14 @@ function runStandardRepoConformance(harness) {
 				const rows = await ctx.repo.findAll({ name: "tx-rollback" });
 				expect(rows).toHaveLength(0);
 			});
+			it("the callback receives a TransactionHandle — the outbox join point", async () => {
+				let handle = "never-called";
+				await ctx.repo.withTransaction(async (_txRepo, uow) => {
+					handle = uow;
+				});
+				expect(typeof handle).toBe("object");
+				expect(handle).not.toBeNull();
+			});
 			it("reads inside the txRepo see writes inside the same callback", async () => {
 				await ctx.repo.withTransaction(async (txRepo) => {
 					const id = idOf(await txRepo.create(harness.makeDoc({
@@ -1186,6 +1195,60 @@ function runStandardRepoConformance(harness) {
 					expect(back?.name).toBe("tx-read");
 				});
 			});
+			it("declares WHO retries a transient conflict — undeclared ownership stacks retry policies", () => {
+				const caps = ctx.repo.capabilities;
+				expect(caps?.transactionRetry, "a repository exposing withTransaction must declare capabilities.transactionRetry: 'managed' (the kit retries internally, callers invoke it once) or 'caller' (single attempt, an outer envelope owns the loop)").toMatch(/^(managed|caller)$/);
+			});
+			it("nestedTransactions matches what a nested call ACTUALLY does", async () => {
+				const caps = ctx.repo.capabilities;
+				let nestedWorked;
+				try {
+					await ctx.repo.withTransaction(async (txRepo) => {
+						await txRepo.withTransaction?.(async () => {});
+					});
+					nestedWorked = true;
+				} catch {
+					nestedWorked = false;
+				}
+				expect(nestedWorked, `capabilities.nestedTransactions is ${String(caps?.nestedTransactions)} but a nested withTransaction ${nestedWorked ? "succeeded" : "threw"} — the descriptor must describe THIS repository, not the underlying driver`).toBe(caps?.nestedTransactions === true);
+			});
+		});
+		describe.skipIf(!harness.features.optimisticConcurrency)("ifVersion CAS", () => {
+			const versionOf = (doc) => Number(doc[harness.versionField ?? "version"]);
+			it("a matching version applies the write and increments the version", async () => {
+				const created = await ctx.repo.create(harness.makeDoc({
+					name: "cas-ok",
+					email: "cas@x.com"
+				}));
+				const id = idOf(created, harness.idField);
+				const v0 = versionOf(created);
+				const updated = await ctx.repo.update(id, { name: "cas-ok-2" }, { ifVersion: v0 });
+				expect(updated?.name).toBe("cas-ok-2");
+				expect(versionOf(updated)).toBe(v0 + 1);
+			});
+			it("a STALE version throws VersionConflictError — never null", async () => {
+				const created = await ctx.repo.create(harness.makeDoc({
+					name: "cas-stale",
+					email: "stale@x.com"
+				}));
+				const id = idOf(created, harness.idField);
+				const v0 = versionOf(created);
+				await ctx.repo.update(id, { name: "cas-stale-2" }, { ifVersion: v0 });
+				let caught;
+				try {
+					await ctx.repo.update(id, { name: "cas-stale-3" }, { ifVersion: v0 });
+				} catch (e) {
+					caught = e;
+				}
+				expect(isVersionConflictError(caught)).toBe(true);
+				const current = await ctx.repo.getById(id);
+				expect(current?.name).toBe("cas-stale-2");
+			});
+			it("not-found stays null — a missing record is NOT a version conflict", async () => {
+				const ghost = harness.missingId ?? "000000000000000000000000";
+				const out = await ctx.repo.update(ghost, { name: "x" }, { ifVersion: 1 });
+				expect(out).toBeNull();
+			});
 		});
 		describe("purgeByField (tenant cleanup)", () => {
 			const seedTwoTenants = async () => {

package/dist/testing/types.d.mts

@@ -97,6 +97,17 @@ interface ConformanceHarness<TDoc extends ConformanceDoc = ConformanceDoc> {
   idField: string;
   /** Feature support flags — skipped scenarios show as `skipped` in vitest output. */
   features: ConformanceFeatures;
+  /**
+   * Field carrying the optimistic-concurrency version, when the
+   * `optimisticConcurrency` capability is declared. Default `'version'`.
+   */
+  versionField?: string;
+  /**
+   * A syntactically valid id that matches no record — the ifVersion cases
+   * assert not-found stays `null` (never a version conflict). Default is a
+   * Mongo-shaped all-zero ObjectId; SQL/string-id kits supply their own.
+   */
+  missingId?: string;
   /** Create a fresh, isolated repo + cleanup closure. Called per test. */
   setup(): Promise<ConformanceContext<TDoc>>;
   /**