@classytic/repo-core 0.3.0 → 0.4.1

package/dist/testing/conformance.mjs

@@ -25,6 +25,15 @@ function isoAt(offsetSeconds) {
 	return new Date(Date.UTC(2026, 3, 1) + offsetSeconds * 1e3).toISOString();
 }
 function runStandardRepoConformance(harness) {
+	const ops = harness.features.aggregateOps;
+	const aggGate = harness.features.aggregate;
+	const skipNoAgg = !aggGate;
+	const skipNoTopN = !aggGate || !ops?.topN;
+	const skipNoPercentile = !aggGate || !ops?.percentile;
+	const skipNoCustomBuckets = !aggGate || !ops?.customDateBuckets;
+	const skipNoSubMinuteBuckets = !aggGate || !ops?.dateBucketSubMinute;
+	const skipNoStddev = !aggGate || !ops?.stddev;
+	const skipNoCache = !aggGate || !ops?.cache;
 	describe(`[conformance] ${harness.name}`, () => {
 		let ctx;
 		beforeEach(async () => {
@@ -67,10 +76,12 @@ function runStandardRepoConformance(harness) {
 				expect((await ctx.repo.update(id, { count: 99 }))?.count).toBe(99);
 				expect(await ctx.repo.update("no-such-id", { count: 1 })).toBeNull();
 			});
-			it("delete by id succeeds; second delete returns success:false", async () => {
+			it("delete by id succeeds; second delete returns null (miss)", async () => {
 				const id = idOf(await ctx.repo.create(harness.makeDoc({ name: "Carol" })), harness.idField);
-				expect((await ctx.repo.delete(id)).success).toBe(true);
-				expect((await ctx.repo.delete(id)).success).toBe(false);
+				const first = await ctx.repo.delete(id);
+				expect(first).not.toBeNull();
+				expect(first?.message).toBeDefined();
+				expect(await ctx.repo.delete(id)).toBeNull();
 			});
 		});
 		describe("findOneAndUpdate", () => {
@@ -241,7 +252,7 @@ function runStandardRepoConformance(harness) {
 					})
 				]);
 			});
-			it.skipIf(!harness.features.aggregate)("empty result set returns { rows: [] } (no throw)", async () => {
+			it.skipIf(skipNoAgg)("empty result set returns { rows: [] } (no throw)", async () => {
 				if (!ctx.repo.aggregate) return;
 				expect((await ctx.repo.aggregate({
 					filter: { category: "does-not-exist" },
@@ -252,7 +263,7 @@ function runStandardRepoConformance(harness) {
 					} }
 				})).rows).toEqual([]);
 			});
-			it.skipIf(!harness.features.aggregate)("groupBy + sum produces one row per group with correct totals", async () => {
+			it.skipIf(skipNoAgg)("groupBy + sum produces one row per group with correct totals", async () => {
 				if (!ctx.repo.aggregate) return;
 				const result = await ctx.repo.aggregate({
 					groupBy: "category",
@@ -268,7 +279,7 @@ function runStandardRepoConformance(harness) {
 				expect(byCategory["admin"]).toBe(70);
 				expect(byCategory["reader"]).toBe(30);
 			});
-			it.skipIf(!harness.features.aggregate)("scalar aggregate (no groupBy) returns single row", async () => {
+			it.skipIf(skipNoAgg)("scalar aggregate (no groupBy) returns single row", async () => {
 				if (!ctx.repo.aggregate) return;
 				const result = await ctx.repo.aggregate({ measures: {
 					total: {
@@ -281,7 +292,7 @@ function runStandardRepoConformance(harness) {
 				expect(Number(result.rows[0]?.total)).toBe(100);
 				expect(Number(result.rows[0]?.n)).toBe(4);
 			});
-			it.skipIf(!harness.features.aggregate)("having filters aggregated rows by measure alias", async () => {
+			it.skipIf(skipNoAgg)("having filters aggregated rows by measure alias", async () => {
 				if (!ctx.repo.aggregate) return;
 				const result = await ctx.repo.aggregate({
 					groupBy: "category",
@@ -294,6 +305,640 @@ function runStandardRepoConformance(harness) {
 				expect(result.rows).toHaveLength(1);
 				expect(result.rows[0].category).toBe("admin");
 			});
+			it.skipIf(skipNoAgg)("filtered sum/count: KPI tiles side-by-side", async () => {
+				if (!ctx.repo.aggregate) return;
+				expect((await ctx.repo.aggregate({
+					groupBy: "category",
+					measures: {
+						activeCount: {
+							op: "count",
+							where: eq("active", true)
+						},
+						inactiveCount: {
+							op: "count",
+							where: eq("active", false)
+						},
+						activeTotal: {
+							op: "sum",
+							field: "count",
+							where: eq("active", true)
+						},
+						grandTotal: {
+							op: "sum",
+							field: "count"
+						}
+					},
+					sort: { category: 1 }
+				})).rows).toEqual([{
+					category: "admin",
+					activeCount: 1,
+					inactiveCount: 1,
+					activeTotal: 40,
+					grandTotal: 70
+				}, {
+					category: "reader",
+					activeCount: 2,
+					inactiveCount: 0,
+					activeTotal: 30,
+					grandTotal: 30
+				}]);
+			});
+			it.skipIf(skipNoAgg)("filtered avg ignores non-matching rows (no bias toward 0)", async () => {
+				if (!ctx.repo.aggregate) return;
+				const result = await ctx.repo.aggregate({
+					filter: eq("category", "admin"),
+					measures: { avgActive: {
+						op: "avg",
+						field: "count",
+						where: eq("active", true)
+					} }
+				});
+				expect(Number(result.rows[0]?.avgActive)).toBe(40);
+			});
+			it.skipIf(skipNoTopN)("top-N: keep top 1 per category by count", async () => {
+				if (!ctx.repo.aggregate) return;
+				expect((await ctx.repo.aggregate({
+					groupBy: ["category", "name"],
+					measures: { n: {
+						op: "sum",
+						field: "count"
+					} },
+					topN: {
+						partitionBy: "category",
+						sortBy: { n: -1 },
+						limit: 1
+					},
+					sort: { category: 1 }
+				})).rows).toEqual([{
+					category: "admin",
+					name: "d",
+					n: 40
+				}, {
+					category: "reader",
+					name: "b",
+					n: 20
+				}]);
+			});
+			it.skipIf(skipNoTopN)("top-N: row_number ties strategy yields exactly N rows per partition", async () => {
+				if (!ctx.repo.aggregate) return;
+				expect((await ctx.repo.aggregate({
+					groupBy: ["category", "name"],
+					measures: { n: { op: "count" } },
+					topN: {
+						partitionBy: "category",
+						sortBy: { name: 1 },
+						limit: 1,
+						ties: "row_number"
+					},
+					sort: { category: 1 }
+				})).rows.map((r) => `${r.category}:${r.name}`)).toEqual(["admin:c", "reader:a"]);
+			});
+			it.skipIf(skipNoTopN)("top-N: throws on partitionBy referencing an unknown column", async () => {
+				if (!ctx.repo.aggregate) return;
+				await expect(ctx.repo.aggregate({
+					groupBy: "category",
+					measures: { n: { op: "count" } },
+					topN: {
+						partitionBy: "does-not-exist",
+						sortBy: { n: -1 },
+						limit: 1
+					}
+				})).rejects.toThrow(/topN\.partitionBy "does-not-exist"/);
+			});
+			it.skipIf(skipNoPercentile)("percentile: P50 / P95 / P99 over a uniform distribution", async () => {
+				if (!ctx.repo.aggregate) return;
+				for (let i = 1; i <= 100; i++) await ctx.repo.create(harness.makeDoc({
+					name: `p${i}`,
+					category: "pct",
+					count: i
+				}));
+				const row = (await ctx.repo.aggregate({
+					filter: eq("category", "pct"),
+					measures: {
+						p50: {
+							op: "percentile",
+							field: "count",
+							p: .5
+						},
+						p95: {
+							op: "percentile",
+							field: "count",
+							p: .95
+						},
+						p99: {
+							op: "percentile",
+							field: "count",
+							p: .99
+						}
+					}
+				})).rows[0];
+				expect(Number(row.p50)).toBeGreaterThanOrEqual(48);
+				expect(Number(row.p50)).toBeLessThanOrEqual(52);
+				expect(Number(row.p95)).toBeGreaterThanOrEqual(93);
+				expect(Number(row.p95)).toBeLessThanOrEqual(97);
+				expect(Number(row.p99)).toBeGreaterThanOrEqual(97);
+				expect(Number(row.p99)).toBeLessThanOrEqual(100);
+			});
+			it.skipIf(skipNoPercentile)("percentile: rejects p outside [0, 1]", async () => {
+				if (!ctx.repo.aggregate) return;
+				await expect(ctx.repo.aggregate({ measures: { bad: {
+					op: "percentile",
+					field: "count",
+					p: 1.5
+				} } })).rejects.toThrow(/percentile/);
+			});
+			it.skipIf(skipNoStddev)("stddev (sample) matches numpy.std(ddof=1) over [2, 4, 4, 4, 5, 5, 7, 9]", async () => {
+				if (!ctx.repo.aggregate) return;
+				for (const value of [
+					2,
+					4,
+					4,
+					4,
+					5,
+					5,
+					7,
+					9
+				]) await ctx.repo.create(harness.makeDoc({
+					name: `s${value}`,
+					category: "std",
+					count: value
+				}));
+				const result = await ctx.repo.aggregate({
+					filter: eq("category", "std"),
+					measures: { s: {
+						op: "stddev",
+						field: "count"
+					} }
+				});
+				expect(Number(result.rows[0]?.s)).toBeCloseTo(2.138, 2);
+			});
+			it.skipIf(skipNoStddev)("stddevPop (population) matches numpy.std(ddof=0) over the same set", async () => {
+				if (!ctx.repo.aggregate) return;
+				for (const value of [
+					2,
+					4,
+					4,
+					4,
+					5,
+					5,
+					7,
+					9
+				]) await ctx.repo.create(harness.makeDoc({
+					name: `p${value}`,
+					category: "pop",
+					count: value
+				}));
+				const result = await ctx.repo.aggregate({
+					filter: eq("category", "pop"),
+					measures: { s: {
+						op: "stddevPop",
+						field: "count"
+					} }
+				});
+				expect(Number(result.rows[0]?.s)).toBeCloseTo(2, 6);
+			});
+			it.skipIf(skipNoCache)("cache hit: same call within staleTime returns cached value (no DB re-read)", async () => {
+				const cachedRepo = ctx.cachedRepo;
+				if (!cachedRepo || !cachedRepo.aggregate) return;
+				await cachedRepo.create(harness.makeDoc({
+					name: "c1",
+					category: "cache",
+					count: 100
+				}));
+				const first = await cachedRepo.aggregate({
+					filter: eq("category", "cache"),
+					measures: { sum: {
+						op: "sum",
+						field: "count"
+					} },
+					cache: { staleTime: 60 }
+				});
+				expect(Number(first.rows[0]?.sum)).toBe(100);
+				const second = await cachedRepo.aggregate({
+					filter: eq("category", "cache"),
+					measures: { sum: {
+						op: "sum",
+						field: "count"
+					} },
+					cache: { staleTime: 60 }
+				});
+				expect(Number(second.rows[0]?.sum)).toBe(100);
+			});
+			it.skipIf(skipNoCache)("write invalidates the cache: subsequent read sees the fresh result", async () => {
+				const cachedRepo = ctx.cachedRepo;
+				if (!cachedRepo || !cachedRepo.aggregate) return;
+				await cachedRepo.create(harness.makeDoc({
+					name: "wi1",
+					category: "wi",
+					count: 100
+				}));
+				const first = await cachedRepo.aggregate({
+					filter: eq("category", "wi"),
+					measures: { sum: {
+						op: "sum",
+						field: "count"
+					} },
+					cache: { staleTime: 60 }
+				});
+				expect(Number(first.rows[0]?.sum)).toBe(100);
+				await cachedRepo.create(harness.makeDoc({
+					name: "wi2",
+					category: "wi",
+					count: 999
+				}));
+				const second = await cachedRepo.aggregate({
+					filter: eq("category", "wi"),
+					measures: { sum: {
+						op: "sum",
+						field: "count"
+					} },
+					cache: { staleTime: 60 }
+				});
+				expect(Number(second.rows[0]?.sum)).toBe(1099);
+			});
+			it.skipIf(skipNoCache)("bypass: forces fresh fetch + overwrites cached entry", async () => {
+				const cachedRepo = ctx.cachedRepo;
+				if (!cachedRepo || !cachedRepo.aggregate) return;
+				await cachedRepo.create(harness.makeDoc({
+					name: "b1",
+					category: "bp",
+					count: 50
+				}));
+				await cachedRepo.aggregate({
+					filter: eq("category", "bp"),
+					measures: { sum: {
+						op: "sum",
+						field: "count"
+					} },
+					cache: { staleTime: 60 }
+				});
+				await cachedRepo.create(harness.makeDoc({
+					name: "b2",
+					category: "bp",
+					count: 100
+				}));
+				const fresh = await cachedRepo.aggregate({
+					filter: eq("category", "bp"),
+					measures: { sum: {
+						op: "sum",
+						field: "count"
+					} },
+					cache: {
+						staleTime: 60,
+						bypass: true
+					}
+				});
+				expect(Number(fresh.rows[0]?.sum)).toBe(150);
+			});
+			it.skipIf(skipNoCache)("tag invalidation via repo.cache.invalidateByTags clears matching entries", async () => {
+				const cachedRepo = ctx.cachedRepo;
+				if (!cachedRepo || !cachedRepo.aggregate) return;
+				await cachedRepo.create(harness.makeDoc({
+					name: "i1",
+					category: "inv",
+					count: 10
+				}));
+				await cachedRepo.aggregate({
+					filter: eq("category", "inv"),
+					measures: { sum: {
+						op: "sum",
+						field: "count"
+					} },
+					cache: {
+						staleTime: 60,
+						tags: ["inv-tag"]
+					}
+				});
+				const handle = cachedRepo.cache;
+				if (!handle) return;
+				expect(await handle.invalidateByTags(["inv-tag"])).toBeGreaterThanOrEqual(1);
+			});
+		});
+		describe("aggregate — date buckets + keyset", () => {
+			const BUCKET_CATS = ["bk-paid", "bk-pending"];
+			const KEYSET_CATS = [
+				"ks-a",
+				"ks-b",
+				"ks-c",
+				"ks-d",
+				"ks-e"
+			];
+			beforeEach(async () => {
+				await ctx.repo.createMany([
+					harness.makeDoc({
+						name: "bk1",
+						category: "bk-paid",
+						count: 100,
+						createdAt: "2026-01-15T10:00:00Z"
+					}),
+					harness.makeDoc({
+						name: "bk2",
+						category: "bk-paid",
+						count: 200,
+						createdAt: "2026-01-22T10:00:00Z"
+					}),
+					harness.makeDoc({
+						name: "bk3",
+						category: "bk-paid",
+						count: 300,
+						createdAt: "2026-02-05T10:00:00Z"
+					}),
+					harness.makeDoc({
+						name: "bk4",
+						category: "bk-pending",
+						count: 50,
+						createdAt: "2026-02-05T10:00:00Z"
+					}),
+					harness.makeDoc({
+						name: "bk5",
+						category: "bk-paid",
+						count: 400,
+						createdAt: "2026-04-10T10:00:00Z"
+					}),
+					harness.makeDoc({
+						name: "bk6",
+						category: "bk-paid",
+						count: 500,
+						createdAt: "2026-07-20T10:00:00Z"
+					})
+				]);
+				for (let i = 0; i < KEYSET_CATS.length; i++) {
+					const cat = KEYSET_CATS[i];
+					await ctx.repo.create(harness.makeDoc({
+						name: cat,
+						category: cat,
+						count: 10 + i * 10
+					}));
+				}
+			});
+			it.skipIf(skipNoAgg)("date bucket month groups rows under YYYY-MM labels", async () => {
+				if (!ctx.repo.aggregate) return;
+				expect((await ctx.repo.aggregate({
+					filter: { category: "bk-paid" },
+					dateBuckets: { month: {
+						field: "createdAt",
+						interval: "month"
+					} },
+					measures: { revenue: {
+						op: "sum",
+						field: "count"
+					} },
+					sort: { month: 1 }
+				})).rows).toEqual([
+					{
+						month: "2026-01",
+						revenue: 300
+					},
+					{
+						month: "2026-02",
+						revenue: 300
+					},
+					{
+						month: "2026-04",
+						revenue: 400
+					},
+					{
+						month: "2026-07",
+						revenue: 500
+					}
+				]);
+			});
+			it.skipIf(skipNoAgg)("date bucket day emits YYYY-MM-DD", async () => {
+				if (!ctx.repo.aggregate) return;
+				expect((await ctx.repo.aggregate({
+					filter: { category: "bk-paid" },
+					dateBuckets: { day: {
+						field: "createdAt",
+						interval: "day"
+					} },
+					measures: { n: { op: "count" } },
+					sort: { day: 1 }
+				})).rows.map((r) => r.day)).toEqual([
+					"2026-01-15",
+					"2026-01-22",
+					"2026-02-05",
+					"2026-04-10",
+					"2026-07-20"
+				]);
+			});
+			it.skipIf(skipNoAgg)("date bucket quarter emits YYYY-Qn", async () => {
+				if (!ctx.repo.aggregate) return;
+				expect((await ctx.repo.aggregate({
+					filter: { category: "bk-paid" },
+					dateBuckets: { q: {
+						field: "createdAt",
+						interval: "quarter"
+					} },
+					measures: { n: { op: "count" } },
+					sort: { q: 1 }
+				})).rows).toEqual([
+					{
+						q: "2026-Q1",
+						n: 3
+					},
+					{
+						q: "2026-Q2",
+						n: 1
+					},
+					{
+						q: "2026-Q3",
+						n: 1
+					}
+				]);
+			});
+			it.skipIf(skipNoAgg)("date bucket year emits YYYY", async () => {
+				if (!ctx.repo.aggregate) return;
+				expect((await ctx.repo.aggregate({
+					filter: { category: "bk-paid" },
+					dateBuckets: { year: {
+						field: "createdAt",
+						interval: "year"
+					} },
+					measures: { n: { op: "count" } }
+				})).rows).toEqual([{
+					year: "2026",
+					n: 5
+				}]);
+			});
+			it.skipIf(skipNoCustomBuckets)("custom 15-minute bins", async () => {
+				if (!ctx.repo.aggregate) return;
+				await ctx.repo.createMany([
+					harness.makeDoc({
+						name: "q1",
+						category: "bk2",
+						count: 1,
+						createdAt: "2026-04-15T10:00:00Z"
+					}),
+					harness.makeDoc({
+						name: "q2",
+						category: "bk2",
+						count: 1,
+						createdAt: "2026-04-15T10:14:00Z"
+					}),
+					harness.makeDoc({
+						name: "q3",
+						category: "bk2",
+						count: 1,
+						createdAt: "2026-04-15T10:15:00Z"
+					}),
+					harness.makeDoc({
+						name: "q4",
+						category: "bk2",
+						count: 1,
+						createdAt: "2026-04-15T10:29:00Z"
+					}),
+					harness.makeDoc({
+						name: "q5",
+						category: "bk2",
+						count: 1,
+						createdAt: "2026-04-15T10:30:00Z"
+					})
+				]);
+				expect((await ctx.repo.aggregate({
+					filter: eq("category", "bk2"),
+					dateBuckets: { bin: {
+						field: "createdAt",
+						interval: {
+							every: 15,
+							unit: "minute"
+						}
+					} },
+					measures: { n: { op: "count" } },
+					sort: { bin: 1 }
+				})).rows).toEqual([
+					{
+						bin: "2026-04-15T10:00",
+						n: 2
+					},
+					{
+						bin: "2026-04-15T10:15",
+						n: 2
+					},
+					{
+						bin: "2026-04-15T10:30",
+						n: 1
+					}
+				]);
+			});
+			it.skipIf(skipNoSubMinuteBuckets)("named hour bucket emits YYYY-MM-DDTHH:00", async () => {
+				if (!ctx.repo.aggregate) return;
+				await ctx.repo.createMany([
+					harness.makeDoc({
+						name: "h1",
+						category: "bk3",
+						count: 1,
+						createdAt: "2026-04-15T10:15:00Z"
+					}),
+					harness.makeDoc({
+						name: "h2",
+						category: "bk3",
+						count: 1,
+						createdAt: "2026-04-15T10:45:00Z"
+					}),
+					harness.makeDoc({
+						name: "h3",
+						category: "bk3",
+						count: 1,
+						createdAt: "2026-04-15T11:05:00Z"
+					})
+				]);
+				expect((await ctx.repo.aggregate({
+					filter: eq("category", "bk3"),
+					dateBuckets: { hour: {
+						field: "createdAt",
+						interval: "hour"
+					} },
+					measures: { n: { op: "count" } },
+					sort: { hour: 1 }
+				})).rows).toEqual([{
+					hour: "2026-04-15T10:00",
+					n: 2
+				}, {
+					hour: "2026-04-15T11:00",
+					n: 1
+				}]);
+			});
+			it.skipIf(skipNoAgg)("date bucket combines with groupBy column", async () => {
+				if (!ctx.repo.aggregate) return;
+				expect((await ctx.repo.aggregate({
+					filter: in_("category", [...BUCKET_CATS]),
+					dateBuckets: { month: {
+						field: "createdAt",
+						interval: "month"
+					} },
+					groupBy: "category",
+					measures: { n: { op: "count" } },
+					sort: {
+						month: 1,
+						category: 1
+					}
+				})).rows).toEqual([
+					{
+						month: "2026-01",
+						category: "bk-paid",
+						n: 2
+					},
+					{
+						month: "2026-02",
+						category: "bk-paid",
+						n: 1
+					},
+					{
+						month: "2026-02",
+						category: "bk-pending",
+						n: 1
+					},
+					{
+						month: "2026-04",
+						category: "bk-paid",
+						n: 1
+					},
+					{
+						month: "2026-07",
+						category: "bk-paid",
+						n: 1
+					}
+				]);
+			});
+			it.skipIf(skipNoAgg)("aggregatePaginate keyset walks all groups via cursor", async () => {
+				if (!ctx.repo.aggregatePaginate) return;
+				const seen = [];
+				let cursor = null;
+				const aggregatePaginate = ctx.repo.aggregatePaginate.bind(ctx.repo);
+				for (let i = 0; i < 10; i++) {
+					const result = await aggregatePaginate({
+						filter: in_("category", [...KEYSET_CATS]),
+						groupBy: "category",
+						measures: { n: { op: "count" } },
+						sort: { category: 1 },
+						pagination: "keyset",
+						limit: 2,
+						...cursor ? { after: cursor } : {}
+					});
+					expect(result.method).toBe("keyset");
+					if (result.method !== "keyset") throw new Error("expected keyset envelope");
+					for (const row of result.data) seen.push(row.category);
+					cursor = result.next;
+					if (!result.hasMore) break;
+				}
+				expect(seen).toEqual([...KEYSET_CATS]);
+			});
+			it.skipIf(skipNoAgg)("aggregatePaginate keyset hasMore is false on the final page", async () => {
+				if (!ctx.repo.aggregatePaginate) return;
+				const result = await ctx.repo.aggregatePaginate.bind(ctx.repo)({
+					filter: in_("category", [...KEYSET_CATS]),
+					groupBy: "category",
+					measures: { n: { op: "count" } },
+					sort: { category: 1 },
+					pagination: "keyset",
+					limit: 100
+				});
+				expect(result.method).toBe("keyset");
+				if (result.method !== "keyset") throw new Error("expected keyset envelope");
+				expect(result.data).toHaveLength(KEYSET_CATS.length);
+				expect(result.hasMore).toBe(false);
+				expect(result.next).toBeNull();
+			});
 		});
 		describe("pagination edges", () => {
 			beforeEach(async () => {
@@ -309,8 +954,8 @@ function runStandardRepoConformance(harness) {
 					limit: 10,
 					sort: "createdAt"
 				});
-				expect(Array.isArray(out.docs)).toBe(true);
-				expect(out.docs).toHaveLength(0);
+				expect(Array.isArray(out.data)).toBe(true);
+				expect(out.data).toHaveLength(0);
 				expect(out.total).toBe(5);
 			});
 			it("limit larger than dataset returns all rows, no error", async () => {
@@ -319,7 +964,7 @@ function runStandardRepoConformance(harness) {
 					limit: 1e3,
 					sort: "createdAt"
 				});
-				expect(out.docs).toHaveLength(5);
+				expect(out.data).toHaveLength(5);
 				expect(out.total).toBe(5);
 			});
 			it("explicit filter in pagination narrows results consistently", async () => {
@@ -328,7 +973,7 @@ function runStandardRepoConformance(harness) {
 					page: 1,
 					limit: 10
 				});
-				expect(out.docs).toHaveLength(1);
+				expect(out.data).toHaveLength(1);
 				expect(out.total).toBe(1);
 			});
 		});
@@ -417,24 +1062,28 @@ function runStandardRepoConformance(harness) {
 			});
 		});
 		describe.skipIf(!harness.features.getOrCreate)("getOrCreate", () => {
-			it("inserts when no row matches filter", async () => {
+			it("inserts when no row matches filter (created: true)", async () => {
 				if (!ctx.repo.getOrCreate) return;
-				expect((await ctx.repo.getOrCreate({ email: "fresh@x.com" }, harness.makeDoc({
+				const result = await ctx.repo.getOrCreate({ email: "fresh@x.com" }, harness.makeDoc({
 					name: "Fresh",
 					email: "fresh@x.com"
-				})))?.name).toBe("Fresh");
+				}));
+				expect(result.doc.name).toBe("Fresh");
+				expect(result.created).toBe(true);
 				expect(await ctx.repo.findAll()).toHaveLength(1);
 			});
-			it("returns existing row when filter matches (no insert)", async () => {
+			it("returns existing row when filter matches (created: false, no insert)", async () => {
 				if (!ctx.repo.getOrCreate) return;
 				await ctx.repo.create(harness.makeDoc({
 					name: "Existing",
 					email: "existing@x.com"
 				}));
-				expect((await ctx.repo.getOrCreate({ email: "existing@x.com" }, harness.makeDoc({
+				const result = await ctx.repo.getOrCreate({ email: "existing@x.com" }, harness.makeDoc({
 					name: "WouldOverwrite",
 					email: "existing@x.com"
-				})))?.name).toBe("Existing");
+				}));
+				expect(result.doc.name).toBe("Existing");
+				expect(result.created).toBe(false);
 				expect(await ctx.repo.findAll()).toHaveLength(1);
 			});
 		});