@classytic/repo-core 0.30.0 → 0.31.1

package/dist/errors/codes.d.mts

@@ -88,6 +88,8 @@ declare const ARC_ERROR_CODES: {
   readonly WRITE_VERB_CONTRACT_VIOLATION: 'arc.write_verb.contract_violation';
   readonly ADAPTER_CAPABILITY_REQUIRED: 'arc.adapter.capability_required';
   readonly NO_ADAPTER: 'arc.no_adapter';
+  /** HTTP 400 — the `mode` query param is neither `offset` nor `keyset`. */
+  readonly PAGINATION_INVALID_MODE: 'arc.pagination.invalid_mode';
   readonly AGGREGATION_MAX_GROUPS_EXCEEDED: 'arc.aggregation.max_groups_exceeded';
   readonly AGGREGATION_REQUIRED_FILTER_MISSING: 'arc.aggregation.required_filter_missing';
   readonly AGGREGATION_REQUIRED_DATE_RANGE_MISSING: 'arc.aggregation.required_date_range_missing';
@@ -112,6 +114,13 @@ declare const ARC_REASON_CODES: {
 };
 type ArcReasonCode = (typeof ARC_REASON_CODES)[keyof typeof ARC_REASON_CODES];
 /** `details[].code` for a unique-constraint violation (see `toErrorContract`). */
+declare const CURSOR_ERROR_CODES: {
+  /** HTTP 400 — malformed, truncated, wrong sort/version, or failed HMAC. */
+  readonly INVALID: 'repo.cursor.invalid';
+  /** HTTP 400 — minted for another collection, tenant, filter, collation or source set. */
+  readonly SCOPE_MISMATCH: 'repo.cursor.scope_mismatch';
+};
+type CursorErrorCode = (typeof CURSOR_ERROR_CODES)[keyof typeof CURSOR_ERROR_CODES];
 declare const DUPLICATE_KEY_DETAIL_CODE = "duplicate_key";
 //#endregion
-export { ARC_ERROR_CODES, ARC_REASON_CODES, ArcErrorCode, ArcReasonCode, DUPLICATE_KEY_DETAIL_CODE, ERROR_CODES, ErrorCode };
+export { ARC_ERROR_CODES, ARC_REASON_CODES, ArcErrorCode, ArcReasonCode, CURSOR_ERROR_CODES, CursorErrorCode, DUPLICATE_KEY_DETAIL_CODE, ERROR_CODES, ErrorCode };

package/dist/errors/codes.mjs

@@ -87,6 +87,8 @@ const ARC_ERROR_CODES = {
 	WRITE_VERB_CONTRACT_VIOLATION: "arc.write_verb.contract_violation",
 	ADAPTER_CAPABILITY_REQUIRED: "arc.adapter.capability_required",
 	NO_ADAPTER: "arc.no_adapter",
+	/** HTTP 400 — the `mode` query param is neither `offset` nor `keyset`. */
+	PAGINATION_INVALID_MODE: "arc.pagination.invalid_mode",
 	AGGREGATION_MAX_GROUPS_EXCEEDED: "arc.aggregation.max_groups_exceeded",
 	AGGREGATION_REQUIRED_FILTER_MISSING: "arc.aggregation.required_filter_missing",
 	AGGREGATION_REQUIRED_DATE_RANGE_MISSING: "arc.aggregation.required_date_range_missing",
@@ -109,6 +111,12 @@ const ARC_REASON_CODES = {
 	BEFORE_RESTORE_HOOK_ERROR: "BEFORE_RESTORE_HOOK_ERROR"
 };
 /** `details[].code` for a unique-constraint violation (see `toErrorContract`). */
+const CURSOR_ERROR_CODES = {
+	/** HTTP 400 — malformed, truncated, wrong sort/version, or failed HMAC. */
+	INVALID: "repo.cursor.invalid",
+	/** HTTP 400 — minted for another collection, tenant, filter, collation or source set. */
+	SCOPE_MISMATCH: "repo.cursor.scope_mismatch"
+};
 const DUPLICATE_KEY_DETAIL_CODE = "duplicate_key";
 //#endregion
-export { ARC_ERROR_CODES, ARC_REASON_CODES, DUPLICATE_KEY_DETAIL_CODE, ERROR_CODES };
+export { ARC_ERROR_CODES, ARC_REASON_CODES, CURSOR_ERROR_CODES, DUPLICATE_KEY_DETAIL_CODE, ERROR_CODES };

package/dist/errors/index.d.mts

@@ -1,8 +1,8 @@
 import { IsTransientConflictFn, VersionConflictError, conservativeMongoIsTransientConflict, isVersionConflictError, neverTransient } from "./conflict.mjs";
-import { ARC_ERROR_CODES, ARC_REASON_CODES, ArcErrorCode, ArcReasonCode, DUPLICATE_KEY_DETAIL_CODE, ERROR_CODES, ErrorCode } from "./codes.mjs";
+import { ARC_ERROR_CODES, ARC_REASON_CODES, ArcErrorCode, ArcReasonCode, CURSOR_ERROR_CODES, CursorErrorCode, DUPLICATE_KEY_DETAIL_CODE, ERROR_CODES, ErrorCode } from "./codes.mjs";
 import { DuplicateKeyMeta, ErrorContract, ErrorDetail, HttpError, ValidationErrorMeta } from "./types.mjs";
 import { statusToErrorCode, toErrorContract } from "./contract.mjs";
 import { createError, isHttpError } from "./create-error.mjs";
 import { IsDuplicateKeyErrorFn, ToDuplicateKeyHttpErrorOptions, conservativeMongoIsDuplicateKey, toDuplicateKeyHttpError } from "./duplicate-key.mjs";
 import { errorContractSchema, errorDetailSchema } from "./schema.mjs";
-export { ARC_ERROR_CODES, ARC_REASON_CODES, type ArcErrorCode, type ArcReasonCode, DUPLICATE_KEY_DETAIL_CODE, type DuplicateKeyMeta, ERROR_CODES, type ErrorCode, type ErrorContract, type ErrorDetail, type HttpError, type IsDuplicateKeyErrorFn, type IsTransientConflictFn, type ToDuplicateKeyHttpErrorOptions, type ValidationErrorMeta, VersionConflictError, conservativeMongoIsDuplicateKey, conservativeMongoIsTransientConflict, createError, errorContractSchema, errorDetailSchema, isHttpError, isVersionConflictError, neverTransient, statusToErrorCode, toDuplicateKeyHttpError, toErrorContract };
+export { ARC_ERROR_CODES, ARC_REASON_CODES, type ArcErrorCode, type ArcReasonCode, CURSOR_ERROR_CODES, type CursorErrorCode, DUPLICATE_KEY_DETAIL_CODE, type DuplicateKeyMeta, ERROR_CODES, type ErrorCode, type ErrorContract, type ErrorDetail, type HttpError, type IsDuplicateKeyErrorFn, type IsTransientConflictFn, type ToDuplicateKeyHttpErrorOptions, type ValidationErrorMeta, VersionConflictError, conservativeMongoIsDuplicateKey, conservativeMongoIsTransientConflict, createError, errorContractSchema, errorDetailSchema, isHttpError, isVersionConflictError, neverTransient, statusToErrorCode, toDuplicateKeyHttpError, toErrorContract };

package/dist/errors/index.mjs

@@ -1,7 +1,7 @@
-import { ARC_ERROR_CODES, ARC_REASON_CODES, DUPLICATE_KEY_DETAIL_CODE, ERROR_CODES } from "./codes.mjs";
+import { ARC_ERROR_CODES, ARC_REASON_CODES, CURSOR_ERROR_CODES, DUPLICATE_KEY_DETAIL_CODE, ERROR_CODES } from "./codes.mjs";
 import { VersionConflictError, conservativeMongoIsTransientConflict, isVersionConflictError, neverTransient } from "./conflict.mjs";
 import { statusToErrorCode, toErrorContract } from "./contract.mjs";
 import { createError, isHttpError } from "./create-error.mjs";
 import { conservativeMongoIsDuplicateKey, toDuplicateKeyHttpError } from "./duplicate-key.mjs";
 import { errorContractSchema, errorDetailSchema } from "./schema.mjs";
-export { ARC_ERROR_CODES, ARC_REASON_CODES, DUPLICATE_KEY_DETAIL_CODE, ERROR_CODES, VersionConflictError, conservativeMongoIsDuplicateKey, conservativeMongoIsTransientConflict, createError, errorContractSchema, errorDetailSchema, isHttpError, isVersionConflictError, neverTransient, statusToErrorCode, toDuplicateKeyHttpError, toErrorContract };
+export { ARC_ERROR_CODES, ARC_REASON_CODES, CURSOR_ERROR_CODES, DUPLICATE_KEY_DETAIL_CODE, ERROR_CODES, VersionConflictError, conservativeMongoIsDuplicateKey, conservativeMongoIsTransientConflict, createError, errorContractSchema, errorDetailSchema, isHttpError, isVersionConflictError, neverTransient, statusToErrorCode, toDuplicateKeyHttpError, toErrorContract };

package/dist/pagination/index.d.mts

@@ -1,6 +1,8 @@
 import { AggregatePaginationResult, AggregatePaginationResultCore, AnyPaginationResult, BareListResult, CursorPayload, DecodedCursor, KeysetPaginationResult, KeysetPaginationResultCore, OffsetPaginationResult, OffsetPaginationResultCore, PaginatedResult, PaginationConfig, SortDirection, SortSpec, ValueType } from "./types.mjs";
+import { CURSOR_ERROR_CODES } from "../errors/codes.mjs";
 import { isPaginatedResult, toCanonicalList } from "./canonical.mjs";
 import { decodeCursor, encodeCursor, validateCursorSort, validateCursorVersion } from "./cursor.mjs";
 import { getPrimaryField, invertSort, normalizeSort, validateKeysetSort } from "./keyset.mjs";
+import { KeysetSource, MergeKeysetOptions, MergedKeysetPage, mergeKeysetPages } from "./merge-keyset.mjs";
 import { calculateSkip, calculateTotalPages, shouldWarnDeepPagination, validateLimit, validatePage } from "./offset.mjs";
-export { type AggregatePaginationResult, type AggregatePaginationResultCore, type AnyPaginationResult, type BareListResult, type CursorPayload, type DecodedCursor, type KeysetPaginationResult, type KeysetPaginationResultCore, type OffsetPaginationResult, type OffsetPaginationResultCore, type PaginatedResult, type PaginationConfig, type SortDirection, type SortSpec, type ValueType, calculateSkip, calculateTotalPages, decodeCursor, encodeCursor, getPrimaryField, invertSort, isPaginatedResult, normalizeSort, shouldWarnDeepPagination, toCanonicalList, validateCursorSort, validateCursorVersion, validateKeysetSort, validateLimit, validatePage };
+export { type AggregatePaginationResult, type AggregatePaginationResultCore, type AnyPaginationResult, type BareListResult, CURSOR_ERROR_CODES, type CursorPayload, type DecodedCursor, type KeysetPaginationResult, type KeysetPaginationResultCore, type KeysetSource, type MergeKeysetOptions, type MergedKeysetPage, type OffsetPaginationResult, type OffsetPaginationResultCore, type PaginatedResult, type PaginationConfig, type SortDirection, type SortSpec, type ValueType, calculateSkip, calculateTotalPages, decodeCursor, encodeCursor, getPrimaryField, invertSort, isPaginatedResult, mergeKeysetPages, normalizeSort, shouldWarnDeepPagination, toCanonicalList, validateCursorSort, validateCursorVersion, validateKeysetSort, validateLimit, validatePage };

package/dist/pagination/index.mjs

@@ -1,5 +1,7 @@
+import { CURSOR_ERROR_CODES } from "../errors/codes.mjs";
 import { isPaginatedResult, toCanonicalList } from "./canonical.mjs";
 import { decodeCursor, encodeCursor, validateCursorSort, validateCursorVersion } from "./cursor.mjs";
 import { getPrimaryField, invertSort, normalizeSort, validateKeysetSort } from "./keyset.mjs";
+import { mergeKeysetPages } from "./merge-keyset.mjs";
 import { calculateSkip, calculateTotalPages, shouldWarnDeepPagination, validateLimit, validatePage } from "./offset.mjs";
-export { calculateSkip, calculateTotalPages, decodeCursor, encodeCursor, getPrimaryField, invertSort, isPaginatedResult, normalizeSort, shouldWarnDeepPagination, toCanonicalList, validateCursorSort, validateCursorVersion, validateKeysetSort, validateLimit, validatePage };
+export { CURSOR_ERROR_CODES, calculateSkip, calculateTotalPages, decodeCursor, encodeCursor, getPrimaryField, invertSort, isPaginatedResult, mergeKeysetPages, normalizeSort, shouldWarnDeepPagination, toCanonicalList, validateCursorSort, validateCursorVersion, validateKeysetSort, validateLimit, validatePage };

package/dist/pagination/merge-keyset.d.mts

@@ -0,0 +1,50 @@
+//#region src/pagination/merge-keyset.d.ts
+/**
+ * `mergeKeysetPages`: one keyset page over SEVERAL sources, each already ordered by the same total
+ * order, merged by the sort key with source order as the final tiebreaker. Each call reads at most
+ * one page of `limit` rows per source. ONE composite cursor carries every source's position (the
+ * merge frontier) plus a fingerprint of (source names, source scopes, sort); it is HMAC-signed when a
+ * secret is given. A cursor that does not decode or verify is `repo.cursor.invalid`; one minted
+ * for other sources, another scope or another sort is `repo.cursor.scope_mismatch` (both 400).
+ */
+interface KeysetSource<T> {
+  /** Unique among the merged sources; part of the cursor binding. */
+  readonly name: string;
+  /** What the source's position is relative to (tenant + filter); a change refuses old cursors. */
+  readonly scope?: string;
+  /** Rows strictly after `after` (this source's own cursor), in the shared order. */
+  page(args: {
+    after?: string;
+    limit: number;
+  }): Promise<{
+    data: readonly T[];
+    hasMore: boolean;
+  }>;
+  /**
+   * This source's cursor positioned AT `row` (its next page starts after it). `row` may come from
+   * ANOTHER source (the merge frontier), so every source shares the sort fields, and the final
+   * tiebreaker is unique across sources (e.g. an ObjectId).
+   */
+  cursorOf(row: T): string | Promise<string>;
+}
+interface MergeKeysetOptions<T> {
+  /** The shared order, ending in a unique tiebreaker (e.g. `{ createdAt: -1, _id: -1 }`). */
+  sort: Readonly<Record<string, 1 | -1>>;
+  limit: number;
+  cursor?: string;
+  /** Sign the composite cursor; when set, an unsigned or mis-signed cursor is refused. */
+  secret?: string;
+  /** Sort-key reader for a row field (default: dotted-path property read). */
+  read?: (row: T, field: string) => unknown;
+}
+interface MergedKeysetPage<T> {
+  docs: Array<{
+    source: string;
+    row: T;
+  }>;
+  next: string | null;
+  hasNext: boolean;
+}
+declare function mergeKeysetPages<T>(sources: readonly KeysetSource<T>[], options: MergeKeysetOptions<T>): Promise<MergedKeysetPage<T>>;
+//#endregion
+export { KeysetSource, MergeKeysetOptions, MergedKeysetPage, mergeKeysetPages };

package/dist/pagination/merge-keyset.mjs

@@ -0,0 +1,139 @@
+import { CURSOR_ERROR_CODES } from "../errors/codes.mjs";
+import { createError } from "../errors/create-error.mjs";
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+//#region src/pagination/merge-keyset.ts
+/**
+* `mergeKeysetPages`: one keyset page over SEVERAL sources, each already ordered by the same total
+* order, merged by the sort key with source order as the final tiebreaker. Each call reads at most
+* one page of `limit` rows per source. ONE composite cursor carries every source's position (the
+* merge frontier) plus a fingerprint of (source names, source scopes, sort); it is HMAC-signed when a
+* secret is given. A cursor that does not decode or verify is `repo.cursor.invalid`; one minted
+* for other sources, another scope or another sort is `repo.cursor.scope_mismatch` (both 400).
+*/
+function fingerprint(sources, sort) {
+	return createHash("sha256").update(JSON.stringify([sources.map((s) => [s.name, s.scope ?? null]), Object.entries(sort)])).digest("hex").slice(0, 16);
+}
+function sign(body, secret) {
+	return createHmac("sha256", secret).update(body).digest("base64url");
+}
+/** A 400 carrying a closed code. */
+function cursorError(message, code) {
+	return Object.assign(createError(400, message), { code });
+}
+const invalid = (why) => cursorError(`Invalid cursor: ${why}`, CURSOR_ERROR_CODES.INVALID);
+function encode(payload, secret) {
+	const body = Buffer.from(JSON.stringify(payload)).toString("base64url");
+	return secret ? `${body}.${sign(body, secret)}` : body;
+}
+function decode(token, secret) {
+	const [body, mac, extra] = token.split(".");
+	if (!body || extra !== void 0) throw invalid("malformed");
+	if (secret) {
+		if (!mac) throw invalid("it carries no signature");
+		const want = Buffer.from(sign(body, secret));
+		const got = Buffer.from(mac);
+		if (want.length !== got.length || !timingSafeEqual(want, got)) throw invalid("signature does not verify");
+	} else if (mac !== void 0) throw invalid("signed cursor, but no secret is configured");
+	let payload;
+	try {
+		payload = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+	} catch {
+		throw invalid("not a cursor token");
+	}
+	const p = payload;
+	if (!p || p.v !== 1 || typeof p.fp !== "string" || !Array.isArray(p.p) || !Array.isArray(p.d) || p.p.length !== p.d.length || !p.p.every((x) => x === null || typeof x === "string") || !p.d.every((x) => typeof x === "boolean")) throw invalid("malformed payload");
+	return p;
+}
+function readPath(row, field) {
+	let cur = row;
+	for (const seg of field.split(".")) {
+		if (cur === null || typeof cur !== "object") return void 0;
+		cur = cur[seg];
+	}
+	return cur;
+}
+/** BSON-like order for sort values: null / missing first, then numbers, strings, dates, ids. */
+function rank(v) {
+	if (v === null || v === void 0) return [0, 0];
+	if (typeof v === "number") return [1, v];
+	if (typeof v === "bigint") return [1, Number(v)];
+	if (typeof v === "string") return [2, v];
+	if (v instanceof Date) return [4, v.getTime()];
+	if (typeof v === "boolean") return [3, v ? 1 : 0];
+	if (typeof v === "object") {
+		if (v._bsontype === "Decimal128") return [1, Number(String(v))];
+		const hex = v.toHexString;
+		if (typeof hex === "function") return [5, hex.call(v)];
+	}
+	return [6, String(v)];
+}
+function compareValues(a, b) {
+	const [ta, va] = rank(a);
+	const [tb, vb] = rank(b);
+	if (ta !== tb) return ta - tb;
+	return va < vb ? -1 : va > vb ? 1 : 0;
+}
+async function mergeKeysetPages(sources, options) {
+	const { sort, limit, secret } = options;
+	if (!Number.isInteger(limit) || limit < 1) throw new TypeError(`mergeKeysetPages: limit must be a positive integer, got ${limit}`);
+	if (new Set(sources.map((s) => s.name)).size !== sources.length) throw new TypeError("mergeKeysetPages: source names must be unique");
+	if (Object.keys(sort).length === 0) throw new TypeError("mergeKeysetPages: sort must name at least one field");
+	const read = options.read ?? readPath;
+	const fp = fingerprint(sources, sort);
+	let positions = sources.map(() => null);
+	let done = sources.map(() => false);
+	if (options.cursor) {
+		const p = decode(options.cursor, secret);
+		if (p.fp !== fp || p.p.length !== sources.length) throw cursorError("Invalid cursor: it was issued for different sources, scopes or sort", CURSOR_ERROR_CODES.SCOPE_MISMATCH);
+		positions = p.p;
+		done = p.d;
+	}
+	const pages = await Promise.all(sources.map((s, i) => done[i] ? {
+		data: [],
+		hasMore: false
+	} : s.page({
+		...positions[i] ? { after: positions[i] } : {},
+		limit
+	})));
+	const fields = Object.entries(sort);
+	const cmp = (a, b) => {
+		for (const [field, dir] of fields) {
+			const c = compareValues(read(a, field), read(b, field));
+			if (c !== 0) return c * dir;
+		}
+		return 0;
+	};
+	const heads = pages.map(() => 0);
+	const docs = [];
+	while (docs.length < limit) {
+		let best = -1;
+		for (let i = 0; i < sources.length; i++) {
+			const row = pages[i]?.data[heads[i]];
+			if (row === void 0) continue;
+			if (best === -1 || cmp(row, pages[best]?.data[heads[best]]) < 0) best = i;
+		}
+		if (best === -1) break;
+		const row = pages[best]?.data[heads[best]];
+		docs.push({
+			source: sources[best]?.name,
+			row
+		});
+		heads[best] = heads[best] + 1;
+	}
+	const frontier = docs[docs.length - 1]?.row;
+	const nextPositions = frontier === void 0 ? positions : await Promise.all(sources.map((s) => s.cursorOf(frontier)));
+	const nextDone = sources.map((_, i) => done[i] === true || pages[i]?.hasMore === false && heads[i] === pages[i]?.data.length);
+	const hasNext = nextDone.some((d) => !d);
+	return {
+		docs,
+		hasNext,
+		next: hasNext ? encode({
+			v: 1,
+			fp,
+			p: nextPositions,
+			d: nextDone
+		}, secret) : null
+	};
+}
+//#endregion
+export { mergeKeysetPages };

package/dist/query-parser/grammar.d.mts

@@ -75,6 +75,10 @@ interface PageRequest {
   readonly page?: number;
   /** Keyset cursor (`after`, or its alias `cursor`). */
   readonly after?: string;
+  /** Keyset cursor for the PREVIOUS page. Never together with `after`. */
+  readonly before?: string;
+  /** Explicit paging mode, when the caller named one. */
+  readonly mode?: 'offset' | 'keyset';
 }
 interface PageOptions {
   defaultLimit?: number | undefined;
@@ -86,6 +90,8 @@ declare function readPageRequest(input: {
   limit?: unknown;
   after?: unknown;
   cursor?: unknown;
+  before?: unknown;
+  mode?: unknown;
 }, options?: PageOptions): PageRequest;
 /** `sort=-createdAt,name` or qs `sort[createdAt]=desc`. An invalid or disallowed field is refused. */
 declare function readSort(raw: unknown, options?: {

package/dist/query-parser/grammar.mjs

@@ -294,16 +294,33 @@ function readPageRequest(input, options = {}) {
 	const maxLimit = options.maxLimit ?? 1e3;
 	const requested = positiveInt(input.limit, "limit");
 	const limit = Math.min(requested ?? options.defaultLimit ?? 20, maxLimit);
+	const mode = pageMode(input.mode);
+	const withMode = (r) => mode ? {
+		...r,
+		mode
+	} : r;
 	const after = cursorValue(input.after ?? input.cursor);
-	if (after !== void 0) return {
+	const before = cursorValue(input.before);
+	if (after !== void 0 && before !== void 0) throw new QueryGrammarError("before", "pass after or before, not both");
+	if (after !== void 0) return withMode({
 		limit,
 		after
-	};
+	});
+	if (before !== void 0) return withMode({
+		limit,
+		before
+	});
 	const page = positiveInt(input.page, "page");
-	return page === void 0 ? { limit } : {
+	return withMode(page === void 0 ? { limit } : {
 		limit,
 		page
-	};
+	});
+}
+function pageMode(raw) {
+	if (raw === void 0 || raw === null || raw === "") return void 0;
+	const value = String(raw).trim();
+	if (value === "offset" || value === "keyset") return value;
+	throw new QueryGrammarError("mode", "mode is offset or keyset");
 }
 /** `sort=-createdAt,name` or qs `sort[createdAt]=desc`. An invalid or disallowed field is refused. */
 function readSort(raw, options = {}) {

package/dist/query-parser/reserved.mjs

@@ -27,6 +27,8 @@ const STANDARD_RESERVED_PARAMS = /* @__PURE__ */ new Set([
 	"page",
 	"limit",
 	"after",
+	"before",
+	"mode",
 	"sort",
 	"select",
 	"populate",

package/dist/repository/bulk-upsert.d.mts

@@ -0,0 +1,59 @@
+import { WriteOptions } from "./types.mjs";
+//#region src/repository/bulk-upsert.d.ts
+type BulkUpsertOutcome = 'inserted' | 'updated' | 'unchanged' | 'failed';
+declare const BULK_UPSERT_FAILURE_CODES: {
+  /** A unique index other than (or racing on) the key refused the row. */
+  readonly DUPLICATE: 'duplicate';
+  /** Schema / document validation refused the row. */
+  readonly VALIDATION: 'validation';
+  /** The row lacks a key field (or carries a non-numeric `inc` field); it was not sent. */
+  readonly INVALID_ROW: 'invalid_row';
+  /** `ordered: true` stopped at an earlier failure; this row was not attempted. */
+  readonly NOT_ATTEMPTED: 'not_attempted';
+  /** Any other per-row write error. */
+  readonly WRITE_ERROR: 'write_error';
+};
+type BulkUpsertFailureCode = (typeof BULK_UPSERT_FAILURE_CODES)[keyof typeof BULK_UPSERT_FAILURE_CODES];
+declare const BULK_UPSERT_ERROR_CODES: {
+  /** No unique index covers the key (with the policy scope): refused before any write. */
+  readonly KEY_NOT_UNIQUE: 'repo.bulk_upsert.key_not_unique';
+  /** A field is routed to two of `set` / `inc` / `setOnInsert`, or a key field is routed at all. */
+  readonly INVALID_OPTIONS: 'repo.bulk_upsert.invalid_options';
+  /** The backend cannot report a per-row outcome (Mongo: server < 8.0). */
+  readonly UNSUPPORTED: 'repo.bulk_upsert.unsupported';
+};
+interface BulkUpsertOptions extends WriteOptions {
+  /** Fields that identify a row. Required; a unique index must cover them. */
+  key: readonly string[];
+  /** When given, only these fields are `$set`; otherwise every non-key, non-routed field. */
+  set?: readonly string[];
+  /** Fields added with `$inc` (numeric). */
+  inc?: readonly string[];
+  /** Fields written only when the row is inserted. */
+  setOnInsert?: readonly string[];
+  /** Stop at the first failure (later rows `not_attempted`). Default `false`. */
+  ordered?: boolean;
+}
+interface BulkUpsertRowResult {
+  /** Position in the input array. */
+  index: number;
+  /** The row's key values, as given. */
+  key: Record<string, unknown>;
+  outcome: BulkUpsertOutcome;
+  /** Present iff `outcome === 'failed'`. */
+  code?: BulkUpsertFailureCode;
+}
+interface BulkUpsertResult {
+  /** One entry per input row, in input order. */
+  results: readonly BulkUpsertRowResult[];
+  inserted: number;
+  updated: number;
+  unchanged: number;
+  failed: number;
+}
+/** Validate field routing; returns the error message, or undefined when the options are valid. */
+declare function bulkUpsertOptionsError(options: BulkUpsertOptions): string | undefined;
+/** Tally a positional result list into the summary counts. */
+declare function summarizeBulkUpsert(results: readonly BulkUpsertRowResult[]): BulkUpsertResult;
+//#endregion
+export { BULK_UPSERT_ERROR_CODES, BULK_UPSERT_FAILURE_CODES, BulkUpsertFailureCode, BulkUpsertOptions, BulkUpsertOutcome, BulkUpsertResult, BulkUpsertRowResult, bulkUpsertOptionsError, summarizeBulkUpsert };

package/dist/repository/bulk-upsert.mjs

@@ -0,0 +1,50 @@
+//#region src/repository/bulk-upsert.ts
+const BULK_UPSERT_FAILURE_CODES = {
+	/** A unique index other than (or racing on) the key refused the row. */
+	DUPLICATE: "duplicate",
+	/** Schema / document validation refused the row. */
+	VALIDATION: "validation",
+	/** The row lacks a key field (or carries a non-numeric `inc` field); it was not sent. */
+	INVALID_ROW: "invalid_row",
+	/** `ordered: true` stopped at an earlier failure; this row was not attempted. */
+	NOT_ATTEMPTED: "not_attempted",
+	/** Any other per-row write error. */
+	WRITE_ERROR: "write_error"
+};
+const BULK_UPSERT_ERROR_CODES = {
+	/** No unique index covers the key (with the policy scope): refused before any write. */
+	KEY_NOT_UNIQUE: "repo.bulk_upsert.key_not_unique",
+	/** A field is routed to two of `set` / `inc` / `setOnInsert`, or a key field is routed at all. */
+	INVALID_OPTIONS: "repo.bulk_upsert.invalid_options",
+	/** The backend cannot report a per-row outcome (Mongo: server < 8.0). */
+	UNSUPPORTED: "repo.bulk_upsert.unsupported"
+};
+/** Validate field routing; returns the error message, or undefined when the options are valid. */
+function bulkUpsertOptionsError(options) {
+	if (!Array.isArray(options.key) || options.key.length === 0) return "`key` must name at least one field";
+	const seen = /* @__PURE__ */ new Map();
+	for (const [list, fields] of [
+		["key", options.key],
+		["set", options.set ?? []],
+		["inc", options.inc ?? []],
+		["setOnInsert", options.setOnInsert ?? []]
+	]) for (const field of fields) {
+		const prior = seen.get(field);
+		if (prior) return `field '${field}' is in both \`${prior}\` and \`${list}\``;
+		seen.set(field, list);
+	}
+}
+/** Tally a positional result list into the summary counts. */
+function summarizeBulkUpsert(results) {
+	const out = {
+		results,
+		inserted: 0,
+		updated: 0,
+		unchanged: 0,
+		failed: 0
+	};
+	for (const r of results) out[r.outcome] += 1;
+	return out;
+}
+//#endregion
+export { BULK_UPSERT_ERROR_CODES, BULK_UPSERT_FAILURE_CODES, bulkUpsertOptionsError, summarizeBulkUpsert };

package/dist/repository/capabilities.d.mts

@@ -220,6 +220,29 @@ interface RepoCapabilities {
   lookupPopulate?: boolean;
   /** `cursor(filter, options)` streaming reads (AsyncIterable batches). */
   streaming?: boolean;
+  /**
+   * `getByIds(ids, { preserveOrder: true, chunkSize })`: an array aligned with `ids` (undefined
+   * for a miss), the same answer at any chunk size. Gates the `getByIds (ordered, chunked)`
+   * group of `runDataAccessConformance`.
+   */
+  getByIdsOrdered?: boolean;
+  /**
+   * Every join (`aggregate({ lookups })`) reads the joined collection under its own tenant and
+   * soft-delete scope, and a join into a collection the kit cannot resolve is refused. Gates the
+   * `scoped joins` group of `runDataAccessConformance`.
+   */
+  scopedJoins?: boolean;
+  /**
+   * Keyset walks equal an in-memory sort (nulls, ties), survive concurrent writes with no duplicate
+   * or gap, and offset pages never repeat a row. Gates `runPaginationPropertyConformance` (fast-check).
+   */
+  paginationProperties?: boolean;
+  /** `bulkUpsert(rows, { key, set, inc, setOnInsert })` with exact per-row outcomes. Gates the `bulkUpsert` group. */
+  bulkUpsert?: boolean;
+  /** Read-model primitives (increments with dedupe, rebuild, reconcile). Gates the `read model` group. */
+  readModel?: boolean;
+  /** Kit sources compose with `mergeKeysetPages` (scope-bound per-row cursors). Gates `runMergeKeysetConformance`. */
+  mergeKeyset?: boolean;
 }
 //#endregion
 export { AggregateOpsSupport, RepoCapabilities };

package/dist/repository/index.d.mts

@@ -7,9 +7,10 @@ import { PLUGIN_ORDER_CONSTRAINTS, Plugin, PluginFunction, PluginType, validateP
 import { RepositoryBase, RepositoryBaseOptions } from "./base.mjs";
 import { AggregateOpsSupport, RepoCapabilities } from "./capabilities.mjs";
 import { 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 } from "./types.mjs";
+import { BULK_UPSERT_ERROR_CODES, BULK_UPSERT_FAILURE_CODES, BulkUpsertFailureCode, BulkUpsertOptions, BulkUpsertOutcome, BulkUpsertResult, BulkUpsertRowResult, bulkUpsertOptionsError, summarizeBulkUpsert } from "./bulk-upsert.mjs";
 import { DistributionConfig, DistributionMissHandler, createDistributionGuard, filterReferencesKey } from "./distribution.mjs";
 import { STANDARD_REPO_OPTION_KEYS, StandardRepoOptionKey } from "./options.mjs";
 import { PurgePort, WritingPurgeStrategy, runChunkedPurge } from "./purge.mjs";
 import { ReadOnlyRepoOptions, ReadOnlyRepositoryError, asReadOnlyRepo, isReadOnlyRepo } from "./read-only.mjs";
 import { RetryingTransactionOptions, retryingTransaction } from "./retrying-transaction.mjs";
-export { type AggCacheOptions, type AggDateBucket, type AggDateBucketInterval, type AggDateBucketUnit, type AggExecutionHints, type AggMeasure, type AggPaginationRequest, type AggRequest, type AggResult, type AggRow, type AggTopN, type AggTopNTies, type AggregateOpsSupport, type ArchiveOptions, type ArchivePort, type ArchiveProgress, type ArchiveResult, type ArchiveSink, type BulkCreateResult, type BulkWriteOperation, type BulkWriteResult, type ChangeEvent, type ClaimTransition, type ClaimVersionTransition, type CursorOptions, type DeleteManyResult, type DeleteOptions, type DeleteResult, type DistributionConfig, type DistributionMissHandler, type FilterInput, type FindAllOptions, type FindOneAndUpdateOptions, type InferDoc, type KeysetAggPaginationResult, type LookupPopulateOptions, type LookupPopulateResult, type LookupRow, type LookupSpec, type MinimalRepo, PLUGIN_ORDER_CONSTRAINTS, type PaginationParams, type Plugin, type PluginFunction, type PluginType, type PurgePort, type QueryOptions, type ReadOnlyRepoOptions, ReadOnlyRepositoryError, type RepoCapabilities, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, type RetryPolicy, type RetryingTransactionOptions, STANDARD_REPO_OPTION_KEYS, type StandardRepo, type StandardRepoOptionKey, type TenantPurgeOptions, type TenantPurgeProgress, type TenantPurgeResult, type TenantPurgeStrategy, type TransactionHandle, type TransitionArgs, type TransitionMachine, type UpdateInput, type UpdateManyResult, type WatchOptions, type WriteOptions, type WritingPurgeStrategy, asReadOnlyRepo, createDistributionGuard, filterReferencesKey, isReadOnlyRepo, isTransientError, nestDottedKeys, nestDottedKeysAll, retryingTransaction, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };
+export { type AggCacheOptions, type AggDateBucket, type AggDateBucketInterval, type AggDateBucketUnit, type AggExecutionHints, type AggMeasure, type AggPaginationRequest, type AggRequest, type AggResult, type AggRow, type AggTopN, type AggTopNTies, type AggregateOpsSupport, type ArchiveOptions, type ArchivePort, type ArchiveProgress, type ArchiveResult, type ArchiveSink, BULK_UPSERT_ERROR_CODES, BULK_UPSERT_FAILURE_CODES, type BulkCreateResult, type BulkUpsertFailureCode, type BulkUpsertOptions, type BulkUpsertOutcome, type BulkUpsertResult, type BulkUpsertRowResult, type BulkWriteOperation, type BulkWriteResult, type ChangeEvent, type ClaimTransition, type ClaimVersionTransition, type CursorOptions, type DeleteManyResult, type DeleteOptions, type DeleteResult, type DistributionConfig, type DistributionMissHandler, type FilterInput, type FindAllOptions, type FindOneAndUpdateOptions, type InferDoc, type KeysetAggPaginationResult, type LookupPopulateOptions, type LookupPopulateResult, type LookupRow, type LookupSpec, type MinimalRepo, PLUGIN_ORDER_CONSTRAINTS, type PaginationParams, type Plugin, type PluginFunction, type PluginType, type PurgePort, type QueryOptions, type ReadOnlyRepoOptions, ReadOnlyRepositoryError, type RepoCapabilities, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, type RetryPolicy, type RetryingTransactionOptions, STANDARD_REPO_OPTION_KEYS, type StandardRepo, type StandardRepoOptionKey, type TenantPurgeOptions, type TenantPurgeProgress, type TenantPurgeResult, type TenantPurgeStrategy, type TransactionHandle, type TransitionArgs, type TransitionMachine, type UpdateInput, type UpdateManyResult, type WatchOptions, type WriteOptions, type WritingPurgeStrategy, asReadOnlyRepo, bulkUpsertOptionsError, createDistributionGuard, filterReferencesKey, isReadOnlyRepo, isTransientError, nestDottedKeys, nestDottedKeysAll, retryingTransaction, runChunkedArchive, runChunkedPurge, summarizeBulkUpsert, throwIfAborted, validatePluginOrder, withRetry };

package/dist/repository/index.mjs

@@ -3,9 +3,10 @@ import { isTransientError, throwIfAborted, withRetry } from "./resilience.mjs";
 import { runChunkedArchive } from "./archive.mjs";
 import { PLUGIN_ORDER_CONSTRAINTS, validatePluginOrder } from "./plugin-types.mjs";
 import { RepositoryBase } from "./base.mjs";
+import { BULK_UPSERT_ERROR_CODES, BULK_UPSERT_FAILURE_CODES, bulkUpsertOptionsError, summarizeBulkUpsert } from "./bulk-upsert.mjs";
 import { createDistributionGuard, filterReferencesKey } from "./distribution.mjs";
 import { STANDARD_REPO_OPTION_KEYS } from "./options.mjs";
 import { runChunkedPurge } from "./purge.mjs";
 import { ReadOnlyRepositoryError, asReadOnlyRepo, isReadOnlyRepo } from "./read-only.mjs";
 import { retryingTransaction } from "./retrying-transaction.mjs";
-export { PLUGIN_ORDER_CONSTRAINTS, ReadOnlyRepositoryError, RepositoryBase, STANDARD_REPO_OPTION_KEYS, asReadOnlyRepo, createDistributionGuard, filterReferencesKey, isReadOnlyRepo, isTransientError, nestDottedKeys, nestDottedKeysAll, retryingTransaction, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };
+export { BULK_UPSERT_ERROR_CODES, BULK_UPSERT_FAILURE_CODES, PLUGIN_ORDER_CONSTRAINTS, ReadOnlyRepositoryError, RepositoryBase, STANDARD_REPO_OPTION_KEYS, asReadOnlyRepo, bulkUpsertOptionsError, createDistributionGuard, filterReferencesKey, isReadOnlyRepo, isTransientError, nestDottedKeys, nestDottedKeysAll, retryingTransaction, runChunkedArchive, runChunkedPurge, summarizeBulkUpsert, throwIfAborted, validatePluginOrder, withRetry };

package/dist/repository/types.d.mts

@@ -4,8 +4,9 @@ import { LookupPopulateOptions, LookupPopulateResult, LookupSpec } from "../look
 import { UpdateInput } from "../update/types.mjs";
 import { RetryPolicy } from "./resilience.mjs";
 import { ArchiveOptions, ArchiveResult, ArchiveSink } from "./archive.mjs";
-import { RepoCapabilities } from "./capabilities.mjs";
 import { CacheOptions } from "../cache/options.mjs";
+import { RepoCapabilities } from "./capabilities.mjs";
+import { BulkUpsertOptions, BulkUpsertResult } from "./bulk-upsert.mjs";
 //#region src/repository/types.d.ts
 /**
  * Accepted filter input across every repository method. A repository
@@ -1622,6 +1623,11 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
    * batches ≤ ~10k ids and chunk beyond.
    */
   getByIds?(ids: readonly string[], options?: FindAllOptions): Promise<Map<string, TDoc>>;
+  /**
+   * Many keyed upserts in one command with an exact per-row outcome (see `./bulk-upsert.ts`).
+   * Optional; gated by `RepoCapabilities.bulkUpsert`.
+   */
+  bulkUpsert?(rows: readonly Record<string, unknown>[], options: BulkUpsertOptions): Promise<BulkUpsertResult>;
   count?(filter?: FilterInput, options?: QueryOptions): Promise<number>;
   exists?(filter: FilterInput, options?: QueryOptions): Promise<boolean | {
     _id: unknown;

package/dist/testing/data-access-conformance.d.mts

@@ -0,0 +1,89 @@
+import { RepoCapabilities } from "../repository/capabilities.mjs";
+import { AggRequest, AggResult } from "../repository/types.mjs";
+import { BulkUpsertOptions, BulkUpsertResult } from "../repository/bulk-upsert.mjs";
+//#region src/testing/data-access-conformance.d.ts
+/** `getByIds(..., { preserveOrder: true })` reached through the kit's own signature. */
+interface OrderedIdsFixture {
+  /** Insert one record per name; returns their ids in the same order. */
+  insert(names: readonly string[]): Promise<string[]>;
+  getOrdered(ids: readonly string[], options: {
+    chunkSize?: number;
+  }): Promise<ReadonlyArray<{
+    name: string;
+  } | undefined>>;
+  /** A well-formed id that matches no record. */
+  missingId: string;
+  cleanup(): Promise<void>;
+}
+/** A tenant-scoped base and a tenant-scoped, soft-deletable sibling it can join. */
+interface ScopedJoinFixture {
+  /** The base repository's portable aggregate. Base rows carry `key`. */
+  aggregate(req: AggRequest, scope: Record<string, unknown>): Promise<AggResult>;
+  /** Name `lookups[].from` takes for the joined sibling. */
+  joined: string;
+  seedBase(tenant: string, keys: readonly string[]): Promise<void>;
+  /** Joined rows carry `key` and `qty`; `deleted` rows are soft-deleted. */
+  seedJoined(tenant: string, rows: ReadonlyArray<{
+    key: string;
+    qty: number;
+    deleted?: boolean;
+  }>): Promise<void>;
+  /** Call options that scope a read to `tenant`. */
+  scope(tenant: string): Record<string, unknown>;
+  cleanup(): Promise<void>;
+}
+/** A tenant-scoped collection keyed uniquely by (tenant, `sku`). Rows: `{ sku, qty, name, firstSeen }`. */
+interface BulkUpsertFixture {
+  bulkUpsert(rows: readonly Record<string, unknown>[], options: BulkUpsertOptions, tenant: string): Promise<BulkUpsertResult>;
+  read(tenant: string): Promise<readonly Record<string, unknown>[]>;
+  /** `bulkUpsert` keyed on `name`, which has NO unique index: must be refused. */
+  bulkUpsertByNonUniqueKey(rows: readonly Record<string, unknown>[], tenant: string): Promise<unknown>;
+  cleanup(): Promise<void>;
+}
+/** Source facts `{ period, rate, tax }` and a totals read model keyed (tenant, period, rate). */
+interface ReadModelFixture {
+  seedSource(tenant: string, rows: ReadonlyArray<{
+    period: string;
+    rate: number;
+    tax: number;
+  }>): Promise<void>;
+  /** Rebuild the tenant's totals from its source facts. */
+  rebuild(tenant: string): Promise<void>;
+  /** The same rebuild, issued inside a transaction: must reject. */
+  rebuildInTransaction(tenant: string): Promise<unknown>;
+  /** Drift between the source-derived totals and the read model, for the tenant. */
+  reconcile(tenant: string): Promise<ReadonlyArray<{
+    key: Record<string, unknown>;
+    expected: unknown;
+    actual: unknown;
+  }>>;
+  /** Corrupt one stored total. */
+  tamper(tenant: string, period: string, rate: number): Promise<void>;
+  /** Apply increments in one unit of work; a repeated dedupeKey must count once. */
+  applyIncrements(tenant: string, grains: ReadonlyArray<{
+    period: string;
+    rate: number;
+    tax: number;
+    dedupeKey: string;
+  }>): Promise<void>;
+  readTotals(tenant: string): Promise<ReadonlyArray<{
+    period: string;
+    rate: number;
+    tax: number;
+  }>>;
+  cleanup(): Promise<void>;
+}
+interface DataAccessConformanceHarness {
+  name: string;
+  features: RepoCapabilities;
+  orderedIds?: () => Promise<OrderedIdsFixture>;
+  scopedJoin?: () => Promise<ScopedJoinFixture>;
+  bulkUpsert?: () => Promise<BulkUpsertFixture>;
+  readModel?: () => Promise<ReadModelFixture>;
+}
+type DataAccessCapability = 'getByIdsOrdered' | 'scopedJoins' | 'bulkUpsert' | 'readModel';
+/** Whether a group runs, is skipped (capability not declared), or fails (declared, no fixture). */
+declare function dataAccessGroupState(features: RepoCapabilities, capability: DataAccessCapability, fixture: unknown): 'run' | 'skip' | 'missing-fixture';
+declare function runDataAccessConformance(harness: DataAccessConformanceHarness): void;
+//#endregion
+export { BulkUpsertFixture, DataAccessCapability, DataAccessConformanceHarness, OrderedIdsFixture, ReadModelFixture, ScopedJoinFixture, dataAccessGroupState, runDataAccessConformance };