@storyshelf/core 0.6.2 → 0.8.0

package/dist/test-helpers/queue-multi-instance.mjs

@@ -0,0 +1,205 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { CaptureJobModel, attemptRowId } from "../models/capture-job.mjs";
+import { LEASE_EXHAUSTED_ERROR } from "../capture/db-queue/claim.mjs";
+import { createDatabaseCaptureQueue } from "../capture/db-queue/index.mjs";
+import { describe, expect, it } from "vitest";
+// src/test-helpers/queue-multi-instance.ts
+/**
+* Multi-instance suite for the database capture queue: several queue instances (one per simulated
+* app instance) share ONE database, the way horizontally scaled app instances do. Database packages
+* run it against their own drivers (node:sqlite, PGlite, and the gated live Postgres, MySQL and
+* Turso tests):
+*
+* ```ts
+* import { databaseQueueMultiInstanceSuite } from "@storyshelf/core/test-helpers";
+* databaseQueueMultiInstanceSuite("sqlite", async () => await setUp(createSqliteDatabase(":memory:")));
+* ```
+*
+* Every instance reads one shared manual clock, so lease expiry and retry delays are exact and no
+* case sleeps. Build ids are unique per run, so a shared live database needs no cleanup between runs.
+*/
+const LEASE_MS = 6e4;
+const RETRIES = 2;
+async function fleet(makeDb, size, kinds = ["capture"]) {
+	const db = await makeDb();
+	const clock = { now: Date.now() };
+	const queues = Array.from({ length: size }, (_unused, index) => createDatabaseCaptureQueue(db, {
+		kinds,
+		leaseMs: LEASE_MS,
+		retries: RETRIES,
+		owner: `instance-${String(index)}`,
+		now: () => clock.now
+	}));
+	const advance = (ms) => {
+		clock.now += ms;
+	};
+	return {
+		db,
+		queues,
+		advance,
+		runId: `mi-${String(clock.now)}-${Math.random().toString(36).slice(2, 8)}`
+	};
+}
+/** Poll on every instance at once, as concurrent app instances would. */
+async function pollAll(queues) {
+	return (await Promise.all(queues.map(async (queue) => await queue.poll()))).filter((job) => job !== null);
+}
+/** Poll every instance until one returns the job of `buildId` (others' jobs are acked away). */
+async function claimOn(queue, buildId) {
+	for (let tries = 0; tries < 50; tries += 1) {
+		const job = await queue.poll();
+		if (job === null || job.buildId === buildId) return job;
+		await queue.ack(job);
+	}
+	return null;
+}
+/** Run the multi-instance suite against databases from `makeDb`. */
+function databaseQueueMultiInstanceSuite(label, makeDb, options = {}) {
+	const size = options.instances ?? 4;
+	const jobs = options.jobs ?? 24;
+	describe(`database queue, ${String(size)} instances on one database: ${label}`, () => {
+		exactlyOnceCase(makeDb, size, jobs, options.timeoutMs);
+		leaseCases(makeDb, size, options.timeoutMs);
+		retryCases(makeDb, size, options.timeoutMs);
+		cancelAndKindCases(makeDb, size, options.timeoutMs);
+	});
+}
+function exactlyOnceCase(makeDb, size, jobs, timeoutMs) {
+	it("runs each job exactly once across instances polling at the same time", async () => {
+		const { queues, runId } = await fleet(makeDb, size);
+		const ids = Array.from({ length: jobs }, (_unused, index) => `${runId}-${String(index)}`);
+		await Promise.all(ids.map(async (buildId, index) => await queues[index % size].enqueue({ buildId })));
+		const claims = /* @__PURE__ */ new Map();
+		const ours = new Set(ids);
+		for (let round = 0; round < jobs * 2 + 20 && claims.size < jobs; round += 1) {
+			const claimed = await pollAll(queues);
+			for (const job of claimed.filter((one) => ours.has(one.buildId))) claims.set(job.buildId, (claims.get(job.buildId) ?? 0) + 1);
+			await Promise.all(claimed.map(async (job) => await queues[0].ack(job)));
+		}
+		expect([...claims.keys()].toSorted()).toEqual(ids.toSorted());
+		expect([...claims.values()].every((count) => count === 1)).toBe(true);
+		const statuses = await Promise.all(ids.map(async (id) => (await queues[1].status(id))?.status));
+		expect(new Set(statuses)).toEqual(/* @__PURE__ */ new Set(["completed"]));
+	}, timeoutMs);
+}
+function leaseCases(makeDb, size, timeoutMs) {
+	it("redelivers an expired lease to another instance and fences the stale holder", async () => {
+		const { db, queues, advance, runId } = await fleet(makeDb, size);
+		const [first, second] = [queues[0], queues[1]];
+		const buildId = `${runId}-lease`;
+		await first.enqueue({ buildId });
+		const stale = await claimOn(first, buildId);
+		expect(stale?.attempt).toBe(1);
+		expect(await claimOn(second, buildId)).toBeNull();
+		advance(60001);
+		const winners = (await pollAll(queues)).filter((job) => job.buildId === buildId);
+		expect(winners).toHaveLength(1);
+		const fresh = winners[0];
+		expect(fresh.attempt).toBe(2);
+		const model = new CaptureJobModel(db);
+		const leaseBefore = (await model.get(attemptRowId(fresh.jobId, 2)))?.visibleAt;
+		expect(await first.extend(stale)).toBe("lost");
+		expect(await first.inspect(stale)).toBe("lost");
+		await first.nack(stale, {
+			requeue: true,
+			error: "stale"
+		});
+		const after = await model.get(fresh.jobId);
+		expect(after).toMatchObject({
+			status: "running",
+			attempt: 2
+		});
+		expect((await model.get(attemptRowId(fresh.jobId, 2)))?.visibleAt).toBe(leaseBefore);
+		expect((await model.get(attemptRowId(fresh.jobId, 1)))?.status).toBe("expired");
+		expect(await second.extend(fresh)).toBe("ok");
+		await second.ack(fresh);
+		await first.ack(stale);
+		expect((await second.status(buildId))?.status).toBe("completed");
+	}, timeoutMs);
+}
+function retryCases(makeDb, size, timeoutMs) {
+	it("fails a job on any instance once its retries are spent", async () => {
+		const { queues, advance, runId } = await fleet(makeDb, size);
+		const buildId = `${runId}-retry`;
+		await queues[0].enqueue({ buildId });
+		for (let attempt = 1; attempt <= 3; attempt += 1) {
+			const queue = queues[attempt % size];
+			const job = await claimOn(queue, buildId);
+			expect(job?.attempt).toBe(attempt);
+			await queue.nack(job, {
+				requeue: true,
+				delayMs: 1e3,
+				error: `boom ${String(attempt)}`
+			});
+			advance(1001);
+		}
+		expect(await claimOn(queues[0], buildId)).toBeNull();
+		expect(await queues[2 % size].status(buildId)).toMatchObject({
+			status: "failed",
+			error: `boom ${String(3)}`
+		});
+	}, timeoutMs);
+	it("fails a job whose every attempt lost its lease", async () => {
+		const { queues, advance, runId } = await fleet(makeDb, size);
+		const buildId = `${runId}-hung`;
+		await queues[0].enqueue({ buildId });
+		for (let attempt = 1; attempt <= 3; attempt += 1) {
+			const job = await claimOn(queues[attempt % size], buildId);
+			expect(job?.attempt).toBe(attempt);
+			advance(60001);
+		}
+		expect(await claimOn(queues[0], buildId)).toBeNull();
+		expect(await queues[1].status(buildId)).toMatchObject({
+			status: "failed",
+			error: LEASE_EXHAUSTED_ERROR
+		});
+	}, timeoutMs);
+}
+function cancelAndKindCases(makeDb, size, timeoutMs) {
+	it("lets one instance cancel a job another instance holds", async () => {
+		const { queues, runId } = await fleet(makeDb, size);
+		const [holder, other] = [queues[0], queues[1]];
+		const buildId = `${runId}-cancel`;
+		await other.enqueue({ buildId });
+		const job = await claimOn(holder, buildId);
+		expect(await holder.inspect(job)).toBe("ok");
+		expect(await other.cancel(buildId)).toBe(true);
+		expect(await holder.inspect(job)).toBe("cancelled");
+		expect(await holder.extend(job)).toBe("cancelled");
+		await holder.nack(job, {
+			requeue: false,
+			error: "cancelled"
+		});
+		expect((await other.status(buildId))?.status).toBe("cancelled");
+		expect(await claimOn(other, buildId)).toBeNull();
+	}, timeoutMs);
+	it("keeps job kinds independent", async () => {
+		const shared = await makeDb();
+		const reuse = () => shared;
+		const capture = await fleet(reuse, 2, ["capture"]);
+		const publish = await fleet(reuse, 2, ["publish"]);
+		const buildId = `${capture.runId}-kinds`;
+		await capture.queues[0].enqueue({ buildId });
+		await publish.queues[0].enqueueJob({
+			kind: "publish",
+			buildId,
+			data: { zip: "k" }
+		});
+		const published = await claimOn(publish.queues[1], buildId);
+		expect(published).toMatchObject({
+			kind: "publish",
+			data: { zip: "k" }
+		});
+		const captured = await claimOn(capture.queues[1], buildId);
+		expect(captured?.kind).toBe("capture");
+		expect(await claimOn(publish.queues[0], buildId)).toBeNull();
+		await publish.queues[1].ack(published);
+		await capture.queues[1].ack(captured);
+		expect((await capture.queues[0].status(buildId))?.status).toBe("completed");
+	}, timeoutMs);
+}
+export { databaseQueueMultiInstanceSuite };
+
+//# sourceMappingURL=queue-multi-instance.mjs.map

