@classytic/repo-core 0.29.0 → 0.31.0

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 };

package/dist/testing/data-access-conformance.mjs

@@ -0,0 +1,331 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+//#region src/testing/data-access-conformance.ts
+/**
+* Data-access conformance: behaviour groups a kit OPTS INTO through `RepoCapabilities`.
+*
+* Each group runs only when its capability is declared. An undeclared one is reported as a
+* skipped group whose title names the missing capability (never a silent pass), and a declared
+* capability without its fixture fails, because an unproven declaration is decoration (FL4).
+* Groups: `getByIdsOrdered`, `scopedJoins`, `bulkUpsert`, `readModel`.
+*/
+/** Whether a group runs, is skipped (capability not declared), or fails (declared, no fixture). */
+function dataAccessGroupState(features, capability, fixture) {
+	if (features[capability] !== true) return "skip";
+	return fixture === void 0 ? "missing-fixture" : "run";
+}
+/** A group's fixture lifecycle, owned once here: each case reads the current fixture via `fx()`. */
+function gated(harness, capability, title, fixture, cases) {
+	const state = dataAccessGroupState(harness.features, capability, fixture);
+	let current;
+	const fx = () => {
+		if (!current) throw new Error(`${title}: fixture not built`);
+		return current;
+	};
+	if (state === "skip") {
+		describe.skip(`${title} [skipped: capability '${capability}' not declared]`, () => cases(fx));
+		return;
+	}
+	if (state === "missing-fixture") {
+		describe(title, () => {
+			it(`declares '${capability}' and supplies its fixture`, () => {
+				throw new Error(`${harness.name} declares '${capability}' but supplies no fixture for it`);
+			});
+		});
+		return;
+	}
+	describe(title, () => {
+		beforeEach(async () => {
+			current = await fixture();
+		});
+		afterEach(async () => {
+			await current?.cleanup();
+			current = void 0;
+		});
+		cases(fx);
+	});
+}
+function runDataAccessConformance(harness) {
+	describe(`[data-access conformance] ${harness.name}`, () => {
+		gated(harness, "getByIdsOrdered", "getByIds (ordered, chunked)", harness.orderedIds, (fx) => {
+			it("aligns with the input: misses are undefined, duplicates repeat", async () => {
+				const [a, b] = await fx().insert(["ord-a", "ord-b"]);
+				const out = await fx().getOrdered([
+					b,
+					fx().missingId,
+					a,
+					b
+				], {});
+				expect(out.map((d) => d?.name)).toEqual([
+					"ord-b",
+					void 0,
+					"ord-a",
+					"ord-b"
+				]);
+			});
+			it("gives the same answer at any chunk size", async () => {
+				const names = Array.from({ length: 7 }, (_, i) => `chunk-${i}`);
+				const shuffled = [...await fx().insert(names)].reverse();
+				const one = await fx().getOrdered(shuffled, { chunkSize: 1 });
+				const all = await fx().getOrdered(shuffled, {});
+				expect(one.map((d) => d?.name)).toEqual([...names].reverse());
+				expect(all.map((d) => d?.name)).toEqual(one.map((d) => d?.name));
+			});
+		});
+		gated(harness, "scopedJoins", "scoped joins", harness.scopedJoin, (fx) => {
+			const joinSum = (from) => ({
+				lookups: [{
+					from,
+					localField: "key",
+					foreignField: "key",
+					as: "j"
+				}],
+				groupBy: "key",
+				measures: { n: { op: "count" } }
+			});
+			it("a join reads only the caller tenant live rows of the joined collection", async () => {
+				await fx().seedBase("t-a", ["shared", "b-only"]);
+				await fx().seedBase("t-b", ["shared"]);
+				await fx().seedJoined("t-a", [{
+					key: "shared",
+					qty: 5
+				}, {
+					key: "shared",
+					qty: 99,
+					deleted: true
+				}]);
+				await fx().seedJoined("t-b", [{
+					key: "shared",
+					qty: 7
+				}, {
+					key: "b-only",
+					qty: 3
+				}]);
+				const { rows } = await fx().aggregate({
+					lookups: [{
+						from: fx().joined,
+						localField: "key",
+						foreignField: "key",
+						as: "j",
+						single: true
+					}],
+					groupBy: "key",
+					measures: { qty: {
+						op: "sum",
+						field: "j.qty"
+					} },
+					sort: { key: 1 }
+				}, fx().scope("t-a"));
+				const byKey = Object.fromEntries(rows.map((r) => [String(r["key"]), r["qty"] ?? 0]));
+				expect(byKey["shared"]).toBe(5);
+				expect(byKey["b-only"]).toBe(0);
+			});
+			it("a join into a name the kit cannot resolve is refused, not an empty join", async () => {
+				await fx().seedBase("t-a", ["shared"]);
+				await expect(fx().aggregate(joinSum(fx().joined), fx().scope("t-a"))).resolves.toBeDefined();
+				await expect(fx().aggregate(joinSum(`${fx().joined}_no_such_collection`), fx().scope("t-a"))).rejects.toThrow();
+			});
+		});
+		gated(harness, "bulkUpsert", "bulkUpsert", harness.bulkUpsert, (fx) => {
+			const at = /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z");
+			it("reports inserted, then updated vs unchanged, per row and in order", async () => {
+				const first = await fx().bulkUpsert([{
+					sku: "A",
+					qty: 1,
+					name: "alpha"
+				}, {
+					sku: "B",
+					qty: 2,
+					name: "beta"
+				}], { key: ["sku"] }, "t-a");
+				expect(first.results.map((r) => r.outcome)).toEqual(["inserted", "inserted"]);
+				expect(first.results.map((r) => r.key)).toEqual([{ sku: "A" }, { sku: "B" }]);
+				const second = await fx().bulkUpsert([{
+					sku: "A",
+					qty: 1,
+					name: "alpha"
+				}, {
+					sku: "B",
+					qty: 2,
+					name: "beta-2"
+				}], { key: ["sku"] }, "t-a");
+				expect(second.results.map((r) => r.outcome)).toEqual(["unchanged", "updated"]);
+				expect(second).toMatchObject({
+					inserted: 0,
+					updated: 1,
+					unchanged: 1,
+					failed: 0
+				});
+			});
+			it("inc accumulates and setOnInsert is written once", async () => {
+				const opts = {
+					key: ["sku"],
+					inc: ["qty"],
+					setOnInsert: ["firstSeen"]
+				};
+				await fx().bulkUpsert([{
+					sku: "A",
+					qty: 5,
+					firstSeen: at
+				}], opts, "t-a");
+				await fx().bulkUpsert([{
+					sku: "A",
+					qty: 7,
+					firstSeen: /* @__PURE__ */ new Date("2027-01-01T00:00:00.000Z")
+				}], opts, "t-a");
+				const [row] = await fx().read("t-a");
+				expect(row?.["qty"]).toBe(12);
+				expect(new Date(String(row?.["firstSeen"])).toISOString()).toBe(at.toISOString());
+			});
+			it("the tenant scope is part of the key: another tenant row is never touched", async () => {
+				const opts = {
+					key: ["sku"],
+					inc: ["qty"]
+				};
+				await fx().bulkUpsert([{
+					sku: "A",
+					qty: 1
+				}], opts, "t-b");
+				await fx().bulkUpsert([{
+					sku: "A",
+					qty: 1
+				}], opts, "t-a");
+				await fx().bulkUpsert([{
+					sku: "A",
+					qty: 1
+				}], opts, "t-a");
+				expect((await fx().read("t-a")).map((r) => r["qty"])).toEqual([2]);
+				expect((await fx().read("t-b")).map((r) => r["qty"])).toEqual([1]);
+			});
+			it("a row missing a key field fails alone; the rest land", async () => {
+				const res = await fx().bulkUpsert([{ qty: 1 }, {
+					sku: "C",
+					qty: 3
+				}], { key: ["sku"] }, "t-a");
+				expect(res.results.map((r) => [r.outcome, r.code])).toEqual([["failed", "invalid_row"], ["inserted", void 0]]);
+			});
+			it("a key without a unique index is refused before any write", async () => {
+				await expect(fx().bulkUpsertByNonUniqueKey([{
+					sku: "Z",
+					name: "zed",
+					qty: 1
+				}], "t-a")).rejects.toThrow();
+				expect(await fx().read("t-a")).toHaveLength(0);
+			});
+			it("a field routed twice is refused", async () => {
+				await expect(fx().bulkUpsert([{
+					sku: "A",
+					qty: 1
+				}], {
+					key: ["sku"],
+					inc: ["qty"],
+					set: ["qty"]
+				}, "t-a")).rejects.toThrow();
+			});
+		});
+		gated(harness, "readModel", "read model", harness.readModel, (fx) => {
+			const facts = [
+				{
+					period: "2026-01",
+					rate: 15,
+					tax: 100
+				},
+				{
+					period: "2026-01",
+					rate: 15,
+					tax: 50
+				},
+				{
+					period: "2026-01",
+					rate: 5,
+					tax: 7
+				},
+				{
+					period: "2026-02",
+					rate: 15,
+					tax: 30
+				}
+			];
+			const byGrain = (rows) => rows.map((t) => [
+				t.period,
+				t.rate,
+				t.tax
+			]).sort((a, b) => String(a).localeCompare(String(b)));
+			it("rebuild then reconcile reports zero drift", async () => {
+				await fx().seedSource("t-a", facts);
+				await fx().rebuild("t-a");
+				expect(await fx().reconcile("t-a")).toEqual([]);
+				expect(byGrain(await fx().readTotals("t-a"))).toEqual(byGrain([
+					{
+						period: "2026-01",
+						rate: 15,
+						tax: 150
+					},
+					{
+						period: "2026-01",
+						rate: 5,
+						tax: 7
+					},
+					{
+						period: "2026-02",
+						rate: 15,
+						tax: 30
+					}
+				]));
+			});
+			it("reconcile reports a corrupted total with its expected and actual value", async () => {
+				await fx().seedSource("t-a", facts);
+				await fx().rebuild("t-a");
+				await fx().tamper("t-a", "2026-01", 15);
+				const drift = await fx().reconcile("t-a");
+				expect(drift).toHaveLength(1);
+				expect(drift[0]?.key).toMatchObject({
+					period: "2026-01",
+					rate: 15
+				});
+				expect(drift[0]?.expected).not.toEqual(drift[0]?.actual);
+			});
+			it("rebuilding one tenant never touches another tenant read model", async () => {
+				await fx().seedSource("t-a", facts);
+				await fx().seedSource("t-b", [{
+					period: "2026-01",
+					rate: 15,
+					tax: 1
+				}]);
+				await fx().rebuild("t-b");
+				await fx().rebuild("t-a");
+				expect((await fx().readTotals("t-b")).map((t) => t.tax)).toEqual([1]);
+			});
+			it("applyIncrements counts a repeated dedupeKey once", async () => {
+				await fx().applyIncrements("t-a", [{
+					period: "2026-03",
+					rate: 15,
+					tax: 10,
+					dedupeKey: "e1"
+				}, {
+					period: "2026-03",
+					rate: 15,
+					tax: 5,
+					dedupeKey: "e2"
+				}]);
+				await fx().applyIncrements("t-a", [{
+					period: "2026-03",
+					rate: 15,
+					tax: 10,
+					dedupeKey: "e1"
+				}, {
+					period: "2026-03",
+					rate: 15,
+					tax: 5,
+					dedupeKey: "e3"
+				}]);
+				expect((await fx().readTotals("t-a")).map((t) => t.tax)).toEqual([20]);
+			});
+			it("a rebuild inside a transaction is refused", async () => {
+				await fx().seedSource("t-a", facts);
+				await expect(fx().rebuildInTransaction("t-a")).rejects.toThrow();
+			});
+		});
+	});
+}
+//#endregion
+export { dataAccessGroupState, runDataAccessConformance };

