@adonis-agora/durable 0.54.1 → 0.54.3

package/dist/src/testing-kit/state-store-conformance.js

@@ -567,6 +567,37 @@ export function runStateStoreContract(name, makeStore) {
             expect(await store.countCheckpoints('r1', 5, 9, ['pending'])).toBe(0);
             expect(await store.countCheckpoints('r1', 0, 4, [])).toBe(0);
         });
+        t('hasCheckpoints answers whether a seq range holds a status', async () => {
+            // Optional on the interface (the engine falls back to countCheckpoints), but a conformant store
+            // MUST provide it — assert presence, then exercise the fast path.
+            expect(store.hasCheckpoints).toBeDefined();
+            if (!store.hasCheckpoints)
+                return;
+            await store.createRun(run());
+            for (const [seq, status] of [
+                [0, 'completed'],
+                [1, 'pending'],
+                [2, 'completed'],
+                [3, 'failed'],
+                [4, 'completed'],
+            ]) {
+                await store.saveCheckpoint(checkpoint({ seq, status, stepId: `r1:${seq}` }));
+            }
+            await store.createRun(run({ id: 'other' }));
+            await store.saveCheckpoint(checkpoint({ runId: 'other', seq: 4, status: 'pending', stepId: 'other:4' }));
+            expect(await store.hasCheckpoints('r1', 0, 4, ['pending'])).toBe(true);
+            // Both bounds are inclusive.
+            expect(await store.hasCheckpoints('r1', 1, 1, ['pending'])).toBe(true);
+            expect(await store.hasCheckpoints('r1', 0, 1, ['pending'])).toBe(true);
+            expect(await store.hasCheckpoints('r1', 1, 2, ['pending'])).toBe(true);
+            expect(await store.hasCheckpoints('r1', 2, 4, ['pending'])).toBe(false);
+            expect(await store.hasCheckpoints('r1', 2, 4, ['pending', 'failed'])).toBe(true);
+            // `other` has a pending row at seq 4: the answer is scoped to its run.
+            expect(await store.hasCheckpoints('r1', 4, 4, ['pending'])).toBe(false);
+            expect(await store.hasCheckpoints('other', 0, 9, ['pending'])).toBe(true);
+            expect(await store.hasCheckpoints('r1', 5, 9, ['completed'])).toBe(false);
+            expect(await store.hasCheckpoints('r1', 0, 4, [])).toBe(false);
+        });
         t('saveCheckpointIfPending writes over a pending row only', async () => {
             // Optional on the interface (the engine falls back to a blind save, which can clobber a settled
             // row), but a conformant store MUST provide it — assert presence, then exercise it.
@@ -661,6 +692,195 @@ export function runStateStoreContract(name, makeStore) {
             ])).toEqual([true, true]);
             expect((await store.getCheckpoint('r1', 3))?.output).toEqual({ n: 3 });
         });