package/dist/test-helpers/queue-multi-instance.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-multi-instance.mjs","names":[],"sources":["../../src/test-helpers/queue-multi-instance.ts"],"sourcesContent":["/**\n * Multi-instance suite for the database capture queue: several queue instances (one per simulated\n * app instance) share ONE database, the way horizontally scaled app instances do. Database packages\n * run it against their own drivers (node:sqlite, PGlite, and the gated live Postgres, MySQL and\n * Turso tests):\n *\n * ```ts\n * import { databaseQueueMultiInstanceSuite } from \"@storyshelf/core/test-helpers\";\n * databaseQueueMultiInstanceSuite(\"sqlite\", async () => await setUp(createSqliteDatabase(\":memory:\")));\n * ```\n *\n * Every instance reads one shared manual clock, so lease expiry and retry delays are exact and no\n * case sleeps. Build ids are unique per run, so a shared live database needs no cleanup between runs.\n */\nimport { describe, expect, it } from \"vitest\";\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport {\n  createDatabaseCaptureQueue,\n  LEASE_EXHAUSTED_ERROR,\n  type DatabaseCaptureQueue,\n  type DatabaseJob,\n} from \"../capture/db-queue/index.ts\";\nimport { attemptRowId, CaptureJobModel } from \"../models/capture-job.ts\";\nimport type { CaptureJobKind } from \"../schema/capture-job.ts\";\n\n/** A set-up database the instances of one case share. */\nexport type SharedDatabaseFactory = () => DatabaseAdapter | Promise<DatabaseAdapter>;\n\n/** Options of {@link databaseQueueMultiInstanceSuite}. */\nexport interface MultiInstanceOptions {\n  /** Queue instances sharing the database (default 4). */\n  instances?: number;\n  /** Jobs in the exactly-once case (default 24). */\n  jobs?: number;\n  /** Per-case timeout in ms, for slow remote databases (default vitest's). */\n  timeoutMs?: number;\n}\n\nconst LEASE_MS = 60_000;\nconst RETRIES = 2;\n\ninterface Fleet {\n  db: DatabaseAdapter;\n  queues: DatabaseCaptureQueue[];\n  advance: (ms: number) => void;\n  runId: string;\n}\n\nasync function fleet(\n  makeDb: SharedDatabaseFactory,\n  size: number,\n  kinds: readonly CaptureJobKind[] = [\"capture\"],\n): Promise<Fleet> {\n  const db = await makeDb();\n  const clock = { now: Date.now() };\n  const queues = Array.from({ length: size }, (_unused, index) =>\n    createDatabaseCaptureQueue(db, {\n      kinds,\n      leaseMs: LEASE_MS,\n      retries: RETRIES,\n      owner: `instance-${String(index)}`,\n      now: () => clock.now,\n    }),\n  );\n  const advance = (ms: number): void => {\n    clock.now += ms;\n  };\n  return {\n    db,\n    queues,\n    advance,\n    runId: `mi-${String(clock.now)}-${Math.random().toString(36).slice(2, 8)}`,\n  };\n}\n\n/** Poll on every instance at once, as concurrent app instances would. */\nasync function pollAll(queues: DatabaseCaptureQueue[]): Promise<DatabaseJob[]> {\n  const jobs = await Promise.all(queues.map(async (queue) => await queue.poll()));\n  return jobs.filter((job): job is DatabaseJob => job !== null);\n}\n\n/** Poll every instance until one returns the job of `buildId` (others' jobs are acked away). */\nasync function claimOn(queue: DatabaseCaptureQueue, buildId: string): Promise<DatabaseJob | null> {\n  for (let tries = 0; tries < 50; tries += 1) {\n    // oxlint-disable-next-line eslint/no-await-in-loop -- sequential polls are the point\n    const job = await queue.poll();\n    if (job === null || job.buildId === buildId) {\n      return job;\n    }\n    // oxlint-disable-next-line eslint/no-await-in-loop -- clear a leftover of another case\n    await queue.ack(job);\n  }\n  return null;\n}\n\n/** Run the multi-instance suite against databases from `makeDb`. */\nexport function databaseQueueMultiInstanceSuite(\n  label: string,\n  makeDb: SharedDatabaseFactory,\n  options: MultiInstanceOptions = {},\n): void {\n  const size = options.instances ?? 4;\n  const jobs = options.jobs ?? 24;\n  describe(`database queue, ${String(size)} instances on one database: ${label}`, () => {\n    exactlyOnceCase(makeDb, size, jobs, options.timeoutMs);\n    leaseCases(makeDb, size, options.timeoutMs);\n    retryCases(makeDb, size, options.timeoutMs);\n    cancelAndKindCases(makeDb, size, options.timeoutMs);\n  });\n}\n\nfunction exactlyOnceCase(\n  makeDb: SharedDatabaseFactory,\n  size: number,\n  jobs: number,\n  timeoutMs?: number,\n): void {\n  it(\n    \"runs each job exactly once across instances polling at the same time\",\n    async () => {\n      const { queues, runId } = await fleet(makeDb, size);\n      const ids = Array.from({ length: jobs }, (_unused, index) => `${runId}-${String(index)}`);\n      await Promise.all(\n        ids.map(async (buildId, index) => await queues[index % size]!.enqueue({ buildId })),\n      );\n      const claims = new Map<string, number>();\n      const ours = new Set(ids);\n      for (let round = 0; round < jobs * 2 + 20 && claims.size < jobs; round += 1) {\n        // oxlint-disable-next-line eslint/no-await-in-loop -- rounds of concurrent polls\n        const claimed = await pollAll(queues);\n        // A shared (live) database may hold other runs' jobs: settle them, count only ours.\n        for (const job of claimed.filter((one) => ours.has(one.buildId))) {\n          claims.set(job.buildId, (claims.get(job.buildId) ?? 0) + 1);\n        }\n        // oxlint-disable-next-line eslint/no-await-in-loop -- see above\n        await Promise.all(claimed.map(async (job) => await queues[0]!.ack(job)));\n      }\n      expect([...claims.keys()].toSorted()).toEqual(ids.toSorted());\n      expect([...claims.values()].every((count) => count === 1)).toBe(true);\n      const statuses = await Promise.all(\n        ids.map(async (id) => (await queues[1]!.status(id))?.status),\n      );\n      expect(new Set(statuses)).toEqual(new Set([\"completed\"]));\n    },\n    timeoutMs,\n  );\n}\n\nfunction leaseCases(makeDb: SharedDatabaseFactory, size: number, timeoutMs?: number): void {\n  it(\n    \"redelivers an expired lease to another instance and fences the stale holder\",\n    async () => {\n      const { db, queues, advance, runId } = await fleet(makeDb, size);\n      const [first, second] = [queues[0]!, queues[1]!];\n      const buildId = `${runId}-lease`;\n      await first.enqueue({ buildId });\n      const stale = await claimOn(first, buildId);\n      expect(stale?.attempt).toBe(1);\n      expect(await claimOn(second, buildId)).toBeNull();\n      advance(LEASE_MS + 1);\n      // Every instance races for the expired lease; exactly one wins.\n      const winners = (await pollAll(queues)).filter((job) => job.buildId === buildId);\n      expect(winners).toHaveLength(1);\n      const fresh = winners[0]!;\n      expect(fresh.attempt).toBe(2);\n      const model = new CaptureJobModel(db);\n      const leaseBefore = (await model.get(attemptRowId(fresh.jobId, 2)))?.visibleAt;\n      expect(await first.extend(stale!)).toBe(\"lost\");\n      expect(await first.inspect(stale!)).toBe(\"lost\");\n      await first.nack(stale!, { requeue: true, error: \"stale\" });\n      const after = await model.get(fresh.jobId);\n      expect(after).toMatchObject({ status: \"running\", attempt: 2 });\n      expect((await model.get(attemptRowId(fresh.jobId, 2)))?.visibleAt).toBe(leaseBefore);\n      expect((await model.get(attemptRowId(fresh.jobId, 1)))?.status).toBe(\"expired\");\n      expect(await second.extend(fresh)).toBe(\"ok\");\n      await second.ack(fresh);\n      // A late finish by the stale holder costs a duplicate run, never a wrong result.\n      await first.ack(stale!);\n      expect((await second.status(buildId))?.status).toBe(\"completed\");\n    },\n    timeoutMs,\n  );\n}\n\nfunction retryCases(makeDb: SharedDatabaseFactory, size: number, timeoutMs?: number): void {\n  it(\n    \"fails a job on any instance once its retries are spent\",\n    async () => {\n      const { queues, advance, runId } = await fleet(makeDb, size);\n      const buildId = `${runId}-retry`;\n      await queues[0]!.enqueue({ buildId });\n      for (let attempt = 1; attempt <= RETRIES + 1; attempt += 1) {\n        const queue = queues[attempt % size]!;\n        // oxlint-disable-next-line eslint/no-await-in-loop -- attempts are sequential\n        const job = await claimOn(queue, buildId);\n        expect(job?.attempt).toBe(attempt);\n        // oxlint-disable-next-line eslint/no-await-in-loop -- see above\n        await queue.nack(job!, { requeue: true, delayMs: 1000, error: `boom ${String(attempt)}` });\n        advance(1001);\n      }\n      expect(await claimOn(queues[0]!, buildId)).toBeNull();\n      expect(await queues[2 % size]!.status(buildId)).toMatchObject({\n        status: \"failed\",\n        error: `boom ${String(RETRIES + 1)}`,\n      });\n    },\n    timeoutMs,\n  );\n\n  it(\n    \"fails a job whose every attempt lost its lease\",\n    async () => {\n      const { queues, advance, runId } = await fleet(makeDb, size);\n      const buildId = `${runId}-hung`;\n      await queues[0]!.enqueue({ buildId });\n      for (let attempt = 1; attempt <= RETRIES + 1; attempt += 1) {\n        // oxlint-disable-next-line eslint/no-await-in-loop -- attempts are sequential\n        const job = await claimOn(queues[attempt % size]!, buildId);\n        expect(job?.attempt).toBe(attempt);\n        advance(LEASE_MS + 1);\n      }\n      expect(await claimOn(queues[0]!, buildId)).toBeNull();\n      expect(await queues[1]!.status(buildId)).toMatchObject({\n        status: \"failed\",\n        error: LEASE_EXHAUSTED_ERROR,\n      });\n    },\n    timeoutMs,\n  );\n}\n\nfunction cancelAndKindCases(makeDb: SharedDatabaseFactory, size: number, timeoutMs?: number): void {\n  it(\n    \"lets one instance cancel a job another instance holds\",\n    async () => {\n      const { queues, runId } = await fleet(makeDb, size);\n      const [holder, other] = [queues[0]!, queues[1]!];\n      const buildId = `${runId}-cancel`;\n      await other.enqueue({ buildId });\n      const job = await claimOn(holder, buildId);\n      expect(await holder.inspect(job!)).toBe(\"ok\");\n      expect(await other.cancel(buildId)).toBe(true);\n      expect(await holder.inspect(job!)).toBe(\"cancelled\");\n      expect(await holder.extend(job!)).toBe(\"cancelled\");\n      await holder.nack(job!, { requeue: false, error: \"cancelled\" });\n      expect((await other.status(buildId))?.status).toBe(\"cancelled\");\n      expect(await claimOn(other, buildId)).toBeNull();\n    },\n    timeoutMs,\n  );\n\n  it(\n    \"keeps job kinds independent\",\n    async () => {\n      const shared = await makeDb();\n      const reuse = (): DatabaseAdapter => shared;\n      const capture = await fleet(reuse, 2, [\"capture\"]);\n      const publish = await fleet(reuse, 2, [\"publish\"]);\n      const buildId = `${capture.runId}-kinds`;\n      await capture.queues[0]!.enqueue({ buildId });\n      await publish.queues[0]!.enqueueJob({ kind: \"publish\", buildId, data: { zip: \"k\" } });\n      const published = await claimOn(publish.queues[1]!, buildId);\n      expect(published).toMatchObject({ kind: \"publish\", data: { zip: \"k\" } });\n      const captured = await claimOn(capture.queues[1]!, buildId);\n      expect(captured?.kind).toBe(\"capture\");\n      expect(await claimOn(publish.queues[0]!, buildId)).toBeNull();\n      await publish.queues[1]!.ack(published!);\n      await capture.queues[1]!.ack(captured!);\n      expect((await capture.queues[0]!.status(buildId))?.status).toBe(\"completed\");\n    },\n    timeoutMs,\n  );\n}\n"],"mappings":"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"}