package/dist/testing/index.d.mts

@@ -1,9 +1,15 @@
 import { AggregateOpsSupport } from "../repository/capabilities.mjs";
+import { ChangeLogConformanceHarness, changeLogStoreCases, runChangeLogStoreConformance } from "./change-log-conformance.mjs";
+import { CommandStreamConformanceHarness, commandStreamStoreCases, runCommandStreamStoreConformance } from "./command-stream-conformance.mjs";
 import { ConformanceContext, ConformanceDoc, ConformanceFeatures, ConformanceHarness } from "./types.mjs";
 import { runStandardRepoConformance } from "./conformance.mjs";
+import { BulkUpsertFixture, DataAccessCapability, DataAccessConformanceHarness, OrderedIdsFixture, ReadModelFixture, ScopedJoinFixture, dataAccessGroupState, runDataAccessConformance } from "./data-access-conformance.mjs";
 import { IdempotencyConformanceHarness, idempotencyStoreCases, runIdempotencyStoreConformance } from "./idempotency-conformance.mjs";
 import { LockConformanceHarness, runLockAdapterConformance } from "./lock-conformance.mjs";
+import { MergeKeysetFixture, MergeKeysetHarness, runMergeKeysetConformance } from "./merge-keyset-conformance.mjs";
+import { PaginationPropertyFixture, PaginationPropertyHarness, PropertyRow, runPaginationPropertyConformance } from "./pagination-property-conformance.mjs";
 import { PurgeConformanceContext, PurgeConformanceHarness, runPurgeConformance } from "./purge-conformance.mjs";
 import { QUERY_GRAMMAR_DOCS, QUERY_GRAMMAR_FILTER_CASES, QUERY_GRAMMAR_PAGING_CASES, QUERY_GRAMMAR_REFUSED, QueryGrammarCaseOptions, QueryGrammarConformanceOptions, QueryGrammarHarness, QueryGrammarParsed, runQueryGrammarConformance } from "./query-grammar-conformance.mjs";