+        t('settleCheckpointsIfPending writes only the result columns, row by row (when implemented)', async () => {
+            if (!store.settleCheckpointsIfPending)
+                return;
+            expect(await store.settleCheckpointsIfPending([])).toEqual([]);
+            await store.createRun(run());
+            await store.createRun(run({ id: 'r2' }));
+            const pending = (runId, seq) => checkpoint({
+                runId,
+                seq,
+                stepId: `${runId}:${seq}`,
+                status: 'pending',
+                input: { prompt: `${runId}:${seq}` },
+                output: undefined,
+                attempts: 2,
+                workerGroup: 'g',
+                parallelGroup: 'fan:0:4',
+                wakeAt: 5_000,
+            });
+            for (const seq of [0, 1, 2, 3])
+                await store.saveCheckpoint(pending('r1', seq));
+            await store.saveCheckpoint(pending('r2', 0));
+            await store.saveCheckpoint({
+                ...pending('r1', 1),
+                status: 'completed',
+                output: { first: 1 },
+            });
+            const startedAt = new Date('2026-05-01T00:00:01.000Z');
+            const finishedAt = new Date('2026-05-01T00:00:02.000Z');
+            const done = (runId, seq, output) => ({
+                runId,
+                seq,
+                status: 'completed',
+                output,
+                events: [{ at: 1, level: 'info', message: `done ${seq}` }],
+                startedAt,
+                finishedAt,
+            });
+            const wrote = await store.settleCheckpointsIfPending([
+                done('r1', 0, { n: 0 }),
+                // Already settled: the result is refused.
+                done('r1', 1, { n: 1 }),
+                // A second copy of a row settled earlier in the call: refused.
+                done('r1', 0, { n: 'dup' }),
+                {
+                    runId: 'r1',
+                    seq: 2,
+                    status: 'failed',
+                    error: { message: 'boom' },
+                    startedAt,
+                    finishedAt,
+                },
+                // No such row: nothing is written.
+                done('r1', 9, { n: 9 }),
+                done('r2', 0, { n: 'r2' }),
+            ]);
+            expect(wrote).toEqual([true, false, false, true, false, true]);
+            const r1 = await store.listCheckpoints('r1');
+            expect(r1.map((c) => [c.seq, c.status, c.output])).toEqual([
+                [0, 'completed', { n: 0 }],
+                [1, 'completed', { first: 1 }],
+                [2, 'failed', undefined],
+                [3, 'pending', undefined],
+            ]);
+            const settled = r1[0];
+            expect(settled.events).toEqual([{ at: 1, level: 'info', message: 'done 0' }]);
+            expect(settled.startedAt.getTime()).toBe(startedAt.getTime());
+            expect(settled.finishedAt.getTime()).toBe(finishedAt.getTime());
+            // Every column the result does not carry is left as it was.
+            expect(settled.input).toEqual({ prompt: 'r1:0' });
+            expect(settled.attempts).toBe(2);
+            expect(settled.workerGroup).toBe('g');
+            expect(settled.parallelGroup).toBe('fan:0:4');
+            expect(settled.wakeAt).toBe(5_000);
+            expect(settled.stepId).toBe('r1:0');
+            expect(r1[2]?.error).toEqual({ message: 'boom' });
+            expect(r1[2]?.input).toEqual({ prompt: 'r1:2' });
+            expect(await store.getCheckpoint('r1', 9)).toBeNull();
+            expect((await store.getCheckpoint('r2', 0))?.output).toEqual({ n: 'r2' });
+            // One entry alone is the same compare-and-set.
+            expect(await store.settleCheckpointsIfPending([done('r1', 3, { n: 3 })])).toEqual([true]);
+            expect(await store.settleCheckpointsIfPending([done('r1', 3, { n: 'again' })])).toEqual([
+                false,
+            ]);
+            const third = await store.getCheckpoint('r1', 3);
+            expect(third?.output).toEqual({ n: 3 });
+            expect(third?.input).toEqual({ prompt: 'r1:3' });
+        });
+        t('settleCheckpointsIfPending settles a batch wider than one statement (when implemented)', async () => {
+            if (!store.settleCheckpointsIfPending)
+                return;
+            await store.createRun(run());
+            const rows = Array.from({ length: 600 }, (_, seq) => checkpoint({
+                seq,
+                stepId: `r1:${seq}`,
+                status: 'pending',
+                input: { seq },
+                output: undefined,
+            }));
+            if (store.saveCheckpoints)
+                await store.saveCheckpoints(rows);
+            else
+                for (const row of rows)
+                    await store.saveCheckpoint(row);
+            const at = new Date('2026-05-01T00:00:03.000Z');
+            const wrote = await store.settleCheckpointsIfPending(rows.map(({ seq }) => ({
+                runId: 'r1',
+                seq,
+                status: 'completed',
+                output: seq * 2,
+                startedAt: at,
+                finishedAt: at,
+            })));
+            expect(wrote.every((w) => w)).toBe(true);
+            const all = await store.listCheckpoints('r1');
+            expect(all.every((c, i) => c.status === 'completed' && c.output === i * 2)).toBe(true);
+            expect(all.every((c, i) => c.input.seq === i)).toBe(true);
+        }, 30_000);
+        t('getCheckpointsForSettle reads the rows without their input (when implemented)', async () => {
+            if (!store.getCheckpointsForSettle)
+                return;
+            expect(await store.getCheckpointsForSettle('r1', [])).toEqual([]);
+            await store.createRun(run());
+            for (const seq of [0, 1, 2]) {
+                await store.saveCheckpoint(checkpoint({
+                    seq,
+                    stepId: `r1:${seq}`,
+                    status: seq === 0 ? 'completed' : 'pending',
+                    input: { prompt: `p${seq}` },
+                    output: seq === 0 ? { a: 0 } : undefined,
+                    wakeAt: 5_000 + seq,
+                }));
+            }
+            const full = (await store.getCheckpoints?.('r1', [2, 0, 9])) ?? [
+                (await store.getCheckpoint('r1', 0)),
+                (await store.getCheckpoint('r1', 2)),
+            ];
+            const read = await store.getCheckpointsForSettle('r1', [2, 0, 9]);
+            expect(read.map((c) => [c.seq, c.input])).toEqual([
+                [0, undefined],
+                [2, undefined],
+            ]);
+            const withoutInput = ({ input: _input, ...rest }) => rest;
+            expect(read.map(withoutInput)).toEqual(full.map(withoutInput));
+            expect((await store.getCheckpoint('r1', 2))?.input).toEqual({ prompt: 'p2' });
+        });
+        t("listCheckpointsForReplay leaves out only a completed row's input (when implemented)", async () => {
+            if (!store.listCheckpointsForReplay)
+                return;
+            await store.createRun(run());
+            const input = (seq) => ({ prompt: `p${seq}` });
+            await store.saveCheckpoint(checkpoint({ seq: 0, stepId: 'r1:0', input: input(0), output: { a: 0 } }));
+            await store.saveCheckpoint(checkpoint({
+                seq: 1,
+                stepId: 'r1:1',
+                status: 'pending',
+                input: input(1),
+                output: undefined,
+            }));
+            await store.saveCheckpoint(checkpoint({
+                seq: 2,
+                stepId: 'r1:2',
+                status: 'failed',
+                input: input(2),
+                output: undefined,
+                error: { message: 'boom' },
+                wakeAt: 7_000,
+            }));
+            await store.saveCheckpoint(checkpoint({
+                seq: 3,
+                stepId: 'r1:3',
+                status: 'running',
+                input: input(3),
+                output: undefined,
+            }));
+            const full = await store.listCheckpoints('r1');
+            const replay = await store.listCheckpointsForReplay('r1');
+            expect(replay.map((c) => [c.seq, c.status, c.input])).toEqual([
+                [0, 'completed', undefined],
+                [1, 'pending', input(1)],
+                [2, 'failed', input(2)],
+                [3, 'running', input(3)],
+            ]);
+            // Every other field reads as listCheckpoints reads it.
+            const withoutInput = ({ input: _input, ...rest }) => rest;
+            expect(replay.map(withoutInput)).toEqual(full.map(withoutInput));
+            // The full read still carries every input.
+            expect(full.map((c) => c.input)).toEqual([input(0), input(1), input(2), input(3)]);
+            expect(await store.listCheckpointsForReplay('nope')).toEqual([]);
+        });
         t('saveCheckpoints writes many rows and getCheckpoints reads them back (when implemented)', async () => {
             if (!store.saveCheckpoints || !store.getCheckpoints)
                 return;