package/dist/test-helpers/runner-contract.d.mts

@@ -1,11 +1,9 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { CaptureRunner } from "../adapter/capture-runner.mjs";
-//#region src/test-helpers/runner-contract.d.ts
 /** Build the adapter under test (sync or async factories both work). */
 type RunnerFactory = () => CaptureRunner | Promise<CaptureRunner>;
 /** Run the runner contract against a factory. */
 declare function runnerContractSuite(label: string, make: RunnerFactory): void;
-//#endregion
 export { RunnerFactory, runnerContractSuite };
 //# sourceMappingURL=runner-contract.d.mts.map

package/dist/test-helpers/runner-contract.mjs

@@ -1,8 +1,9 @@
 import "node:path";
 import "node:url";
 import.meta.url;
+import { isCaptureTarget } from "../adapters/capture-target.mjs";
 import { describe, expect, it } from "vitest";
-//#region src/test-helpers/runner-contract.ts
+// src/test-helpers/runner-contract.ts
 /**
 * Published runner contract suite for first- and third-party adapters.
 *
@@ -19,6 +20,16 @@ function runnerContractSuite(label, make) {
 			expect(runner.metadata.category).toBe("capture-runner");
 			expect(runner.metadata.kind.length).toBeGreaterThan(0);
 		});
+		it("lists its targets as unique, valid capture targets, default first", async () => {
+			const targets = (await make()).metadata.targets;
+			if (targets === void 0) return;
+			expect(targets.length).toBeGreaterThan(0);
+			for (const entry of targets) {
+				expect(isCaptureTarget(entry.target), entry.target).toBe(true);
+				expect(["loopback", "url"]).toContain(entry.reach);
+			}
+			expect(new Set(targets.map((entry) => entry.target)).size).toBe(targets.length);
+		});
 		it("exposes render and cancel", async () => {
 			const runner = await make();
 			expect(typeof runner.render).toBe("function");
@@ -26,7 +37,6 @@ function runnerContractSuite(label, make) {
 		});
 	});
 }
-//#endregion
 export { runnerContractSuite };
 
 //# sourceMappingURL=runner-contract.mjs.map

package/dist/test-helpers/runner-contract.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"runner-contract.mjs","names":[],"sources":["../../src/test-helpers/runner-contract.ts"],"sourcesContent":["/**\n * Published runner contract suite for first- and third-party adapters.\n *\n * Structural conformance (identity, render/cancel presence). Behavioral\n * rendering stays per-package behind real or mocked browsers — the\n * orchestrator owns timeouts, byte guards, and failure caps, so runners\n * only promise to return PNG buffers and honor `cancel`.\n */\nimport { describe, expect, it } from \"vitest\";\nimport type { CaptureRunner } from \"../adapters/capture-runner.ts\";\n\n/** Build the adapter under test (sync or async factories both work). */\nexport type RunnerFactory = () => CaptureRunner | Promise<CaptureRunner>;\n\n/** Run the runner contract against a factory. */\nexport function runnerContractSuite(label: string, make: RunnerFactory): void {\n  describe(`runner contract: ${label}`, () => {\n    it(\"exposes capture-runner metadata\", async () => {\n      const runner = await make();\n      expect(runner.metadata.category).toBe(\"capture-runner\");\n      expect(runner.metadata.kind.length).toBeGreaterThan(0);\n    });\n\n    it(\"exposes render and cancel\", async () => {\n      const runner = await make();\n      expect(typeof runner.render).toBe(\"function\");\n      expect(typeof runner.cancel).toBe(\"function\");\n    });\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;AAeA,SAAgB,oBAAoB,OAAe,MAA2B;CAC5E,SAAS,oBAAoB,eAAe;EAC1C,GAAG,mCAAmC,YAAY;GAChD,MAAM,SAAS,MAAM,KAAK;GAC1B,OAAO,OAAO,SAAS,QAAQ,CAAC,CAAC,KAAK,gBAAgB;GACtD,OAAO,OAAO,SAAS,KAAK,MAAM,CAAC,CAAC,gBAAgB,CAAC;EACvD,CAAC;EAED,GAAG,6BAA6B,YAAY;GAC1C,MAAM,SAAS,MAAM,KAAK;GAC1B,OAAO,OAAO,OAAO,MAAM,CAAC,CAAC,KAAK,UAAU;GAC5C,OAAO,OAAO,OAAO,MAAM,CAAC,CAAC,KAAK,UAAU;EAC9C,CAAC;CACH,CAAC;AACH"}
+{"version":3,"file":"runner-contract.mjs","names":[],"sources":["../../src/test-helpers/runner-contract.ts"],"sourcesContent":["/**\n * Published runner contract suite for first- and third-party adapters.\n *\n * Structural conformance (identity, render/cancel presence). Behavioral\n * rendering stays per-package behind real or mocked browsers — the\n * orchestrator owns timeouts, byte guards, and failure caps, so runners\n * only promise to return PNG buffers and honor `cancel`.\n */\nimport { describe, expect, it } from \"vitest\";\nimport type { CaptureRunner } from \"../adapters/capture-runner.ts\";\nimport { isCaptureTarget } from \"../adapters/capture-target.ts\";\n\n/** Build the adapter under test (sync or async factories both work). */\nexport type RunnerFactory = () => CaptureRunner | Promise<CaptureRunner>;\n\n/** Run the runner contract against a factory. */\nexport function runnerContractSuite(label: string, make: RunnerFactory): void {\n  describe(`runner contract: ${label}`, () => {\n    it(\"exposes capture-runner metadata\", async () => {\n      const runner = await make();\n      expect(runner.metadata.category).toBe(\"capture-runner\");\n      expect(runner.metadata.kind.length).toBeGreaterThan(0);\n    });\n\n    it(\"lists its targets as unique, valid capture targets, default first\", async () => {\n      const targets = (await make()).metadata.targets;\n      if (targets === undefined) {\n        return;\n      }\n      expect(targets.length).toBeGreaterThan(0);\n      for (const entry of targets) {\n        expect(isCaptureTarget(entry.target), entry.target).toBe(true);\n        expect([\"loopback\", \"url\"]).toContain(entry.reach);\n      }\n      expect(new Set(targets.map((entry) => entry.target)).size).toBe(targets.length);\n    });\n\n    it(\"exposes render and cancel\", async () => {\n      const runner = await make();\n      expect(typeof runner.render).toBe(\"function\");\n      expect(typeof runner.cancel).toBe(\"function\");\n    });\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;AAgBA,SAAgB,oBAAoB,OAAe,MAA2B;CAC5E,SAAS,oBAAoB,eAAe;EAC1C,GAAG,mCAAmC,YAAY;GAChD,MAAM,SAAS,MAAM,KAAK;GAC1B,OAAO,OAAO,SAAS,QAAQ,CAAC,CAAC,KAAK,gBAAgB;GACtD,OAAO,OAAO,SAAS,KAAK,MAAM,CAAC,CAAC,gBAAgB,CAAC;EACvD,CAAC;EAED,GAAG,qEAAqE,YAAY;GAClF,MAAM,WAAW,MAAM,KAAK,EAAA,CAAG,SAAS;GACxC,IAAI,YAAY,KAAA,GACd;GAEF,OAAO,QAAQ,MAAM,CAAC,CAAC,gBAAgB,CAAC;GACxC,KAAK,MAAM,SAAS,SAAS;IAC3B,OAAO,gBAAgB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,CAAC,KAAK,IAAI;IAC7D,OAAO,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,UAAU,MAAM,KAAK;GACnD;GACA,OAAO,IAAI,IAAI,QAAQ,KAAK,UAAU,MAAM,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,QAAQ,MAAM;EAChF,CAAC;EAED,GAAG,6BAA6B,YAAY;GAC1C,MAAM,SAAS,MAAM,KAAK;GAC1B,OAAO,OAAO,OAAO,MAAM,CAAC,CAAC,KAAK,UAAU;GAC5C,OAAO,OAAO,OAAO,MAAM,CAAC,CAAC,KAAK,UAAU;EAC9C,CAAC;CACH,CAAC;AACH"}

package/dist/test-helpers/sql-chunks.mjs

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { getTableColumns } from "drizzle-orm";
-//#region src/test-helpers/sql-chunks.ts
+// src/test-helpers/sql-chunks.ts
 /** Flatten the string parts of a drizzle SQL chunk into a single string. */
 function textOf(chunk) {
 	if (chunk === void 0 || !Array.isArray(chunk.value) || !chunk.value.every((part) => typeof part === "string")) return;
@@ -24,7 +24,11 @@ function matchChunk(chunks, row, table) {
 	const text = chunks.map((c) => textOf(c) ?? "").join("");
 	if (/is not null/iu.test(text)) return isNullMatches(chunks, row, table, true);
 	if (/is null/iu.test(text)) return isNullMatches(chunks, row, table, false);
+	if (text.includes(" <> ")) return !eqMatches(chunks, row, table);
+	if (text.includes(" like ")) return likeMatches(chunks, row, table);
 	if (text.includes(" in ")) return inArrayMatches(chunks, row, table);
+	if (text.includes(" >= ")) return !ltMatches(chunks, row, table);
+	if (text.includes(" <= ")) return lteMatches(chunks, row, table);
 	if (text.includes(" < ")) return ltMatches(chunks, row, table);
 	return eqMatches(chunks, row, table);
 }
@@ -45,6 +49,21 @@ function eqMatches(chunks, row, table) {
 	if (columnName === void 0) return false;
 	return row[columnKey(table, columnName)] === argument;
 }
+/** Match `column like 'pattern'`: `%` is any run of characters, `_` any one; everything else literal. */
+function likeMatches(chunks, row, table) {
+	let columnName;
+	let pattern;
+	for (const chunk of chunks) if (typeof chunk === "string") pattern = chunk;
+	else if (chunk !== null && typeof chunk === "object") {
+		const node = chunk;
+		if (typeof node.name === "string" && node.table !== void 0) columnName = node.name;
+		else if ("brand" in node) pattern = node.value;
+	}
+	const cell = columnName === void 0 ? void 0 : row[columnKey(table, columnName)];
+	if (typeof cell !== "string" || typeof pattern !== "string") return false;
+	const source = pattern.replaceAll(/[.*+?^${}()|[\]\\]/gu, String.raw`\$&`);
+	return new RegExp(`^${source.replaceAll("%", ".*").replaceAll("_", ".")}$`, "su").test(cell);
+}
 function inArrayMatches(chunks, row, table) {
 	let columnName;
 	const values = [];
@@ -78,6 +97,11 @@ function inArrayMatches(chunks, row, table) {
 	const key = columnKey(table, columnName);
 	return values.includes(row[key]);
 }
+/** `column <= value`: the cell is present and not greater than the argument. */
+function lteMatches(chunks, row, table) {
+	if (ltMatches(chunks, row, table)) return true;
+	return eqMatches(chunks, row, table);
+}
 function ltMatches(chunks, row, table) {
 	let columnName;
 	let argument;
@@ -132,7 +156,6 @@ function columnKey(table, dbName) {
 	for (const [property, column] of Object.entries(getTableColumns(table))) if (column.name === dbName) return property;
 	return dbName;
 }
-//#endregion
 export { orderRows, whereMatches };
 
 //# sourceMappingURL=sql-chunks.mjs.map

package/dist/test-helpers/sql-chunks.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"sql-chunks.mjs","names":[],"sources":["../../src/test-helpers/sql-chunks.ts"],"sourcesContent":["import { getTableColumns, type SQL, type Table } from \"drizzle-orm\";\n\n/* eslint-disable require-await, no-unnecessary-type-assertion, no-unnecessary-type-parameters, non-nullable-type-assertion-style */\n\n/** A drizzle SQL chunk inspected for matching and ordering. */\nexport interface SqlChunk {\n  value?: unknown;\n  name?: string;\n  table?: unknown;\n  brand?: unknown;\n  queryChunks?: SqlChunk[];\n}\n\n/** Flatten the string parts of a drizzle SQL chunk into a single string. */\nfunction textOf(chunk: SqlChunk | undefined): string | undefined {\n  if (\n    chunk === undefined ||\n    !Array.isArray(chunk.value) ||\n    !chunk.value.every((part) => typeof part === \"string\")\n  ) {\n    return undefined;\n  }\n  return chunk.value.join(\"\");\n}\n\n/** Test whether an in-memory row satisfies a drizzle where-clause. */\nexport function whereMatches(where: SQL, row: Record<string, unknown>, table: Table): boolean {\n  let current = where.queryChunks as unknown as SqlChunk[];\n  let wrapped = current[1]?.queryChunks;\n  while (wrapped !== undefined && textOf(current[0]) === \"(\" && textOf(current.at(-1)) === \")\") {\n    current = wrapped;\n    wrapped = current[1]?.queryChunks;\n  }\n  // Drizzle's `and(singleCondition)` emits the condition directly, without\n  // the enclosing parens produced for two or more clauses, so unwrap it.\n  if (current.length === 1 && current[0]?.queryChunks !== undefined) {\n    current = current[0].queryChunks as unknown as SqlChunk[];\n  }\n  if (current.some((chunk) => textOf(chunk)?.trim() === \"and\")) {\n    return current\n      .filter((chunk) => textOf(chunk) === undefined)\n      .every((chunk) => matchChunk(chunk.queryChunks ?? [], row, table));\n  }\n  return matchChunk(current, row, table);\n}\n\nfunction matchChunk(chunks: SqlChunk[], row: Record<string, unknown>, table: Table): boolean {\n  const text = chunks.map((c) => textOf(c) ?? \"\").join(\"\");\n  if (/is not null/iu.test(text)) {\n    return isNullMatches(chunks, row, table, true);\n  }\n  if (/is null/iu.test(text)) {\n    return isNullMatches(chunks, row, table, false);\n  }\n  if (text.includes(\" in \")) {\n    return inArrayMatches(chunks, row, table);\n  }\n  if (text.includes(\" < \")) {\n    return ltMatches(chunks, row, table);\n  }\n  return eqMatches(chunks, row, table);\n}\n\n/** Match `is null` / `is not null` predicates (no value argument). */\nfunction isNullMatches(\n  chunks: SqlChunk[],\n  row: Record<string, unknown>,\n  table: Table,\n  negated: boolean,\n): boolean {\n  let columnName: string | undefined;\n  for (const chunk of chunks) {\n    if (typeof chunk.name === \"string\" && chunk.table !== undefined) {\n      columnName = chunk.name;\n    }\n  }\n  if (columnName === undefined) {\n    return false;\n  }\n  const cell = row[columnKey(table, columnName)];\n  const missing = cell === null || cell === undefined;\n  return negated ? !missing : missing;\n}\n\nfunction eqMatches(chunks: SqlChunk[], row: Record<string, unknown>, table: Table): boolean {\n  let columnName: string | undefined;\n  let argument: unknown;\n  for (const chunk of chunks) {\n    if (typeof chunk.name === \"string\" && chunk.table !== undefined) {\n      columnName = chunk.name;\n    } else if (\"brand\" in chunk) {\n      argument = chunk.value;\n    }\n  }\n  if (columnName === undefined) {\n    return false;\n  }\n  return row[columnKey(table, columnName)] === argument;\n}\n\n/* eslint-disable complexity, max-depth -- handles drizzle's varied chunk shapes */\nfunction inArrayMatches(chunks: SqlChunk[], row: Record<string, unknown>, table: Table): boolean {\n  let columnName: string | undefined;\n  const values: unknown[] = [];\n  const collect = (nodes: unknown[]): void => {\n    for (const raw of nodes as SqlChunk[]) {\n      const chunk = raw as SqlChunk & Record<string, unknown>;\n      // Handle array-like chunk (inArray values stored as array of chunks)\n      if (\n        Array.isArray(chunk) ||\n        (chunk && typeof chunk === \"object\" && Object.keys(chunk).every((k) => /^\\d+$/u.test(k)))\n      ) {\n        collect(Object.values(chunk as unknown as Record<string, unknown>) as unknown[]);\n        continue;\n      }\n      if (typeof chunk.name === \"string\" && chunk.table !== undefined) {\n        columnName = chunk.name as string;\n      }\n      if (\"brand\" in chunk && (chunk as Record<string, unknown>)[\"value\"] !== undefined) {\n        const val = (chunk as Record<string, unknown>)[\"value\"];\n        if (Array.isArray(val)) {\n          values.push(...(val as unknown[]));\n        } else {\n          values.push(val);\n        }\n      }\n      if (chunk.queryChunks) {\n        collect(chunk.queryChunks as unknown[]);\n      }\n      const val = (chunk as Record<string, unknown>)[\"value\"];\n      if (Array.isArray(val)) {\n        for (const item of val as unknown[]) {\n          if (\n            item &&\n            typeof item === \"object\" &&\n            \"queryChunks\" in (item as Record<string, unknown>)\n          ) {\n            collect(((item as Record<string, unknown>)[\"queryChunks\"] as unknown[]) ?? []);\n          }\n          if (item && typeof item === \"object\" && \"value\" in (item as Record<string, unknown>)) {\n            const iv = (item as Record<string, unknown>)[\"value\"];\n            if (iv !== undefined) {\n              values.push(iv);\n            }\n          }\n          if (typeof item === \"string\") {\n            values.push(item);\n          }\n        }\n      }\n    }\n  };\n  collect(chunks as unknown[]);\n  if (columnName === undefined) {\n    return false;\n  }\n  const key = columnKey(table, columnName);\n  return values.includes(row[key]);\n}\n/* eslint-enable complexity, max-depth */\n\nfunction ltMatches(chunks: SqlChunk[], row: Record<string, unknown>, table: Table): boolean {\n  let columnName: string | undefined;\n  let argument: unknown;\n  for (const chunk of chunks) {\n    if (typeof chunk.name === \"string\" && chunk.table !== undefined) {\n      columnName = chunk.name;\n    } else if (\"brand\" in chunk) {\n      argument = chunk.value;\n    }\n  }\n  if (columnName === undefined) {\n    return false;\n  }\n  const key = columnKey(table, columnName);\n  const cell = row[key];\n  if (typeof cell === \"string\" && typeof argument === \"string\") {\n    return cell < argument;\n  }\n  if (typeof cell === \"number\" && typeof argument === \"number\") {\n    return cell < argument;\n  }\n  return String(cell) < String(argument);\n}\n\nfunction compareCells(left: unknown, right: unknown): number {\n  if (typeof left === \"string\" && typeof right === \"string\") {\n    if (left === right) {\n      return 0;\n    }\n    return left < right ? -1 : 1;\n  }\n  if (typeof left === \"number\" && typeof right === \"number\") {\n    return left - right;\n  }\n  const leftText = String(left);\n  const rightText = String(right);\n  if (leftText === rightText) {\n    return 0;\n  }\n  return leftText < rightText ? -1 : 1;\n}\n\n/** Collect every raw string part of a drizzle SQL chunk tree. */\nfunction sqlText(nodes: SqlChunk[]): string {\n  return nodes\n    .map((node) => {\n      const own = textOf(node) ?? \"\";\n      const nested = node.queryChunks ? sqlText(node.queryChunks as unknown as SqlChunk[]) : \"\";\n      return own + nested;\n    })\n    .join(\"\");\n}\n\n/** Find the ordered column reference in a drizzle order-by expression. */\nfunction findOrderColumn(nodes: SqlChunk[]): string | undefined {\n  for (const node of nodes) {\n    if (typeof node.name === \"string\" && node.table !== undefined) {\n      return node.name;\n    }\n    if (node.queryChunks) {\n      const nested = findOrderColumn(node.queryChunks as unknown as SqlChunk[]);\n      if (nested !== undefined) {\n        return nested;\n      }\n    }\n  }\n  return undefined;\n}\n\n/** Sort rows per a drizzle order-by expression (single-column asc/desc). */\nexport function orderRows(rows: unknown[], orderBy: SQL, table: Table): unknown[] {\n  const chunks = orderBy.queryChunks as unknown as SqlChunk[];\n  const columnName = findOrderColumn(chunks);\n  if (columnName === undefined) {\n    return rows;\n  }\n  const key = columnKey(table, columnName);\n  const descending = /desc/iu.test(sqlText(chunks));\n  return rows.toSorted((left, right) => {\n    const order = compareCells(\n      (left as Record<string, unknown>)[key],\n      (right as Record<string, unknown>)[key],\n    );\n    return descending ? -order : order;\n  });\n}\n\nfunction columnKey(table: Table, dbName: string): string {\n  for (const [property, column] of Object.entries(getTableColumns(table))) {\n    if (column.name === dbName) {\n      return property;\n    }\n  }\n  return dbName;\n}\n/* eslint-enable require-await, no-unnecessary-type-assertion, no-unnecessary-type-parameters, non-nullable-type-assertion-style */\n"],"mappings":"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"}
+{"version":3,"file":"sql-chunks.mjs","names":[],"sources":["../../src/test-helpers/sql-chunks.ts"],"sourcesContent":["import { getTableColumns, type SQL, type Table } from \"drizzle-orm\";\n\n/* eslint-disable require-await, no-unnecessary-type-assertion, no-unnecessary-type-parameters, non-nullable-type-assertion-style */\n\n/** A drizzle SQL chunk inspected for matching and ordering. */\nexport interface SqlChunk {\n  value?: unknown;\n  name?: string;\n  table?: unknown;\n  brand?: unknown;\n  queryChunks?: SqlChunk[];\n}\n\n/** Flatten the string parts of a drizzle SQL chunk into a single string. */\nfunction textOf(chunk: SqlChunk | undefined): string | undefined {\n  if (\n    chunk === undefined ||\n    !Array.isArray(chunk.value) ||\n    !chunk.value.every((part) => typeof part === \"string\")\n  ) {\n    return undefined;\n  }\n  return chunk.value.join(\"\");\n}\n\n/** Test whether an in-memory row satisfies a drizzle where-clause. */\nexport function whereMatches(where: SQL, row: Record<string, unknown>, table: Table): boolean {\n  let current = where.queryChunks as unknown as SqlChunk[];\n  let wrapped = current[1]?.queryChunks;\n  while (wrapped !== undefined && textOf(current[0]) === \"(\" && textOf(current.at(-1)) === \")\") {\n    current = wrapped;\n    wrapped = current[1]?.queryChunks;\n  }\n  // Drizzle's `and(singleCondition)` emits the condition directly, without\n  // the enclosing parens produced for two or more clauses, so unwrap it.\n  if (current.length === 1 && current[0]?.queryChunks !== undefined) {\n    current = current[0].queryChunks as unknown as SqlChunk[];\n  }\n  if (current.some((chunk) => textOf(chunk)?.trim() === \"and\")) {\n    return current\n      .filter((chunk) => textOf(chunk) === undefined)\n      .every((chunk) => matchChunk(chunk.queryChunks ?? [], row, table));\n  }\n  return matchChunk(current, row, table);\n}\n\nfunction matchChunk(chunks: SqlChunk[], row: Record<string, unknown>, table: Table): boolean {\n  const text = chunks.map((c) => textOf(c) ?? \"\").join(\"\");\n  if (/is not null/iu.test(text)) {\n    return isNullMatches(chunks, row, table, true);\n  }\n  if (/is null/iu.test(text)) {\n    return isNullMatches(chunks, row, table, false);\n  }\n  if (text.includes(\" <> \")) {\n    return !eqMatches(chunks, row, table);\n  }\n  if (text.includes(\" like \")) {\n    return likeMatches(chunks, row, table);\n  }\n  if (text.includes(\" in \")) {\n    return inArrayMatches(chunks, row, table);\n  }\n  if (text.includes(\" >= \")) {\n    return !ltMatches(chunks, row, table);\n  }\n  if (text.includes(\" <= \")) {\n    return lteMatches(chunks, row, table);\n  }\n  if (text.includes(\" < \")) {\n    return ltMatches(chunks, row, table);\n  }\n  return eqMatches(chunks, row, table);\n}\n\n/** Match `is null` / `is not null` predicates (no value argument). */\nfunction isNullMatches(\n  chunks: SqlChunk[],\n  row: Record<string, unknown>,\n  table: Table,\n  negated: boolean,\n): boolean {\n  let columnName: string | undefined;\n  for (const chunk of chunks) {\n    if (typeof chunk.name === \"string\" && chunk.table !== undefined) {\n      columnName = chunk.name;\n    }\n  }\n  if (columnName === undefined) {\n    return false;\n  }\n  const cell = row[columnKey(table, columnName)];\n  const missing = cell === null || cell === undefined;\n  return negated ? !missing : missing;\n}\n\nfunction eqMatches(chunks: SqlChunk[], row: Record<string, unknown>, table: Table): boolean {\n  let columnName: string | undefined;\n  let argument: unknown;\n  for (const chunk of chunks) {\n    if (typeof chunk.name === \"string\" && chunk.table !== undefined) {\n      columnName = chunk.name;\n    } else if (\"brand\" in chunk) {\n      argument = chunk.value;\n    }\n  }\n  if (columnName === undefined) {\n    return false;\n  }\n  return row[columnKey(table, columnName)] === argument;\n}\n\n/** Match `column like 'pattern'`: `%` is any run of characters, `_` any one; everything else literal. */\nfunction likeMatches(chunks: SqlChunk[], row: Record<string, unknown>, table: Table): boolean {\n  let columnName: string | undefined;\n  let pattern: unknown;\n  for (const chunk of chunks as unknown[]) {\n    if (typeof chunk === \"string\") {\n      pattern = chunk;\n    } else if (chunk !== null && typeof chunk === \"object\") {\n      const node = chunk as SqlChunk;\n      if (typeof node.name === \"string\" && node.table !== undefined) {\n        columnName = node.name;\n      } else if (\"brand\" in node) {\n        pattern = node.value;\n      }\n    }\n  }\n  const cell = columnName === undefined ? undefined : row[columnKey(table, columnName)];\n  if (typeof cell !== \"string\" || typeof pattern !== \"string\") {\n    return false;\n  }\n  const source = pattern.replaceAll(/[.*+?^${}()|[\\]\\\\]/gu, String.raw`\\$&`);\n  return new RegExp(`^${source.replaceAll(\"%\", \".*\").replaceAll(\"_\", \".\")}$`, \"su\").test(cell);\n}\n\n/* eslint-disable complexity, max-depth -- handles drizzle's varied chunk shapes */\nfunction inArrayMatches(chunks: SqlChunk[], row: Record<string, unknown>, table: Table): boolean {\n  let columnName: string | undefined;\n  const values: unknown[] = [];\n  const collect = (nodes: unknown[]): void => {\n    for (const raw of nodes as SqlChunk[]) {\n      const chunk = raw as SqlChunk & Record<string, unknown>;\n      // Handle array-like chunk (inArray values stored as array of chunks)\n      if (\n        Array.isArray(chunk) ||\n        (chunk && typeof chunk === \"object\" && Object.keys(chunk).every((k) => /^\\d+$/u.test(k)))\n      ) {\n        collect(Object.values(chunk as unknown as Record<string, unknown>) as unknown[]);\n        continue;\n      }\n      if (typeof chunk.name === \"string\" && chunk.table !== undefined) {\n        columnName = chunk.name as string;\n      }\n      if (\"brand\" in chunk && (chunk as Record<string, unknown>)[\"value\"] !== undefined) {\n        const val = (chunk as Record<string, unknown>)[\"value\"];\n        if (Array.isArray(val)) {\n          values.push(...(val as unknown[]));\n        } else {\n          values.push(val);\n        }\n      }\n      if (chunk.queryChunks) {\n        collect(chunk.queryChunks as unknown[]);\n      }\n      const val = (chunk as Record<string, unknown>)[\"value\"];\n      if (Array.isArray(val)) {\n        for (const item of val as unknown[]) {\n          if (\n            item &&\n            typeof item === \"object\" &&\n            \"queryChunks\" in (item as Record<string, unknown>)\n          ) {\n            collect(((item as Record<string, unknown>)[\"queryChunks\"] as unknown[]) ?? []);\n          }\n          if (item && typeof item === \"object\" && \"value\" in (item as Record<string, unknown>)) {\n            const iv = (item as Record<string, unknown>)[\"value\"];\n            if (iv !== undefined) {\n              values.push(iv);\n            }\n          }\n          if (typeof item === \"string\") {\n            values.push(item);\n          }\n        }\n      }\n    }\n  };\n  collect(chunks as unknown[]);\n  if (columnName === undefined) {\n    return false;\n  }\n  const key = columnKey(table, columnName);\n  return values.includes(row[key]);\n}\n/* eslint-enable complexity, max-depth */\n\n/** `column <= value`: the cell is present and not greater than the argument. */\nfunction lteMatches(chunks: SqlChunk[], row: Record<string, unknown>, table: Table): boolean {\n  if (ltMatches(chunks, row, table)) {\n    return true;\n  }\n  return eqMatches(chunks, row, table);\n}\n\nfunction ltMatches(chunks: SqlChunk[], row: Record<string, unknown>, table: Table): boolean {\n  let columnName: string | undefined;\n  let argument: unknown;\n  for (const chunk of chunks) {\n    if (typeof chunk.name === \"string\" && chunk.table !== undefined) {\n      columnName = chunk.name;\n    } else if (\"brand\" in chunk) {\n      argument = chunk.value;\n    }\n  }\n  if (columnName === undefined) {\n    return false;\n  }\n  const key = columnKey(table, columnName);\n  const cell = row[key];\n  if (typeof cell === \"string\" && typeof argument === \"string\") {\n    return cell < argument;\n  }\n  if (typeof cell === \"number\" && typeof argument === \"number\") {\n    return cell < argument;\n  }\n  return String(cell) < String(argument);\n}\n\nfunction compareCells(left: unknown, right: unknown): number {\n  if (typeof left === \"string\" && typeof right === \"string\") {\n    if (left === right) {\n      return 0;\n    }\n    return left < right ? -1 : 1;\n  }\n  if (typeof left === \"number\" && typeof right === \"number\") {\n    return left - right;\n  }\n  const leftText = String(left);\n  const rightText = String(right);\n  if (leftText === rightText) {\n    return 0;\n  }\n  return leftText < rightText ? -1 : 1;\n}\n\n/** Collect every raw string part of a drizzle SQL chunk tree. */\nfunction sqlText(nodes: SqlChunk[]): string {\n  return nodes\n    .map((node) => {\n      const own = textOf(node) ?? \"\";\n      const nested = node.queryChunks ? sqlText(node.queryChunks as unknown as SqlChunk[]) : \"\";\n      return own + nested;\n    })\n    .join(\"\");\n}\n\n/** Find the ordered column reference in a drizzle order-by expression. */\nfunction findOrderColumn(nodes: SqlChunk[]): string | undefined {\n  for (const node of nodes) {\n    if (typeof node.name === \"string\" && node.table !== undefined) {\n      return node.name;\n    }\n    if (node.queryChunks) {\n      const nested = findOrderColumn(node.queryChunks as unknown as SqlChunk[]);\n      if (nested !== undefined) {\n        return nested;\n      }\n    }\n  }\n  return undefined;\n}\n\n/** Sort rows per a drizzle order-by expression (single-column asc/desc). */\nexport function orderRows(rows: unknown[], orderBy: SQL, table: Table): unknown[] {\n  const chunks = orderBy.queryChunks as unknown as SqlChunk[];\n  const columnName = findOrderColumn(chunks);\n  if (columnName === undefined) {\n    return rows;\n  }\n  const key = columnKey(table, columnName);\n  const descending = /desc/iu.test(sqlText(chunks));\n  return rows.toSorted((left, right) => {\n    const order = compareCells(\n      (left as Record<string, unknown>)[key],\n      (right as Record<string, unknown>)[key],\n    );\n    return descending ? -order : order;\n  });\n}\n\nfunction columnKey(table: Table, dbName: string): string {\n  for (const [property, column] of Object.entries(getTableColumns(table))) {\n    if (column.name === dbName) {\n      return property;\n    }\n  }\n  return dbName;\n}\n/* eslint-enable require-await, no-unnecessary-type-assertion, no-unnecessary-type-parameters, non-nullable-type-assertion-style */\n"],"mappings":"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"}

package/dist/test-helpers/storage-contract.d.mts

@@ -1,11 +1,9 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { StorageAdapter } from "../adapter/storage.mjs";
-//#region src/test-helpers/storage-contract.d.ts
 /** Build the adapter under test (sync or async factories both work). */
 type StorageFactory = () => StorageAdapter | Promise<StorageAdapter>;
 /** Run the full storage contract against a factory. */
 declare function storageContractSuite(label: string, make: StorageFactory): void;
-//#endregion
 export { StorageFactory, storageContractSuite };
 //# sourceMappingURL=storage-contract.d.mts.map

package/dist/test-helpers/storage-contract.mjs

@@ -1,9 +1,9 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-import { describe, expect, it } from "vitest";
 import { Readable } from "node:stream";
-//#region src/test-helpers/storage-contract.ts
+import { describe, expect, it } from "vitest";
+// src/test-helpers/storage-contract.ts
 /**
 * Published storage contract suite for first- and third-party adapters.
 *
@@ -81,7 +81,6 @@ function storageContractSuite(label, make) {
 		});
 	});
 }
-//#endregion
 export { storageContractSuite };
 
 //# sourceMappingURL=storage-contract.mjs.map

package/dist/test-helpers.d.mts

@@ -1,13 +1,19 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
+import { Deferred, Latch, ReleaseQueue, createLatch, createReleaseQueue, deferred } from "./test-helpers/deferred.mjs";
+import { DesignContractSamples, designContractSuite } from "./test-helpers/design-contract.mjs";
 import { createTestBuild, createTestProject } from "./test-helpers/create-project.mjs";
 import { REQUIRED_TABLES, databaseContractSuite } from "./test-helpers/database-contract.mjs";
-import { gitContractSuite } from "./test-helpers/git-contract.mjs";
+import { FAKE_PNG, FakeDesign, fakeUrl, makeFakeDesign } from "./test-helpers/fake-design.mjs";
 import { makeDatabase } from "./test-helpers/fake-database.mjs";
 import { FakeStorage, makeStorage } from "./test-helpers/fake-storage.mjs";
 import { stubTables } from "./test-helpers/fake-adapters.mjs";
-import { notifierContractSuite } from "./test-helpers/notifier-contract.mjs";
-import { queueContractSuite } from "./test-helpers/queue-contract.mjs";
+import { notifierContractSuite, stateNotifierContractSuite } from "./test-helpers/notifier-contract.mjs";
+import { PollableContractOptions, QueueContractOptions, QueueFactory, queueContractSuite } from "./test-helpers/queue-contract.mjs";
+import { MultiInstanceOptions, SharedDatabaseFactory, databaseQueueMultiInstanceSuite } from "./test-helpers/queue-multi-instance.mjs";
+import { ManualClock, createManualClock } from "./test-helpers/manual-clock.mjs";
 import { runnerContractSuite } from "./test-helpers/runner-contract.mjs";
 import { storageContractSuite } from "./test-helpers/storage-contract.mjs";
-export { type FakeStorage, REQUIRED_TABLES, createTestBuild, createTestProject, databaseContractSuite, gitContractSuite, makeDatabase, makeStorage, notifierContractSuite, queueContractSuite, runnerContractSuite, storageContractSuite, stubTables };
+import { FakeStateNotifier, makeFakeStateNotifier } from "./test-helpers/fake-notifier.mjs";
+import { BuildReferenceContractFixture, BuildReferenceContractFixtureRunner, buildReferenceContractSuite } from "./test-helpers/build-reference-contract.mjs";
+export { type BuildReferenceContractFixture, type BuildReferenceContractFixtureRunner, type Deferred, type DesignContractSamples, FAKE_PNG, type FakeDesign, type FakeStateNotifier, type FakeStorage, type Latch, type ManualClock, type MultiInstanceOptions, type PollableContractOptions, type QueueContractOptions, type QueueFactory, REQUIRED_TABLES, type ReleaseQueue, type SharedDatabaseFactory, buildReferenceContractSuite, createLatch, createManualClock, createReleaseQueue, createTestBuild, createTestProject, databaseContractSuite, databaseQueueMultiInstanceSuite, deferred, designContractSuite, fakeUrl, makeDatabase, makeFakeDesign, makeFakeStateNotifier, makeStorage, notifierContractSuite, queueContractSuite, runnerContractSuite, stateNotifierContractSuite, storageContractSuite, stubTables };

package/dist/test-helpers.mjs

@@ -1,14 +1,20 @@
 import "node:path";
 import "node:url";
 import.meta.url;
+import { createLatch, createReleaseQueue, deferred } from "./test-helpers/deferred.mjs";
+import { designContractSuite } from "./test-helpers/design-contract.mjs";
 import { createTestBuild, createTestProject } from "./test-helpers/create-project.mjs";
 import { REQUIRED_TABLES, databaseContractSuite } from "./test-helpers/database-contract.mjs";
-import { gitContractSuite } from "./test-helpers/git-contract.mjs";
+import { FAKE_PNG, fakeUrl, makeFakeDesign } from "./test-helpers/fake-design.mjs";
 import { makeDatabase } from "./test-helpers/fake-database.mjs";
 import { makeStorage } from "./test-helpers/fake-storage.mjs";
 import { stubTables } from "./test-helpers/fake-adapters.mjs";
-import { notifierContractSuite } from "./test-helpers/notifier-contract.mjs";
+import { notifierContractSuite, stateNotifierContractSuite } from "./test-helpers/notifier-contract.mjs";
 import { queueContractSuite } from "./test-helpers/queue-contract.mjs";
+import { databaseQueueMultiInstanceSuite } from "./test-helpers/queue-multi-instance.mjs";
+import { createManualClock } from "./test-helpers/manual-clock.mjs";
 import { runnerContractSuite } from "./test-helpers/runner-contract.mjs";
 import { storageContractSuite } from "./test-helpers/storage-contract.mjs";
-export { REQUIRED_TABLES, createTestBuild, createTestProject, databaseContractSuite, gitContractSuite, makeDatabase, makeStorage, notifierContractSuite, queueContractSuite, runnerContractSuite, storageContractSuite, stubTables };
+import { makeFakeStateNotifier } from "./test-helpers/fake-notifier.mjs";
+import { buildReferenceContractSuite } from "./test-helpers/build-reference-contract.mjs";
+export { FAKE_PNG, REQUIRED_TABLES, buildReferenceContractSuite, createLatch, createManualClock, createReleaseQueue, createTestBuild, createTestProject, databaseContractSuite, databaseQueueMultiInstanceSuite, deferred, designContractSuite, fakeUrl, makeDatabase, makeFakeDesign, makeFakeStateNotifier, makeStorage, notifierContractSuite, queueContractSuite, runnerContractSuite, stateNotifierContractSuite, storageContractSuite, stubTables };

package/dist/tracing.mjs

@@ -1,8 +1,9 @@
 import "node:path";
 import "node:url";
 import.meta.url;
+import { redactSecrets } from "./utils/redact.mjs";
 import { SpanKind, SpanStatusCode, context, propagation, trace } from "@opentelemetry/api";
-//#region src/tracing.ts
+// src/tracing.ts
 /**
 * Internal span and propagation helpers over `@opentelemetry/api`.
 *
@@ -15,11 +16,41 @@ import { SpanKind, SpanStatusCode, context, propagation, trace } from "@opentele
 const SCOPE = "storyshelf.core";
 /** W3C traceparent header name. */
 const TRACEPARENT_HEADER = "traceparent";
+/** What a span records of an error instead of its message, set by the code that knows the error. */
+const spanMessages = /* @__PURE__ */ new WeakMap();
+/**
+* State what spans record as the message of `error`, instead of its own: an outbound HTTP failure
+* is recorded as its status, never the response body it carries. The error itself is not touched,
+* so what a caller catches is unchanged.
+*/
+function setSpanMessage(error, message) {
+	if (typeof error === "object" && error !== null) spanMessages.set(error, message);
+}
+/**
+* The form of a failure that may be recorded on a span: a new error of the same name whose message
+* (the one given to {@link setSpanMessage}, else the error's own) has gone through
+* `redactSecrets`, with the original's stack frames. Never the original, whose message, stack
+* header or `cause` can repeat a URL, a token or a response body. A thrown non-error is stringified
+* and redacted. This is the one way core records an exception on a span.
+*/
+function spanException(error) {
+	if (!(error instanceof Error)) return redactSecrets(String(error));
+	const message = redactSecrets(spanMessages.get(error) ?? error.message);
+	const copy = new Error(message);
+	copy.name = error.name;
+	copy.stack = `${error.name}: ${message}${redactSecrets(framesOf(error))}`;
+	return copy;
+}
+/** The stack after its `Name: message` header, which may hold what the span must not record. */
+function framesOf(error) {
+	const header = `${error.name}: ${error.message}`;
+	return error.stack?.startsWith(header) ? error.stack.slice(header.length) : "";
+}
 /**
 * Run `fn` inside an internal span.
 *
-* On throw the span records the exception, is marked ERROR, and the error
-* is rethrown — mirroring the pino `{ err }` convention.
+* On throw the span records a redacted copy of the exception ({@link spanException}), is marked
+* ERROR, and the original error is rethrown untouched — mirroring the pino `{ err }` convention.
 *
 * @param name - Span name (`domain.operation`, never a high-cardinality value).
 * @param fn - Work to run with the span active.
@@ -35,7 +66,7 @@ async function withSpan(name, fn, attributes, parent) {
 		try {
 			return await fn(span);
 		} catch (error) {
-			span.recordException(error instanceof Error ? error : String(error));
+			span.recordException(spanException(error));
 			span.setStatus({ code: SpanStatusCode.ERROR });
 			throw error;
 		} finally {
@@ -57,7 +88,6 @@ function parentContext(traceparent) {
 function injectTraceContext(headers) {
 	propagation.inject(context.active(), headers);
 }
-//#endregion
-export { injectTraceContext, parentContext, withSpan };
+export { injectTraceContext, parentContext, setSpanMessage, spanException, withSpan };
 
 //# sourceMappingURL=tracing.mjs.map

package/dist/tracing.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"tracing.mjs","names":[],"sources":["../src/tracing.ts"],"sourcesContent":["/**\n * Internal span and propagation helpers over `@opentelemetry/api`.\n *\n * Not exported from the package surface (see `package.json` exports): other\n * packages use `@storyshelf/observability`. Without a configured provider\n * every helper is a cheap noop, so call sites need no enabled-checks and\n * the hermetic vitest suite stays network-free.\n */\nimport {\n  SpanKind,\n  SpanStatusCode,\n  context,\n  propagation,\n  trace,\n  type Attributes,\n  type Context,\n  type Span,\n} from \"@opentelemetry/api\";\n\n/** Instrumentation scope for core spans. */\nconst SCOPE = \"storyshelf.core\";\n\n/** W3C traceparent header name. */\nconst TRACEPARENT_HEADER = \"traceparent\";\n\n/**\n * Run `fn` inside an internal span.\n *\n * On throw the span records the exception, is marked ERROR, and the error\n * is rethrown — mirroring the pino `{ err }` convention.\n *\n * @param name - Span name (`domain.operation`, never a high-cardinality value).\n * @param fn - Work to run with the span active.\n * @param attributes - Fixed span attributes.\n * @param parent - Parent context (defaults to the active context).\n * @returns Whatever `fn` returns.\n */\nexport async function withSpan<T>(\n  name: string,\n  fn: (span: Span) => Promise<T>,\n  attributes?: Attributes,\n  parent?: Context,\n): Promise<T> {\n  const tracer = trace.getTracer(SCOPE);\n  return await tracer.startActiveSpan(\n    name,\n    { kind: SpanKind.INTERNAL, attributes },\n    parent ?? context.active(),\n    async (span) => {\n      try {\n        return await fn(span);\n      } catch (error) {\n        span.recordException(error instanceof Error ? error : String(error));\n        span.setStatus({ code: SpanStatusCode.ERROR });\n        throw error;\n      } finally {\n        span.end();\n      }\n    },\n  );\n}\n\n/**\n * Resolve the parent context from an inbound `traceparent` value.\n *\n * @param traceparent - W3C value from a queue payload; absent keeps context.\n * @returns The extracted remote context, or the active context when absent.\n */\nexport function parentContext(traceparent?: string): Context {\n  if (!traceparent) {\n    return context.active();\n  }\n  return propagation.extract(context.active(), { [TRACEPARENT_HEADER]: traceparent });\n}\n\n/** Inject the active span context into a mutable header record. */\nexport function injectTraceContext(headers: Record<string, string>): void {\n  propagation.inject(context.active(), headers);\n}\n\n/**\n * Read the current W3C `traceparent` value for queue payloads.\n *\n * @returns The header value, or undefined when no span is active.\n */\nexport function currentTraceparent(): string | undefined {\n  const carrier: Record<string, string> = {};\n  propagation.inject(context.active(), carrier);\n  return carrier[TRACEPARENT_HEADER];\n}\n"],"mappings":";;;;;;;;;;;;;;AAoBA,MAAM,QAAQ;;AAGd,MAAM,qBAAqB;;;;;;;;;;;;;AAc3B,eAAsB,SACpB,MACA,IACA,YACA,QACY;CAEZ,OAAO,MADQ,MAAM,UAAU,KACb,CAAC,CAAC,gBAClB,MACA;EAAE,MAAM,SAAS;EAAU;CAAW,GACtC,UAAU,QAAQ,OAAO,GACzB,OAAO,SAAS;EACd,IAAI;GACF,OAAO,MAAM,GAAG,IAAI;EACtB,SAAS,OAAO;GACd,KAAK,gBAAgB,iBAAiB,QAAQ,QAAQ,OAAO,KAAK,CAAC;GACnE,KAAK,UAAU,EAAE,MAAM,eAAe,MAAM,CAAC;GAC7C,MAAM;EACR,UAAU;GACR,KAAK,IAAI;EACX;CACF,CACF;AACF;;;;;;;AAQA,SAAgB,cAAc,aAA+B;CAC3D,IAAI,CAAC,aACH,OAAO,QAAQ,OAAO;CAExB,OAAO,YAAY,QAAQ,QAAQ,OAAO,GAAG,GAAG,qBAAqB,YAAY,CAAC;AACpF;;AAGA,SAAgB,mBAAmB,SAAuC;CACxE,YAAY,OAAO,QAAQ,OAAO,GAAG,OAAO;AAC9C"}
+{"version":3,"file":"tracing.mjs","names":[],"sources":["../src/tracing.ts"],"sourcesContent":["/**\n * Internal span and propagation helpers over `@opentelemetry/api`.\n *\n * Not exported from the package surface (see `package.json` exports): other\n * packages use `@storyshelf/observability`. Without a configured provider\n * every helper is a cheap noop, so call sites need no enabled-checks and\n * the hermetic vitest suite stays network-free.\n */\nimport {\n  SpanKind,\n  SpanStatusCode,\n  context,\n  propagation,\n  trace,\n  type Attributes,\n  type Context,\n  type Span,\n} from \"@opentelemetry/api\";\nimport { redactSecrets } from \"./utils/redact.ts\";\n\n/** Instrumentation scope for core spans. */\nconst SCOPE = \"storyshelf.core\";\n\n/** W3C traceparent header name. */\nconst TRACEPARENT_HEADER = \"traceparent\";\n\n/** What a span records of an error instead of its message, set by the code that knows the error. */\nconst spanMessages = new WeakMap<object, string>();\n\n/**\n * State what spans record as the message of `error`, instead of its own: an outbound HTTP failure\n * is recorded as its status, never the response body it carries. The error itself is not touched,\n * so what a caller catches is unchanged.\n */\nexport function setSpanMessage(error: unknown, message: string): void {\n  if (typeof error === \"object\" && error !== null) {\n    spanMessages.set(error, message);\n  }\n}\n\n/**\n * The form of a failure that may be recorded on a span: a new error of the same name whose message\n * (the one given to {@link setSpanMessage}, else the error's own) has gone through\n * `redactSecrets`, with the original's stack frames. Never the original, whose message, stack\n * header or `cause` can repeat a URL, a token or a response body. A thrown non-error is stringified\n * and redacted. This is the one way core records an exception on a span.\n */\nexport function spanException(error: unknown): Error | string {\n  if (!(error instanceof Error)) {\n    return redactSecrets(String(error));\n  }\n  const message = redactSecrets(spanMessages.get(error) ?? error.message);\n  const copy = new Error(message);\n  copy.name = error.name;\n  copy.stack = `${error.name}: ${message}${redactSecrets(framesOf(error))}`;\n  return copy;\n}\n\n/** The stack after its `Name: message` header, which may hold what the span must not record. */\nfunction framesOf(error: Error): string {\n  const header = `${error.name}: ${error.message}`;\n  return error.stack?.startsWith(header) ? error.stack.slice(header.length) : \"\";\n}\n\n/**\n * Run `fn` inside an internal span.\n *\n * On throw the span records a redacted copy of the exception ({@link spanException}), is marked\n * ERROR, and the original error is rethrown untouched — mirroring the pino `{ err }` convention.\n *\n * @param name - Span name (`domain.operation`, never a high-cardinality value).\n * @param fn - Work to run with the span active.\n * @param attributes - Fixed span attributes.\n * @param parent - Parent context (defaults to the active context).\n * @returns Whatever `fn` returns.\n */\nexport async function withSpan<T>(\n  name: string,\n  fn: (span: Span) => Promise<T>,\n  attributes?: Attributes,\n  parent?: Context,\n): Promise<T> {\n  const tracer = trace.getTracer(SCOPE);\n  return await tracer.startActiveSpan(\n    name,\n    { kind: SpanKind.INTERNAL, attributes },\n    parent ?? context.active(),\n    async (span) => {\n      try {\n        return await fn(span);\n      } catch (error) {\n        span.recordException(spanException(error));\n        span.setStatus({ code: SpanStatusCode.ERROR });\n        throw error;\n      } finally {\n        span.end();\n      }\n    },\n  );\n}\n\n/**\n * Resolve the parent context from an inbound `traceparent` value.\n *\n * @param traceparent - W3C value from a queue payload; absent keeps context.\n * @returns The extracted remote context, or the active context when absent.\n */\nexport function parentContext(traceparent?: string): Context {\n  if (!traceparent) {\n    return context.active();\n  }\n  return propagation.extract(context.active(), { [TRACEPARENT_HEADER]: traceparent });\n}\n\n/** Inject the active span context into a mutable header record. */\nexport function injectTraceContext(headers: Record<string, string>): void {\n  propagation.inject(context.active(), headers);\n}\n\n/**\n * Read the current W3C `traceparent` value for queue payloads.\n *\n * @returns The header value, or undefined when no span is active.\n */\nexport function currentTraceparent(): string | undefined {\n  const carrier: Record<string, string> = {};\n  propagation.inject(context.active(), carrier);\n  return carrier[TRACEPARENT_HEADER];\n}\n"],"mappings":";;;;;;;;;;;;;;;AAqBA,MAAM,QAAQ;;AAGd,MAAM,qBAAqB;;AAG3B,MAAM,+BAAe,IAAI,QAAwB;;;;;;AAOjD,SAAgB,eAAe,OAAgB,SAAuB;CACpE,IAAI,OAAO,UAAU,YAAY,UAAU,MACzC,aAAa,IAAI,OAAO,OAAO;AAEnC;;;;;;;;AASA,SAAgB,cAAc,OAAgC;CAC5D,IAAI,EAAE,iBAAiB,QACrB,OAAO,cAAc,OAAO,KAAK,CAAC;CAEpC,MAAM,UAAU,cAAc,aAAa,IAAI,KAAK,KAAK,MAAM,OAAO;CACtE,MAAM,OAAO,IAAI,MAAM,OAAO;CAC9B,KAAK,OAAO,MAAM;CAClB,KAAK,QAAQ,GAAG,MAAM,KAAK,IAAI,UAAU,cAAc,SAAS,KAAK,CAAC;CACtE,OAAO;AACT;;AAGA,SAAS,SAAS,OAAsB;CACtC,MAAM,SAAS,GAAG,MAAM,KAAK,IAAI,MAAM;CACvC,OAAO,MAAM,OAAO,WAAW,MAAM,IAAI,MAAM,MAAM,MAAM,OAAO,MAAM,IAAI;AAC9E;;;;;;;;;;;;;AAcA,eAAsB,SACpB,MACA,IACA,YACA,QACY;CAEZ,OAAO,MADQ,MAAM,UAAU,KACb,CAAC,CAAC,gBAClB,MACA;EAAE,MAAM,SAAS;EAAU;CAAW,GACtC,UAAU,QAAQ,OAAO,GACzB,OAAO,SAAS;EACd,IAAI;GACF,OAAO,MAAM,GAAG,IAAI;EACtB,SAAS,OAAO;GACd,KAAK,gBAAgB,cAAc,KAAK,CAAC;GACzC,KAAK,UAAU,EAAE,MAAM,eAAe,MAAM,CAAC;GAC7C,MAAM;EACR,UAAU;GACR,KAAK,IAAI;EACX;CACF,CACF;AACF;;;;;;;AAQA,SAAgB,cAAc,aAA+B;CAC3D,IAAI,CAAC,aACH,OAAO,QAAQ,OAAO;CAExB,OAAO,YAAY,QAAQ,QAAQ,OAAO,GAAG,GAAG,qBAAqB,YAAY,CAAC;AACpF;;AAGA,SAAgB,mBAAmB,SAAuC;CACxE,YAAY,OAAO,QAAQ,OAAO,GAAG,OAAO;AAC9C"}