+import { ReadModelPropertyHarness, runReadModelPropertyConformance } from "./read-model-property-conformance.mjs";
 import { UsageConformanceHarness, runUsageStoreContract } from "./usage-conformance.mjs";
-export { type AggregateOpsSupport, type ConformanceContext, type ConformanceDoc, type ConformanceFeatures, type ConformanceHarness, type IdempotencyConformanceHarness, type LockConformanceHarness, type PurgeConformanceContext, type PurgeConformanceHarness, QUERY_GRAMMAR_DOCS, QUERY_GRAMMAR_FILTER_CASES, QUERY_GRAMMAR_PAGING_CASES, QUERY_GRAMMAR_REFUSED, type QueryGrammarCaseOptions, type QueryGrammarConformanceOptions, type QueryGrammarHarness, type QueryGrammarParsed, type UsageConformanceHarness, idempotencyStoreCases, runIdempotencyStoreConformance, runLockAdapterConformance, runPurgeConformance, runQueryGrammarConformance, runStandardRepoConformance, runUsageStoreContract };
+export { type AggregateOpsSupport, type BulkUpsertFixture, type ChangeLogConformanceHarness, type CommandStreamConformanceHarness, type ConformanceContext, type ConformanceDoc, type ConformanceFeatures, type ConformanceHarness, type DataAccessCapability, type DataAccessConformanceHarness, type IdempotencyConformanceHarness, type LockConformanceHarness, type MergeKeysetFixture, type MergeKeysetHarness, type OrderedIdsFixture, type PaginationPropertyFixture, type PaginationPropertyHarness, type PropertyRow, type PurgeConformanceContext, type PurgeConformanceHarness, QUERY_GRAMMAR_DOCS, QUERY_GRAMMAR_FILTER_CASES, QUERY_GRAMMAR_PAGING_CASES, QUERY_GRAMMAR_REFUSED, type QueryGrammarCaseOptions, type QueryGrammarConformanceOptions, type QueryGrammarHarness, type QueryGrammarParsed, type ReadModelFixture, type ReadModelPropertyHarness, type ScopedJoinFixture, type UsageConformanceHarness, changeLogStoreCases, commandStreamStoreCases, dataAccessGroupState, idempotencyStoreCases, runChangeLogStoreConformance, runCommandStreamStoreConformance, runDataAccessConformance, runIdempotencyStoreConformance, runLockAdapterConformance, runMergeKeysetConformance, runPaginationPropertyConformance, runPurgeConformance, runQueryGrammarConformance, runReadModelPropertyConformance, runStandardRepoConformance, runUsageStoreContract };

