@retinue/agentkit 0.2.0 → 0.3.0

package/dist/testing/conformance/files.js

@@ -0,0 +1,454 @@
+/**
+ * `FileMetadataStore` and `FileContentStore` conformance (#129).
+ *
+ * Both carry safety properties rather than only a data contract, and both are asserted here rather than
+ * assumed:
+ *
+ * - **A `contentKey` from one tenant must not resolve another's bytes.** The key is opaque and a caller
+ *   cannot construct one — but an adapter that took the key as sufficient would leak across tenants the
+ *   moment a key was guessed, logged or copied. #91 found an `AgentStore` that accepted `TenantScope` and
+ *   ignored it, which is why every adapter is asked the question directly.
+ * - **`transition` is a compare-and-set.** A blind write lets a conversation delete racing an upload leave a
+ *   file `stored` after its bytes were scheduled for removal — bytes that then never get swept, because
+ *   nothing is looking for a `stored` file's object.
+ */
+import { describe, expect, it } from "vitest";
+import { asId } from "../../core/ids.js";
+import { withConversation } from "./parents.js";
+const T1 = asId("conf-file-tenant-1");
+const T2 = asId("conf-file-tenant-2");
+const C1 = asId("conf-file-convo-1");
+const C2 = asId("conf-file-convo-2");
+const P1 = asId("conf-file-principal-1");
+/**
+ * `Omit<…, "id">` before the intersection, not `Partial<FileMetadata> & { id: string }`.
+ *
+ * The latter intersects `FileId | undefined` with `string`, so the parameter demanded a *branded* id and every
+ * call site passing `{ id: "f1" }` was a type error. Invisible until #253 put this directory under the compiler:
+ * it was excluded from `tsconfig`, and vitest transpiles without typechecking.
+ */
+const file = (over) => ({
+    conversationId: C1,
+    filename: "notes.pdf",
+    mediaType: "application/pdf",
+    byteSize: 1_024,
+    contentKey: `key-${over.id}`,
+    state: "stored",
+    uploadedBy: P1,
+    createdAt: "2026-08-23T10:00:00.000Z",
+    ...over,
+    id: asId(over.id),
+});
+const bytes = (text) => (async function* () {
+    yield new TextEncoder().encode(text);
+})();
+/**
+ * A real timestamp, because `at` is one.
+ *
+ * This was a placeholder string until #129 ran the harness against Postgres, which rejected it: the
+ * in-memory adapter had been storing whatever it was handed. The lesson is the matrix's whole purpose --
+ * a reference adapter laxer than the real one turns a production failure into a passing test -- so the
+ * placeholder became a timestamp and `rejects a non-timestamp \`at\`` below holds both adapters to it.
+ */
+const AT = "2026-08-23T12:00:00.000Z";
+export function fileMetadataStoreConformance(makeFixture) {
+    // A file references a conversation, and Postgres enforces that with a foreign key — so the parent has to
+    // exist before the child, and only the fixture can create it. Same shape as `messageStoreConformance`.
+    const open = (conversations = [C1]) => withConversation(makeFixture(), conversations.map((conversationId) => ({ tenantId: T1, conversationId })));
+    describe("FileMetadataStore conformance", () => {
+        it("stores and reads back a file", async () => {
+            const store = await open();
+            await store.create({ tenantId: T1, file: file({ id: "f1" }) });
+            expect(await store.get({ tenantId: T1, id: asId("f1") })).toMatchObject({
+                id: "f1",
+                filename: "notes.pdf",
+                state: "stored",
+            });
+        });
+        it("returns null for another tenant's file", async () => {
+            // Indistinguishable from absent, so the store cannot be used to probe which ids exist.
+            const store = await open();
+            await store.create({ tenantId: T1, file: file({ id: "f1" }) });
+            expect(await store.get({ tenantId: T2, id: asId("f1") })).toBeNull();
+        });
+        it("refuses to create the same id twice", async () => {
+            const store = await open();
+            await store.create({ tenantId: T1, file: file({ id: "f1" }) });
+            await expect(store.create({ tenantId: T1, file: file({ id: "f1" }) })).rejects.toThrow();
+        });
+        it("lists a conversation's live files, newest cursor last", async () => {
+            const store = await open([C1, C2]);
+            await store.create({ tenantId: T1, file: file({ id: "f1", createdAt: "2026-08-23T10:00:00.000Z" }) });
+            await store.create({ tenantId: T1, file: file({ id: "f2", createdAt: "2026-08-23T11:00:00.000Z" }) });
+            await store.create({ tenantId: T1, file: file({ id: "f3", conversationId: C2 }) });
+            const page = await store.listByConversation({ tenantId: T1, conversationId: C1, limit: 10 });
+            expect(page.items.map((f) => f.id)).toEqual(["f1", "f2"]);
+            // Another conversation's file is absent, not merely last.
+            expect(page.items.map((f) => f.id)).not.toContain("f3");
+        });
+        it("pages on a keyset cursor rather than an offset", async () => {
+            // An offset shifts when a row is inserted, so a caller paging a conversation while a file uploads
+            // either sees one twice or misses one.
+            const store = await open();
+            for (const n of [1, 2, 3, 4]) {
+                await store.create({
+                    tenantId: T1,
+                    file: file({ id: `f${n}`, createdAt: `2026-08-23T1${n}:00:00.000Z` }),
+                });
+            }
+            const first = await store.listByConversation({ tenantId: T1, conversationId: C1, limit: 2 });
+            expect(first.items.map((f) => f.id)).toEqual(["f1", "f2"]);
+            expect(first.nextCursor).toBeDefined();
+            const second = await store.listByConversation({
+                tenantId: T1,
+                conversationId: C1,
+                limit: 2,
+                cursor: first.nextCursor,
+            });
+            expect(second.items.map((f) => f.id)).toEqual(["f3", "f4"]);
+            // No cursor when the page is the last one, so a caller loops on its presence.
+            expect(second.nextCursor).toBeUndefined();
+        });
+        it("hides a soft-deleted file from the conversation listing", async () => {
+            const store = await open();
+            await store.create({ tenantId: T1, file: file({ id: "f1" }) });
+            await store.transition({
+                tenantId: T1,
+                id: asId("f1"),
+                from: "stored",
+                to: "deleting",
+                at: "2026-08-23T12:00:00.000Z",
+            });
+            // A deleted attachment reappearing in the list is the failure this guards.
+            const page = await store.listByConversation({ tenantId: T1, conversationId: C1, limit: 10 });
+            expect(page.items).toEqual([]);
+        });
+        it("moves a file only from the state the caller expected", async () => {
+            const store = await open();
+            await store.create({ tenantId: T1, file: file({ id: "f1", state: "pending" }) });
+            const wrong = await store.transition({
+                tenantId: T1,
+                id: asId("f1"),
+                from: "stored",
+                to: "deleted",
+                at: AT,
+            });
+            expect(wrong.moved).toBe(false);
+            expect(await store.get({ tenantId: T1, id: asId("f1") })).toMatchObject({ state: "pending" });
+            const right = await store.transition({
+                tenantId: T1,
+                id: asId("f1"),
+                from: "pending",
+                to: "stored",
+                at: AT,
+                checksum: "abc",
+            });
+            expect(right.moved).toBe(true);
+            expect(await store.get({ tenantId: T1, id: asId("f1") })).toMatchObject({
+                state: "stored",
+                checksum: "abc",
+            });
+        });
+        it("lets exactly one of two racing transitions win", async () => {
+            // The race that matters: a conversation delete and an upload completion both trying to move the same
+            // file. A blind write would let the upload land after the delete, leaving a `stored` file whose bytes
+            // are scheduled for removal — and nothing sweeps a `stored` file's object.
+            const store = await open();
+            await store.create({ tenantId: T1, file: file({ id: "f1", state: "pending" }) });
+            const results = await Promise.all([
+                store.transition({ tenantId: T1, id: asId("f1"), from: "pending", to: "stored", at: AT }),
+                store.transition({ tenantId: T1, id: asId("f1"), from: "pending", to: "deleting", at: AT }),
+            ]);
+            expect(results.filter((r) => r.moved)).toHaveLength(1);
+        });
+        it("does not transition another tenant's file", async () => {
+            const store = await open();
+            await store.create({ tenantId: T1, file: file({ id: "f1", state: "pending" }) });
+            const result = await store.transition({
+                tenantId: T2,
+                id: asId("f1"),
+                from: "pending",
+                to: "stored",
+                at: AT,
+            });
+            expect(result.moved).toBe(false);
+            expect(await store.get({ tenantId: T1, id: asId("f1") })).toMatchObject({ state: "pending" });
+        });
+        it("records an extraction outcome and reads it back", async () => {
+            // #131. Every field, because they are stored as separate columns in Postgres and a mapper that dropped
+            // one would still return a plausible record.
+            const store = await open();
+            await store.create({ tenantId: T1, file: file({ id: "f1" }) });
+            const { recorded } = await store.recordExtraction({
+                tenantId: T1,
+                id: asId("f1"),
+                extraction: {
+                    state: "extracted",
+                    ref: asId("blob-1"),
+                    pageCount: 3,
+                    blockCount: 42,
+                    truncated: false,
+                    at: AT,
+                },
+            });
+            expect(recorded).toBe(true);
+            expect((await store.get({ tenantId: T1, id: asId("f1") }))?.extraction).toEqual({
+                state: "extracted",
+                ref: "blob-1",
+                pageCount: 3,
+                blockCount: 42,
+                truncated: false,
+                at: AT,
+            });
+        });
+        it("records a typed failure with its reason and message", async () => {
+            // AC-4 of #131 depends on both surviving storage: the reason drives behaviour and the message is what
+            // the user reads, so a store that kept one and dropped the other would half-work.
+            const store = await open();
+            await store.create({ tenantId: T1, file: file({ id: "f1" }) });
+            await store.recordExtraction({
+                tenantId: T1,
+                id: asId("f1"),
+                extraction: {
+                    state: "failed",
+                    failureReason: "no-text-layer",
+                    failureMessage: "That PDF is a scan and needs OCR.",
+                    at: AT,
+                },
+            });
+            expect((await store.get({ tenantId: T1, id: asId("f1") }))?.extraction).toMatchObject({
+                state: "failed",
+                failureReason: "no-text-layer",
+                failureMessage: "That PDF is a scan and needs OCR.",
+            });
+        });
+        it("does not record an extraction against another tenant's file", async () => {
+            const store = await open();
+            await store.create({ tenantId: T1, file: file({ id: "f1" }) });
+            const { recorded } = await store.recordExtraction({
+                tenantId: T2,
+                id: asId("f1"),
+                extraction: { state: "extracted", at: AT },
+            });
+            // Reported rather than thrown: it is the same answer a file deleted mid-extraction gives, and a worker
+            // must be able to tell "gone" from "broken".
+            expect(recorded).toBe(false);
+            expect((await store.get({ tenantId: T1, id: asId("f1") }))?.extraction).toBeUndefined();
+        });
+        it("reports a file nobody has extracted as pending, not as absent", async () => {
+            // The property that makes the sweep able to find a lost enqueue: a file with no extraction record at
+            // all is waiting, which is the same fact as `pending`.
+            const store = await open();
+            await store.create({ tenantId: T1, file: file({ id: "f1" }) });
+            const page = await store.listByExtractionState({
+                tenantId: T1,
+                state: "pending",
+                olderThan: "2030-01-01T00:00:00.000Z",
+                limit: 10,
+            });
+            expect(page.items.map((f) => f.id)).toEqual(["f1"]);
+        });
+        it("finds an extraction stuck mid-parse", async () => {
+            // A worker that died leaves `running`, and nothing else would ever notice.
+            const store = await open();
+            await store.create({ tenantId: T1, file: file({ id: "f1" }) });
+            await store.create({ tenantId: T1, file: file({ id: "f2" }) });
+            await store.recordExtraction({ tenantId: T1, id: asId("f1"), extraction: { state: "running", at: AT } });
+            await store.recordExtraction({
+                tenantId: T1,
+                id: asId("f2"),
+                extraction: { state: "extracted", ref: asId("b"), at: AT },
+            });
+            const page = await store.listByExtractionState({
+                tenantId: T1,
+                state: "running",
+                olderThan: "2030-01-01T00:00:00.000Z",
+                limit: 10,
+            });
+            expect(page.items.map((f) => f.id)).toEqual(["f1"]);
+        });
+        it("does not list another tenant's stuck extraction", async () => {
+            const store = await open();
+            await store.create({ tenantId: T1, file: file({ id: "f1" }) });
+            const page = await store.listByExtractionState({
+                tenantId: T2,
+                state: "pending",
+                olderThan: "2030-01-01T00:00:00.000Z",
+                limit: 10,
+            });
+            expect(page.items).toEqual([]);
+        });
+        it("rejects a non-timestamp `at` rather than storing it", async () => {
+            // Found by running this harness against Postgres for the first time (#129): it rejected the
+            // placeholder string the in-memory adapter had been storing happily. Either behaviour is defensible
+            // in isolation; differing is not, because it makes a production write failure something the
+            // in-memory tests cannot see. Pinned here so neither adapter can drift back.
+            const store = await open();
+            await store.create({ tenantId: T1, file: file({ id: "f1", state: "pending" }) });
+            await expect(store.transition({ tenantId: T1, id: asId("f1"), from: "pending", to: "stored", at: "t" })).rejects.toThrow();
+            // And it did not move: a rejected write must not be a partial one.
+            expect(await store.get({ tenantId: T1, id: asId("f1") })).toMatchObject({ state: "pending" });
+        });
+        it("schedules every live file of a conversation in one call", async () => {
+            // One call rather than list-then-loop: a file uploaded between the two would be missed, leaving bytes
+            // for a conversation that no longer exists.
+            const store = await open([C1, C2]);
+            await store.create({ tenantId: T1, file: file({ id: "f1", state: "stored" }) });
+            await store.create({ tenantId: T1, file: file({ id: "f2", state: "pending" }) });
+            await store.create({ tenantId: T1, file: file({ id: "f3", conversationId: C2 }) });
+            const result = await store.scheduleConversationDeletion({
+                tenantId: T1,
+                conversationId: C1,
+                at: "2026-08-23T12:00:00.000Z",
+            });
+            // `pending` as well as `stored`: an in-flight upload must not complete into a deleted conversation.
+            expect(result.scheduled).toBe(2);
+            expect(await store.get({ tenantId: T1, id: asId("f1") })).toMatchObject({ state: "deleting" });
+            expect(await store.get({ tenantId: T1, id: asId("f2") })).toMatchObject({ state: "deleting" });
+            // Another conversation's file is untouched.
+            expect(await store.get({ tenantId: T1, id: asId("f3") })).toMatchObject({ state: "stored" });
+        });
+        it("does not schedule another tenant's conversation", async () => {
+            const store = await open();
+            await store.create({ tenantId: T1, file: file({ id: "f1" }) });
+            const result = await store.scheduleConversationDeletion({
+                tenantId: T2,
+                conversationId: C1,
+                at: AT,
+            });
+            expect(result.scheduled).toBe(0);
+            expect(await store.get({ tenantId: T1, id: asId("f1") })).toMatchObject({ state: "stored" });
+        });
+        it("lists by state only past the age threshold", async () => {
+            // Without the threshold the job reports every upload happening while it runs.
+            const store = await open();
+            await store.create({ tenantId: T1, file: file({ id: "old", state: "pending", createdAt: "2026-08-23T09:00:00.000Z" }) });
+            await store.create({ tenantId: T1, file: file({ id: "new", state: "pending", createdAt: "2026-08-23T12:00:00.000Z" }) });
+            const page = await store.listByState({
+                tenantId: T1,
+                state: "pending",
+                olderThan: "2026-08-23T10:00:00.000Z",
+                limit: 10,
+            });
+            expect(page.items.map((f) => f.id)).toEqual(["old"]);
+        });
+        it("does not list another tenant's files by state", async () => {
+            const store = await open();
+            await store.create({ tenantId: T1, file: file({ id: "f1", state: "pending" }) });
+            const page = await store.listByState({
+                tenantId: T2,
+                state: "pending",
+                olderThan: "2027-01-01T00:00:00.000Z",
+                limit: 10,
+            });
+            expect(page.items).toEqual([]);
+        });
+    });
+}
+export function fileContentStoreConformance(make) {
+    describe("FileContentStore conformance", () => {
+        it("writes bytes and reads them back unchanged", async () => {
+            const store = make();
+            const stored = await store.putFile({
+                tenantId: T1,
+                contentKey: "k1",
+                mediaType: "text/plain",
+                bytes: bytes("hello"),
+                maxBytes: 1_000,
+            });
+            expect(stored.byteSize).toBe(5);
+            expect(stored.checksum).toMatch(/^[0-9a-f]{64}$/);
+            const read = await store.readFile({ tenantId: T1, contentKey: "k1" });
+            expect(read).not.toBeNull();
+            const chunks = [];
+            for await (const chunk of read)
+                chunks.push(chunk);
+            expect(new TextDecoder().decode(Buffer.concat(chunks.map((c) => Buffer.from(c))))).toBe("hello");
+        });
+        it("does not resolve another tenant's key", async () => {
+            // The key is opaque and a caller cannot construct one — but an adapter treating the key as sufficient
+            // would leak the moment one was guessed, logged or copied.
+            const store = make();
+            await store.putFile({
+                tenantId: T1,
+                contentKey: "k1",
+                mediaType: "text/plain",
+                bytes: bytes("secret"),
+                maxBytes: 1_000,
+            });
+            expect(await store.readFile({ tenantId: T2, contentKey: "k1" })).toBeNull();
+        });
+        it("stops at the cap and writes nothing", async () => {
+            // Stops, rather than reading to the end and then refusing — and stores nothing, because a kept partial
+            // object is an orphan created by every oversized upload.
+            const store = make();
+            await expect(store.putFile({
+                tenantId: T1,
+                contentKey: "k1",
+                mediaType: "text/plain",
+                bytes: bytes("far too long"),
+                maxBytes: 4,
+            })).rejects.toThrow();
+            expect(await store.readFile({ tenantId: T1, contentKey: "k1" })).toBeNull();
+        });
+        it("deletes idempotently", async () => {
+            // A retried sweep depends on it: the sweep deletes bytes before moving the state, so a crash between
+            // them means the next run deletes an object that is already gone.
+            const store = make();
+            await store.putFile({
+                tenantId: T1,
+                contentKey: "k1",
+                mediaType: "text/plain",
+                bytes: bytes("x"),
+                maxBytes: 10,
+            });
+            await store.deleteFile({ tenantId: T1, contentKey: "k1" });
+            await expect(store.deleteFile({ tenantId: T1, contentKey: "k1" })).resolves.toBeUndefined();
+            expect(await store.readFile({ tenantId: T1, contentKey: "k1" })).toBeNull();
+        });
+        it("does not delete another tenant's object", async () => {
+            const store = make();
+            await store.putFile({
+                tenantId: T1,
+                contentKey: "k1",
+                mediaType: "text/plain",
+                bytes: bytes("keep"),
+                maxBytes: 10,
+            });
+            await store.deleteFile({ tenantId: T2, contentKey: "k1" });
+            expect(await store.readFile({ tenantId: T1, contentKey: "k1" })).not.toBeNull();
+        });
+        it("lists only this tenant's objects", async () => {
+            const store = make();
+            for (const [tenantId, key] of [
+                [T1, "a"],
+                [T1, "b"],
+                [T2, "c"],
+            ]) {
+                await store.putFile({ tenantId, contentKey: key, mediaType: "text/plain", bytes: bytes("x"), maxBytes: 10 });
+            }
+            const page = await store.listObjects({ tenantId: T1, limit: 10 });
+            expect(page.items.map((o) => o.contentKey).sort()).toEqual(["a", "b"]);
+        });
+        it("either signs with an expiry or returns null, never a durable URL", async () => {
+            // AC-6 as a property of the port. An adapter with no signing mechanism says so; one that signs must
+            // take an expiry, and there is no method that returns a URL without one.
+            const store = make();
+            await store.putFile({
+                tenantId: T1,
+                contentKey: "k1",
+                mediaType: "text/plain",
+                bytes: bytes("x"),
+                maxBytes: 10,
+            });
+            const url = await store.signedUrl({ tenantId: T1, contentKey: "k1", expiresInSeconds: 60 });
+            if (url !== null) {
+                // A signed URL carries its expiry somewhere in it. Asserted loosely because the parameter name is
+                // the provider's, and asserting a specific one would only test the adapter we happened to write.
+                expect(url).toMatch(/https?:\/\//);
+                expect(url.length).toBeGreaterThan("https://".length);
+            }
+        });
+    });
+}
+//# sourceMappingURL=files.js.map

package/dist/testing/conformance/flows.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The flow stores' shared contract — #187, #186.
+ *
+ * Runs against every adapter, so "the Postgres one behaves like the reference" is a fact rather than a claim about
+ * two hundred lines nobody compared. Two cases matter more than the rest and are the reason this file exists
+ * rather than per-adapter tests:
+ *
+ * - **A version cannot be overwritten.** An execution pins the version it started with and reads it for its whole
+ *   life, so a definition that could change under it would change an automation's shape halfway through.
+ * - **`save` is monotonic.** Two workers holding the same execution must not let the slower one move it
+ *   backwards, because a flow that goes backwards re-performs external writes.
+ */
+import type { FlowDefinitionStore, FlowExecutionStore } from "../../persistence/index.js";
+export declare function flowDefinitionStoreConformance(make: () => FlowDefinitionStore): void;
+export declare function flowExecutionStoreConformance(make: () => FlowExecutionStore): void;
+//# sourceMappingURL=flows.d.ts.map

package/dist/testing/conformance/flows.js

@@ -0,0 +1,193 @@
+/**
+ * The flow stores' shared contract — #187, #186.
+ *
+ * Runs against every adapter, so "the Postgres one behaves like the reference" is a fact rather than a claim about
+ * two hundred lines nobody compared. Two cases matter more than the rest and are the reason this file exists
+ * rather than per-adapter tests:
+ *
+ * - **A version cannot be overwritten.** An execution pins the version it started with and reads it for its whole
+ *   life, so a definition that could change under it would change an automation's shape halfway through.
+ * - **`save` is monotonic.** Two workers holding the same execution must not let the slower one move it
+ *   backwards, because a flow that goes backwards re-performs external writes.
+ */
+import { describe, expect, it } from "vitest";
+import { asId } from "../../core/ids.js";
+const T1 = asId("tenant-1");
+const T2 = asId("tenant-2");
+const definition = (over = {}) => ({
+    flowId: "onboard",
+    version: 1,
+    name: "Onboarding",
+    kind: "flow",
+    definition: { steps: [{ name: "a", kind: "done" }], start: "a" },
+    createdAt: "2026-08-26T10:00:00.000Z",
+    createdBy: asId("p1"),
+    ...over,
+});
+const execution = (over = {}) => ({
+    id: "exec-1",
+    flowId: "onboard",
+    flowVersion: 1,
+    runId: asId("run-1"),
+    status: "running",
+    currentStep: "a",
+    steps: 0,
+    execution: { state: {} },
+    startedAt: "2026-08-26T10:00:00.000Z",
+    ...over,
+});
+export function flowDefinitionStoreConformance(make) {
+    describe("FlowDefinitionStore conformance", () => {
+        it("stores and reads a definition by version", async () => {
+            const store = make();
+            await store.put({ tenantId: T1, definition: definition() });
+            const read = await store.get({ tenantId: T1, flowId: "onboard", version: 1 });
+            expect(read?.name).toBe("Onboarding");
+            expect(read?.definition).toEqual({ steps: [{ name: "a", kind: "done" }], start: "a" });
+        });
+        it("refuses to overwrite a version", async () => {
+            // The property an execution's version pin depends on. Without it, "the definition at version 1" is not a
+            // stable thing to have pinned.
+            const store = make();
+            await store.put({ tenantId: T1, definition: definition() });
+            await expect(store.put({ tenantId: T1, definition: definition({ name: "changed" }) })).rejects.toThrow();
+            expect((await store.get({ tenantId: T1, flowId: "onboard", version: 1 }))?.name).toBe("Onboarding");
+        });
+        it("keeps versions side by side and reports the latest", async () => {
+            const store = make();
+            await store.put({ tenantId: T1, definition: definition({ version: 1 }) });
+            await store.put({ tenantId: T1, definition: definition({ version: 3, name: "v3" }) });
+            await store.put({ tenantId: T1, definition: definition({ version: 2, name: "v2" }) });
+            expect((await store.latest({ tenantId: T1, flowId: "onboard" }))?.version).toBe(3);
+            // Every earlier version is still readable: an execution pinned to 1 must still find it.
+            expect((await store.get({ tenantId: T1, flowId: "onboard", version: 1 }))?.name).toBe("Onboarding");
+        });
+        it("returns null for an unknown flow or version rather than throwing", async () => {
+            const store = make();
+            expect(await store.get({ tenantId: T1, flowId: "nope", version: 1 })).toBeNull();
+            expect(await store.latest({ tenantId: T1, flowId: "nope" })).toBeNull();
+        });
+        it("does not resolve another tenant's definition", async () => {
+            const store = make();
+            await store.put({ tenantId: T1, definition: definition() });
+            expect(await store.get({ tenantId: T2, flowId: "onboard", version: 1 })).toBeNull();
+            expect(await store.latest({ tenantId: T2, flowId: "onboard" })).toBeNull();
+        });
+        it("lists the latest version of each flow, not every version", async () => {
+            const store = make();
+            await store.put({ tenantId: T1, definition: definition({ version: 1 }) });
+            await store.put({ tenantId: T1, definition: definition({ version: 2 }) });
+            await store.put({ tenantId: T1, definition: definition({ flowId: "other", version: 1 }) });
+            const listed = await store.list({ tenantId: T1, limit: 50 });
+            expect(listed.items.map((d) => [d.flowId, d.version]).sort()).toEqual([
+                ["onboard", 2],
+                ["other", 1],
+            ]);
+        });
+        it("pages the list", async () => {
+            const store = make();
+            for (const flowId of ["a", "b", "c"])
+                await store.put({ tenantId: T1, definition: definition({ flowId }) });
+            const first = await store.list({ tenantId: T1, limit: 2 });
+            expect(first.items).toHaveLength(2);
+            expect(first.nextCursor).toBeDefined();
+            const second = await store.list({ tenantId: T1, limit: 2, cursor: first.nextCursor });
+            expect(second.items.map((d) => d.flowId)).toEqual(["c"]);
+        });
+    });
+}
+export function flowExecutionStoreConformance(make) {
+    describe("FlowExecutionStore conformance", () => {
+        it("creates and reads an execution", async () => {
+            const store = make();
+            await store.create({ tenantId: T1, execution: execution() });
+            expect((await store.get({ tenantId: T1, executionId: "exec-1" }))?.currentStep).toBe("a");
+        });
+        it("refuses to create the same execution twice", async () => {
+            const store = make();
+            await store.create({ tenantId: T1, execution: execution() });
+            await expect(store.create({ tenantId: T1, execution: execution() })).rejects.toThrow();
+        });
+        it("saves forward", async () => {
+            const store = make();
+            await store.create({ tenantId: T1, execution: execution() });
+            await store.save({ tenantId: T1, execution: execution({ steps: 3, currentStep: "b" }) });
+            expect((await store.get({ tenantId: T1, executionId: "exec-1" }))?.steps).toBe(3);
+        });
+        it("ignores a save that would move the execution backwards", async () => {
+            /**
+             * The monotonic guard. Two workers holding the same execution: the slower one's document is stale, and
+             * writing it would rewind the flow — which re-performs whatever external writes the rewound steps did.
+             */
+            const store = make();
+            await store.create({ tenantId: T1, execution: execution() });
+            await store.save({ tenantId: T1, execution: execution({ steps: 5, currentStep: "e" }) });
+            await store.save({ tenantId: T1, execution: execution({ steps: 2, currentStep: "b" }) });
+            const read = await store.get({ tenantId: T1, executionId: "exec-1" });
+            expect(read?.steps).toBe(5);
+            expect(read?.currentStep).toBe("e");
+        });
+        it("accepts a save at the same step count, because a status can change without progress", async () => {
+            // Parking on a question completes no step. Rejecting an equal count would make "waiting" unrecordable.
+            const store = make();
+            await store.create({ tenantId: T1, execution: execution({ steps: 2 }) });
+            await store.save({ tenantId: T1, execution: execution({ steps: 2, status: "waiting", waitingSignal: "paid" }) });
+            expect((await store.get({ tenantId: T1, executionId: "exec-1" }))?.status).toBe("waiting");
+        });
+        it("does not resolve another tenant's execution", async () => {
+            const store = make();
+            await store.create({ tenantId: T1, execution: execution() });
+            expect(await store.get({ tenantId: T2, executionId: "exec-1" })).toBeNull();
+        });
+        it("finds executions parked on a signal, and only those", async () => {
+            const store = make();
+            await store.create({ tenantId: T1, execution: execution({ id: "waiting", status: "waiting", waitingSignal: "invoice.paid" }) });
+            await store.create({ tenantId: T1, execution: execution({ id: "other-signal", status: "waiting", waitingSignal: "shipped" }) });
+            // Running, not waiting: a signal must not resume something that never asked for it.
+            await store.create({ tenantId: T1, execution: execution({ id: "running", status: "running", waitingSignal: "invoice.paid" }) });
+            const found = await store.waitingOnSignal({ tenantId: T1, signal: "invoice.paid" });
+            expect(found.map((e) => e.id)).toEqual(["waiting"]);
+        });
+        it("finds the execution parked on a child run, and only while it is waiting", async () => {
+            // #202. A settled run has to find its parent, and a stale id on a *running* execution is not a parent
+            // waiting for anything — resuming it would advance a flow that is already advancing.
+            const store = make();
+            await store.create({
+                tenantId: T1,
+                execution: execution({ id: "parked", status: "waiting", waitingRunId: asId("child-1") }),
+            });
+            await store.create({
+                tenantId: T1,
+                execution: execution({ id: "running", status: "running", waitingRunId: asId("child-2") }),
+            });
+            expect((await store.waitingOnRun({ tenantId: T1, runId: asId("child-1") }))?.id).toBe("parked");
+            expect(await store.waitingOnRun({ tenantId: T1, runId: asId("child-2") })).toBeNull();
+            expect(await store.waitingOnRun({ tenantId: T1, runId: asId("nobody") })).toBeNull();
+        });
+        it("does not resolve another tenant's parked execution by child run", async () => {
+            const store = make();
+            await store.create({
+                tenantId: T1,
+                execution: execution({ status: "waiting", waitingRunId: asId("child-1") }),
+            });
+            expect(await store.waitingOnRun({ tenantId: T2, runId: asId("child-1") })).toBeNull();
+        });
+        it("lists a flow's executions, newest first", async () => {
+            const store = make();
+            await store.create({ tenantId: T1, execution: execution({ id: "old", startedAt: "2026-08-01T00:00:00.000Z" }) });
+            await store.create({ tenantId: T1, execution: execution({ id: "new", startedAt: "2026-08-20T00:00:00.000Z" }) });
+            await store.create({ tenantId: T1, execution: execution({ id: "elsewhere", flowId: "other" }) });
+            const listed = await store.listByFlow({ tenantId: T1, flowId: "onboard", limit: 50 });
+            expect(listed.items.map((e) => e.id)).toEqual(["new", "old"]);
+        });
+        it("keeps the whole execution document, so an inspector can read the state", async () => {
+            // #187 AC-7. A stored execution nobody can read the state of is not inspectable.
+            const store = make();
+            const state = { order: { id: "o1", total: 42 }, approved: true };
+            await store.create({ tenantId: T1, execution: execution({ execution: { state } }) });
+            const read = await store.get({ tenantId: T1, executionId: "exec-1" });
+            expect((read?.execution).state).toEqual(state);
+        });
+    });
+}
+//# sourceMappingURL=flows.js.map