package/dist/testing/index.mjs

@@ -1,7 +1,13 @@
+import { changeLogStoreCases, runChangeLogStoreConformance } from "./change-log-conformance.mjs";
+import { commandStreamStoreCases, runCommandStreamStoreConformance } from "./command-stream-conformance.mjs";
 import { runStandardRepoConformance } from "./conformance.mjs";
+import { dataAccessGroupState, runDataAccessConformance } from "./data-access-conformance.mjs";
 import { idempotencyStoreCases, runIdempotencyStoreConformance } from "./idempotency-conformance.mjs";
 import { runLockAdapterConformance } from "./lock-conformance.mjs";
+import { runMergeKeysetConformance } from "./merge-keyset-conformance.mjs";
+import { runPaginationPropertyConformance } from "./pagination-property-conformance.mjs";
 import { runPurgeConformance } from "./purge-conformance.mjs";
 import { QUERY_GRAMMAR_DOCS, QUERY_GRAMMAR_FILTER_CASES, QUERY_GRAMMAR_PAGING_CASES, QUERY_GRAMMAR_REFUSED, runQueryGrammarConformance } from "./query-grammar-conformance.mjs";
+import { runReadModelPropertyConformance } from "./read-model-property-conformance.mjs";
 import { runUsageStoreContract } from "./usage-conformance.mjs";
-export { QUERY_GRAMMAR_DOCS, QUERY_GRAMMAR_FILTER_CASES, QUERY_GRAMMAR_PAGING_CASES, QUERY_GRAMMAR_REFUSED, idempotencyStoreCases, runIdempotencyStoreConformance, runLockAdapterConformance, runPurgeConformance, runQueryGrammarConformance, runStandardRepoConformance, runUsageStoreContract };
+export { QUERY_GRAMMAR_DOCS, QUERY_GRAMMAR_FILTER_CASES, QUERY_GRAMMAR_PAGING_CASES, QUERY_GRAMMAR_REFUSED, changeLogStoreCases, commandStreamStoreCases, dataAccessGroupState, idempotencyStoreCases, runChangeLogStoreConformance, runCommandStreamStoreConformance, runDataAccessConformance, runIdempotencyStoreConformance, runLockAdapterConformance, runMergeKeysetConformance, runPaginationPropertyConformance, runPurgeConformance, runQueryGrammarConformance, runReadModelPropertyConformance, runStandardRepoConformance, runUsageStoreContract };

package/dist/testing/merge-keyset-conformance.d.mts

@@ -0,0 +1,26 @@
+import { RepoCapabilities } from "../repository/capabilities.mjs";
+import { KeysetSource } from "../pagination/merge-keyset.mjs";
+//#region src/testing/merge-keyset-conformance.d.ts
+interface MergeKeysetFixture {
+  /** Insert into source 0 or 1; `k` is a small integer sort key (ties expected), `label` unique. */
+  insert(source: 0 | 1, rows: ReadonlyArray<{
+    k: number;
+    label: string;
+  }>): Promise<void>;
+  /** Fresh sources over the two collections, in source order. */
+  sources(): readonly KeysetSource<unknown>[];
+  sort: Readonly<Record<string, 1 | -1>>;
+  labelOf(row: unknown): string;
+  /** The sort key of a row, comparable as a number (larger first: the sort is descending). */
+  keyOf(row: unknown): number;
+  cleanup(): Promise<void>;
+}
+interface MergeKeysetHarness {
+  name: string;
+  features: RepoCapabilities;
+  fixture?: () => Promise<MergeKeysetFixture>;
+  numRuns?: number;
+}
+declare function runMergeKeysetConformance(harness: MergeKeysetHarness): void;
+//#endregion
+export { MergeKeysetFixture, MergeKeysetHarness, runMergeKeysetConformance };

package/dist/testing/merge-keyset-conformance.mjs

@@ -0,0 +1,85 @@
+import { mergeKeysetPages } from "../pagination/merge-keyset.mjs";
+import { describe, expect, it } from "vitest";
+import fc from "fast-check";
+//#region src/testing/merge-keyset-conformance.ts
+/**
+* `mergeKeysetPages` over a kit's real sources (fast-check), gated by
+* `RepoCapabilities.mergeKeyset`: two sources ordered by the same total order (descending key),
+* merged to the end, equal the sorted union with every row once, also when rows are inserted
+* between pages. An undeclared capability is a skipped group naming it.
+*/
+function runMergeKeysetConformance(harness) {
+	const title = `[merge keyset] ${harness.name}`;
+	if (harness.features.mergeKeyset !== true) {
+		describe.skip(`${title} [skipped: capability 'mergeKeyset' not declared]`, () => {
+			it("skipped", () => void 0);
+		});
+		return;
+	}
+	describe(title, () => {
+		if (!harness.fixture) {
+			it("declares 'mergeKeyset' and supplies its fixture", () => {
+				throw new Error(`${harness.name} declares 'mergeKeyset' but supplies no fixture`);
+			});
+			return;
+		}
+		const make = harness.fixture;
+		it("a merged walk equals the sorted union, each row once, with inserts between pages", async () => {
+			await fc.assert(fc.asyncProperty(fc.array(fc.integer({
+				min: 0,
+				max: 5
+			}), { maxLength: 12 }), fc.array(fc.integer({
+				min: 0,
+				max: 5
+			}), { maxLength: 12 }), fc.integer({
+				min: 1,
+				max: 5
+			}), fc.array(fc.tuple(fc.constantFrom(0, 1), fc.integer({
+				min: 0,
+				max: 5
+			})), { maxLength: 4 }), async (a, b, limit, inserts) => {
+				const f = await make();
+				try {
+					await f.insert(0, a.map((k, i) => ({
+						k,
+						label: `a${i}`
+					})));
+					await f.insert(1, b.map((k, i) => ({
+						k,
+						label: `b${i}`
+					})));
+					const seen = [];
+					let cursor;
+					for (let step = 0; step < 200; step++) {
+						const page = await mergeKeysetPages(f.sources(), {
+							sort: f.sort,
+							limit,
+							...cursor ? { cursor } : {}
+						});
+						seen.push(...page.docs.map((d) => ({
+							label: f.labelOf(d.row),
+							key: f.keyOf(d.row)
+						})));
+						const ins = inserts[step];
+						if (ins) await f.insert(ins[0], [{
+							k: ins[1],
+							label: `z${step}`
+						}]);
+						if (!page.hasNext) break;
+						cursor = page.next ?? void 0;
+					}
+					const labels = seen.map((s) => s.label);
+					expect(new Set(labels).size).toBe(labels.length);
+					for (let i = 0; i < a.length; i++) expect(labels).toContain(`a${i}`);
+					for (let i = 0; i < b.length; i++) expect(labels).toContain(`b${i}`);
+					const keys = seen.map((s) => s.key);
+					expect(keys).toEqual([...keys].sort((x, y) => y - x));
+				} finally {
+					await f.cleanup();
+				}
+			}), { numRuns: harness.numRuns ?? 15 });
+		});
+	});
+}
+//#endregion
+export { runMergeKeysetConformance };

package/dist/testing/pagination-property-conformance.d.mts

@@ -0,0 +1,44 @@
+import { RepoCapabilities } from "../repository/capabilities.mjs";
+//#region src/testing/pagination-property-conformance.d.ts
+interface PropertyRow {
+  id: string;
+  k: number | null;
+  s: string;
+}
+interface PaginationPropertyFixture {
+  /** Insert rows (`k` may be null); returns their ids in order. */
+  insert(rows: ReadonlyArray<{
+    k: number | null;
+    s: string;
+  }>): Promise<string[]>;
+  update(id: string, k: number | null): Promise<void>;
+  remove(id: string): Promise<void>;
+  keysetPage(params: {
+    sort: Record<string, 1 | -1>;
+    limit: number;
+    after?: string;
+  }): Promise<{
+    data: PropertyRow[];
+    next: string | null;
+  }>;
+  offsetPage(params: {
+    sort: Record<string, 1 | -1>;
+    page: number;
+    limit: number;
+  }): Promise<{
+    data: PropertyRow[];
+  }>;
+  /** Remove every row (called between property runs). */
+  reset(): Promise<void>;
+  cleanup(): Promise<void>;
+}
+interface PaginationPropertyHarness {
+  name: string;
+  features: RepoCapabilities;
+  fixture?: () => Promise<PaginationPropertyFixture>;
+  /** fast-check runs per property. Default 15. */
+  numRuns?: number;
+}
+declare function runPaginationPropertyConformance(harness: PaginationPropertyHarness): void;
+//#endregion
+export { PaginationPropertyFixture, PaginationPropertyHarness, PropertyRow, runPaginationPropertyConformance };