donobu 5.36.0 → 5.36.2

package/dist/managers/FederatedPagination.js

@@ -8,67 +8,150 @@ function createCompositePageToken(state) {
 }
 function parseCompositePageToken(token) {
     if (!token) {
-        return { sourceTokens: {}, exhaustedSources: [], cursorTimestamp: null };
+        return { sources: [] };
     }
     try {
-        return JSON.parse(Buffer.from(token, 'base64').toString());
+        const decoded = JSON.parse(Buffer.from(token, 'base64').toString());
+        if (decoded && Array.isArray(decoded.sources)) {
+            return decoded;
+        }
     }
     catch {
-        return { sourceTokens: {}, exhaustedSources: [], cursorTimestamp: null };
+        // fall through
     }
+    return { sources: [] };
 }
 /**
- * Federate a paginated listing across multiple persistence layers.
+ * Federate a paginated listing across multiple persistence layers
+ * (resume-by-id).
+ *
+ * Each layer holds an opaque cursor and an optional `resumeAfterId`. On
+ * each page request, federation fetches from each non-exhausted layer
+ * (advancing through batches as needed until it has at least `limit`
+ * candidates per layer), stable-sorts the merged contributions with the
+ * caller's `comparator`, and trims to `limit`. For each layer, the
+ * **last kept item in that layer's order** becomes the new
+ * `resumeAfterId`, with `cursor` set to the layer-token used to fetch
+ * that item's batch. Layers whose contribution is wholly dropped by the
+ * trim retain their pre-call state so their items remain reachable on
+ * later pages.
  *
- * Each layer is queried with up to 2× the requested limit, results are merged,
- * sorted by the provided comparator, and trimmed to the requested limit.
- * A composite page token tracks per-source pagination state.
+ * **Critical contract: the comparator must NOT tiebreak by id.** Ties
+ * on the sort key must return 0 from `comparator`. `Array.sort` is
+ * stable since ES2019, and federation feeds the merge in
+ * `[layer0..., layer1..., ...]` insertion order, so ties resolve by
+ * `(layerIndex, layer-internal position)` — exactly the property that
+ * keeps each layer's kept items as a *prefix* of its own order, which
+ * is what makes a single `resumeAfterId` representable. An id
+ * tiebreaker would silently break this and lose items.
  *
- * @param layers    The persistence layers to query.
- * @param query     The query object (must have `limit`, `pageToken`).
- * @param fetcher   Function that queries a single layer.
- * @param comparator Sort comparator for merging results across layers.
+ * **Layer contract.** Layers must return the same items in the same
+ * order for the same `(query, pageToken)` pair across calls. Their
+ * internal ordering does not need to match federation's tiebreaker —
+ * just be deterministic.
  */
 async function federatedList(layers, query, comparator) {
-    const paginationState = parseCompositePageToken(query.pageToken);
     const requestedLimit = Math.min(Math.max(1, query.limit ?? 100), 100);
-    const combinedResults = [];
-    let layersThatReturnedResults = 0;
+    const incomingState = parseCompositePageToken(query.pageToken);
+    const initialFor = (i) => {
+        const s = incomingState.sources[i];
+        return s ? { ...s } : { exhausted: false };
+    };
+    const work = [];
     for (let i = 0; i < layers.length; i++) {
-        if (paginationState.exhaustedSources.includes(i)) {
+        const init = initialFor(i);
+        const w = { contribution: [], layerExhausted: false };
+        work.push(w);
+        if (init.exhausted) {
+            w.layerExhausted = true;
             continue;
         }
-        const sourceLimit = Math.min(requestedLimit * 2, 100);
-        const sourceQuery = {
-            ...query,
-            limit: sourceLimit,
-            pageToken: paginationState.sourceTokens[i],
-        };
-        const sourceResult = await layers[i].getItems(sourceQuery);
-        if (sourceResult.items.length > 0) {
-            layersThatReturnedResults++;
+        let cursor = init.cursor;
+        let resume = init.resumeAfterId;
+        while (w.contribution.length < requestedLimit) {
+            const layerQuery = {
+                ...query,
+                limit: requestedLimit,
+                pageToken: cursor,
+            };
+            const batch = await layers[i].getItems(layerQuery);
+            let items = batch.items;
+            if (resume !== undefined) {
+                const idx = items.findIndex((it) => it.id === resume);
+                if (idx >= 0) {
+                    items = items.slice(idx + 1);
+                }
+                // The skip is one-shot: clear `resume` regardless of whether we
+                // found it. If found, we've passed it; if not, it was in a
+                // previously-fetched batch and won't reappear in subsequent
+                // batches we fetch in this loop.
+                resume = undefined;
+            }
+            for (const it of items) {
+                w.contribution.push({
+                    item: it,
+                    layerIndex: i,
+                    fetchCursor: cursor,
+                });
+            }
+            if (!batch.nextPageToken) {
+                w.layerExhausted = true;
+                break;
+            }
+            cursor = batch.nextPageToken;
         }
-        combinedResults.push(...sourceResult.items);
-        if (sourceResult.nextPageToken) {
-            paginationState.sourceTokens[i] = sourceResult.nextPageToken;
+    }
+    // Stable sort: ties resolve by insertion order = (layerIndex, layer
+    // position). Do NOT add an id tiebreaker (see header comment).
+    const merged = [];
+    for (const w of work) {
+        merged.push(...w.contribution);
+    }
+    merged.sort((a, b) => comparator(a.item, b.item));
+    const page = merged.slice(0, requestedLimit);
+    const newSources = [];
+    for (let i = 0; i < layers.length; i++) {
+        const init = initialFor(i);
+        if (init.exhausted) {
+            newSources.push({ exhausted: true });
+            continue;
+        }
+        const keptFromLayer = page.filter((w) => w.layerIndex === i);
+        if (keptFromLayer.length === 0) {
+            if (work[i].contribution.length === 0 && work[i].layerExhausted) {
+                // Layer truly has nothing — empty stream. Mark exhausted so
+                // we don't re-query it forever.
+                newSources.push({ exhausted: true });
+            }
+            else {
+                // Layer's items were all outranked by other layers. Roll back
+                // to the incoming state so they remain reachable on later
+                // pages, when the outranking layers have moved on.
+                newSources.push(init);
+            }
+            continue;
+        }
+        const lastKept = keptFromLayer[keptFromLayer.length - 1];
+        const allFromLayer = work[i].contribution;
+        const allKept = allFromLayer.length === keptFromLayer.length;
+        if (work[i].layerExhausted && allKept) {
+            newSources.push({ exhausted: true });
         }
         else {
-            paginationState.exhaustedSources.push(i);
+            newSources.push({
+                cursor: lastKept.fetchCursor,
+                resumeAfterId: lastKept.item.id,
+                exhausted: false,
+            });
         }
     }
-    // Only re-sort when results came from multiple layers; a single layer's
-    // results are already in the order it returned them, and re-sorting can
-    // disturb fields the comparator can't fully account for.
-    if (layersThatReturnedResults > 1) {
-        combinedResults.sort(comparator);
-    }
-    const limitedResults = combinedResults.slice(0, requestedLimit);
-    const hasMore = combinedResults.length > requestedLimit ||
-        paginationState.exhaustedSources.length < layers.length;
+    const someUnconsumed = merged.length > requestedLimit;
+    const someNotExhausted = newSources.some((s) => !s.exhausted);
+    const hasMore = someUnconsumed || someNotExhausted;
     return {
-        items: limitedResults,
+        items: page.map((w) => w.item),
         nextPageToken: hasMore
-            ? createCompositePageToken(paginationState)
+            ? createCompositePageToken({ sources: newSources })
             : undefined,
     };
 }

package/dist/managers/SuitesManager.js

@@ -108,16 +108,21 @@ class SuitesManager {
      * behavior for non-DB persistence layers (Volatile, S3, GCS).
      */
     async deleteSuite(suiteId) {
-        const suiteLayers = await this.suitesPersistenceRegistry.getAll();
-        const testLayers = await this.testsPersistenceRegistry.getAll();
-        for (let i = 0; i < suiteLayers.length; i++) {
+        for (const { key, persistence, } of await this.suitesPersistenceRegistry.getEntries()) {
             try {
-                await suiteLayers[i].deleteSuite(suiteId);
+                await persistence.deleteSuite(suiteId);
                 // Orphan tests in this layer after successfully deleting the suite.
                 // This mirrors the DB-level ON DELETE SET NULL for non-DB layers.
-                const testsResult = await testLayers[i].getTests({ suiteId });
+                // Pair by key — the suites and tests registries can have different
+                // sets of layers (e.g. plugin-only suites persistence) so positional
+                // indexing isn't safe.
+                const testsPersistence = await this.testsPersistenceRegistry.getByKey(key);
+                if (!testsPersistence) {
+                    continue;
+                }
+                const testsResult = await testsPersistence.getTests({ suiteId });
                 for (const test of testsResult.items) {
-                    await testLayers[i].updateTest({ ...test, suiteId: null });
+                    await testsPersistence.updateTest({ ...test, suiteId: null });
                 }
             }
             catch {

package/dist/managers/TestsManager.d.ts

@@ -2,14 +2,30 @@ import type { CreateDonobuFlow } from '../models/CreateDonobuFlow';
 import type { CreateTest } from '../models/CreateTest';
 import type { PaginatedResult } from '../models/PaginatedResult';
 import type { TestListItem, TestMetadata, TestsQuery } from '../models/TestMetadata';
+import type { SuitesPersistenceRegistry } from '../persistence/suites/SuitesPersistenceRegistry';
 import type { TestsPersistenceRegistry } from '../persistence/tests/TestsPersistenceRegistry';
 import type { DonobuFlowsManager } from './DonobuFlowsManager';
 export declare class TestsManager {
     private readonly testsPersistenceRegistry;
+    private readonly suitesPersistenceRegistry;
     private readonly flowsManager;
-    constructor(testsPersistenceRegistry: TestsPersistenceRegistry, flowsManager: DonobuFlowsManager);
+    constructor(testsPersistenceRegistry: TestsPersistenceRegistry, suitesPersistenceRegistry: SuitesPersistenceRegistry, flowsManager: DonobuFlowsManager);
     createTest(params: CreateTest): Promise<TestMetadata>;
     getTestById(testId: string): Promise<TestMetadata>;
+    /**
+     * Picks the tests persistence layer to use when creating a new test.
+     *
+     * - If `suiteId` is null/undefined: use the primary tests layer.
+     * - If `suiteId` is set: look up the suite's layer key and use the matching
+     *   tests layer. If no tests layer matches the suite's key (rare — would
+     *   require asymmetric registry config), fall back to the primary tests
+     *   layer; the FK won't hold but at least the test is persisted somewhere.
+     * - If `suiteId` is set but the suite doesn't exist anywhere: fall back
+     *   to the primary tests layer (the SQLite FK will reject if applicable;
+     *   non-DB layers will accept the dangling reference).
+     */
+    private resolveLayerForTestCreate;
+    private findSuiteLayerKey;
     getTests(query: TestsQuery): Promise<PaginatedResult<TestListItem>>;
     /**
      * Update a test in the persistence layer where it exists.
@@ -38,7 +54,9 @@ export declare class TestsManager {
     private getTestToolCalls;
     /**
      * Creates a new flow (config) for the given test, which should be passed to
-     * `flowsManager.createFlow` to execute the test.
+     * `flowsManager.createFlow` to execute the test. The returned config's
+     * `testId` is set, which `createFlow` uses to route the flow to the same
+     * persistence layer as the test.
      *
      * @param testId - The ID of the test to create a new flow for
      *

package/dist/managers/TestsManager.js

@@ -3,13 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TestsManager = void 0;
 const crypto_1 = require("crypto");
 const CannotDeleteRunningFlowException_1 = require("../exceptions/CannotDeleteRunningFlowException");
+const SuiteNotFoundException_1 = require("../exceptions/SuiteNotFoundException");
 const TestNotFoundException_1 = require("../exceptions/TestNotFoundException");
 const buildProvenance_1 = require("../utils/buildProvenance");
 const displayName_1 = require("../utils/displayName");
 const FederatedPagination_1 = require("./FederatedPagination");
 class TestsManager {
-    constructor(testsPersistenceRegistry, flowsManager) {
+    constructor(testsPersistenceRegistry, suitesPersistenceRegistry, flowsManager) {
         this.testsPersistenceRegistry = testsPersistenceRegistry;
+        this.suitesPersistenceRegistry = suitesPersistenceRegistry;
         this.flowsManager = flowsManager;
     }
     async createTest(params) {
@@ -38,9 +40,12 @@ class TestsManager {
             videoDisabled: params.videoDisabled,
             provenance: (0, buildProvenance_1.buildProvenance)('DONOBU_STUDIO'),
         };
-        // Create in the primary persistence layer only.
-        const primary = await this.testsPersistenceRegistry.get();
-        await primary.createTest(testMetadata);
+        // If the test is part of a suite, write it to the same persistence layer
+        // as the suite — otherwise the suite_id foreign key fails (in SQLite)
+        // or leaves a dangling reference (in non-DB layers). When standalone,
+        // fall back to the primary layer.
+        const persistence = await this.resolveLayerForTestCreate(testMetadata.suiteId);
+        await persistence.createTest(testMetadata);
         return testMetadata;
     }
     async getTestById(testId) {
@@ -56,6 +61,49 @@ class TestsManager {
         }
         throw TestNotFoundException_1.TestNotFoundException.forId(testId);
     }
+    /**
+     * Picks the tests persistence layer to use when creating a new test.
+     *
+     * - If `suiteId` is null/undefined: use the primary tests layer.
+     * - If `suiteId` is set: look up the suite's layer key and use the matching
+     *   tests layer. If no tests layer matches the suite's key (rare — would
+     *   require asymmetric registry config), fall back to the primary tests
+     *   layer; the FK won't hold but at least the test is persisted somewhere.
+     * - If `suiteId` is set but the suite doesn't exist anywhere: fall back
+     *   to the primary tests layer (the SQLite FK will reject if applicable;
+     *   non-DB layers will accept the dangling reference).
+     */
+    async resolveLayerForTestCreate(suiteId) {
+        if (!suiteId) {
+            return this.testsPersistenceRegistry.get();
+        }
+        let suiteLayerKey;
+        try {
+            suiteLayerKey = await this.findSuiteLayerKey(suiteId);
+        }
+        catch (error) {
+            if (!(error instanceof SuiteNotFoundException_1.SuiteNotFoundException)) {
+                throw error;
+            }
+            return this.testsPersistenceRegistry.get();
+        }
+        const matched = await this.testsPersistenceRegistry.getByKey(suiteLayerKey);
+        return matched ?? (await this.testsPersistenceRegistry.get());
+    }
+    async findSuiteLayerKey(suiteId) {
+        for (const { key, persistence, } of await this.suitesPersistenceRegistry.getEntries()) {
+            try {
+                await persistence.getSuiteById(suiteId);
+                return key;
+            }
+            catch (error) {
+                if (!(error instanceof SuiteNotFoundException_1.SuiteNotFoundException)) {
+                    throw error;
+                }
+            }
+        }
+        throw SuiteNotFoundException_1.SuiteNotFoundException.forId(suiteId);
+    }
     async getTests(query) {
         const layers = (await this.testsPersistenceRegistry.getAll()).map((persistence) => ({
             getItems: (q) => persistence.getTests(q),
@@ -65,13 +113,6 @@ class TestsManager {
         // TestMetadata has no `created_at` field — fall back to "now" so newly
         // returned items sort to the most-recent end. For other sort columns,
         // map the snake_case API name to the camelCase JS field.
-        //
-        // `flow_count` and `latest_flow_created_at` are only known at the
-        // persistence layer (SQLite computes them via JOIN; the cloud handles
-        // them server-side). Returning 0 here means each layer's pre-sorted
-        // results stay in their own order during the federated merge, but
-        // ordering across layers degrades to "first seen wins" — fine for the
-        // common single-primary-layer case.
         const fieldFor = (test) => {
             switch (sortBy) {
                 case 'created_at':
@@ -83,8 +124,9 @@ class TestsManager {
                 case 'next_run_mode':
                     return test.nextRunMode;
                 case 'flow_count':
+                    return test.flowCount ?? 0;
                 case 'latest_flow_created_at':
-                    return 0;
+                    return test.latestFlow?.startedAt ?? Date.now();
                 default:
                     return '';
             }
@@ -196,7 +238,9 @@ class TestsManager {
     }
     /**
      * Creates a new flow (config) for the given test, which should be passed to
-     * `flowsManager.createFlow` to execute the test.
+     * `flowsManager.createFlow` to execute the test. The returned config's
+     * `testId` is set, which `createFlow` uses to route the flow to the same
+     * persistence layer as the test.
      *
      * @param testId - The ID of the test to create a new flow for
      *
@@ -210,7 +254,16 @@ class TestsManager {
             try {
                 toolCallsOnStart = await this.getTestToolCalls(test);
             }
-            catch {
+            catch (error) {
+                // Fallback to AUTONOMOUS is only viable when the test has an
+                // overallObjective for the agent to work toward. For tests without
+                // one (e.g. Playwright-imported tests, or AI tests where the user
+                // cleared the objective), AUTONOMOUS would just fail downstream
+                // with a misleading "overallObjective is required" — propagate the
+                // original error instead so the user sees the real cause.
+                if ((test.overallObjective?.trim().length ?? 0) === 0) {
+                    throw error;
+                }
                 runMode = 'AUTONOMOUS';
             }
         }

package/dist/persistence/flows/FlowsPersistenceDonobuApi.js

@@ -125,7 +125,16 @@ class FlowsPersistenceDonobuApi {
             params.set('orphaned', query.orphaned ? 'true' : 'false');
         }
         if (query.sortBy) {
-            params.set('sort_by', query.sortBy);
+            switch (query.sortBy) {
+                case 'created_at':
+                    // `donobu-api` only supports `started_at`, but that's essentially
+                    // equivalent to `created_at`
+                    params.set('sort_by', 'started_at');
+                    break;
+                default:
+                    params.set('sort_by', query.sortBy);
+                    break;
+            }
         }
         if (query.sortOrder) {
             params.set('sort_order', query.sortOrder);

package/dist/persistence/flows/FlowsPersistenceRegistry.d.ts

@@ -2,6 +2,17 @@ import type { EnvPick } from 'env-struct';
 import type { env } from '../../envVars';
 import { PersistencePluginRegistry } from '../PersistencePlugin';
 import type { FlowsPersistence } from './FlowsPersistence';
+/**
+ * A persistence layer paired with the `PERSISTENCE_PRIORITY` key it was
+ * created from. The key is shared across the flows/tests/suites registries:
+ * the same key in each registry refers to the same logical store, which is
+ * how cross-entity foreign keys are kept aligned (e.g. a flow's `testId`
+ * resolves to a test that lives in the same layer).
+ */
+export interface FlowsPersistenceLayer {
+    key: string;
+    persistence: FlowsPersistence;
+}
 export interface FlowsPersistenceRegistry {
     /**
      * Returns the primary persistence layer.
@@ -9,6 +20,17 @@ export interface FlowsPersistenceRegistry {
     get(): Promise<FlowsPersistence>;
     /** Returns a list of all valid persistence layers. Guaranteed to be non-empty. */
     getAll(): Promise<FlowsPersistence[]>;
+    /**
+     * Returns all valid layers paired with their `PERSISTENCE_PRIORITY` key.
+     * Used by callers that need to align writes across registries (e.g. write
+     * a flow into the same layer as the test it references).
+     */
+    getEntries(): Promise<FlowsPersistenceLayer[]>;
+    /**
+     * Returns the persistence layer registered under the given
+     * `PERSISTENCE_PRIORITY` key, or undefined if no such layer exists.
+     */
+    getByKey(key: string): Promise<FlowsPersistence | undefined>;
 }
 /**
  * A factory class for creating FlowsPersistence instances. Persistence layers are constructed
@@ -19,7 +41,7 @@ export declare class FlowsPersistenceRegistryImpl implements FlowsPersistenceReg
     /**
      * Creates an instance with pre-built persistence layers.
      */
-    constructor(layers: FlowsPersistence[]);
+    constructor(layers: FlowsPersistenceLayer[]);
     /**
      * Creates an instance by reading environment variables and eagerly constructing
      * all applicable persistence layers.
@@ -31,5 +53,7 @@ export declare class FlowsPersistenceRegistryImpl implements FlowsPersistenceReg
     get(): Promise<FlowsPersistence>;
     /** Returns all persistence layers. Guaranteed to be non-empty. */
     getAll(): Promise<FlowsPersistence[]>;
+    getEntries(): Promise<FlowsPersistenceLayer[]>;
+    getByKey(key: string): Promise<FlowsPersistence | undefined>;
 }
 //# sourceMappingURL=FlowsPersistenceRegistry.d.ts.map

package/dist/persistence/flows/FlowsPersistenceRegistry.js

@@ -32,21 +32,27 @@ class FlowsPersistenceRegistryImpl {
             switch (key) {
                 case 'DONOBU':
                     if (donobuApiKey && donobuApiBaseUrl) {
-                        layers.push(new FlowsPersistenceDonobuApi_1.FlowsPersistenceDonobuApi(donobuApiBaseUrl, donobuApiKey));
+                        layers.push({
+                            key,
+                            persistence: new FlowsPersistenceDonobuApi_1.FlowsPersistenceDonobuApi(donobuApiBaseUrl, donobuApiKey),
+                        });
                     }
                     break;
                 case 'LOCAL':
-                    layers.push(await FlowsPersistenceSqlite_1.FlowsPersistenceSqlite.create(await (0, DonobuSqliteDb_1.getDonobuSqliteDatabase)()));
+                    layers.push({
+                        key,
+                        persistence: await FlowsPersistenceSqlite_1.FlowsPersistenceSqlite.create(await (0, DonobuSqliteDb_1.getDonobuSqliteDatabase)()),
+                    });
                     break;
                 case 'RAM':
-                    layers.push(new FlowsPersistenceVolatile_1.FlowsPersistenceVolatile());
+                    layers.push({ key, persistence: new FlowsPersistenceVolatile_1.FlowsPersistenceVolatile() });
                     break;
                 default: {
                     const plugin = persistencePlugins.get(key);
                     if (plugin) {
                         const impl = await plugin.createFlowsPersistence();
                         if (impl) {
-                            layers.push(impl);
+                            layers.push({ key, persistence: impl });
                         }
                     }
                     break;
@@ -59,12 +65,18 @@ class FlowsPersistenceRegistryImpl {
      * Returns the primary persistence layer.
      */
     async get() {
-        return this.layers[0];
+        return this.layers[0].persistence;
     }
     /** Returns all persistence layers. Guaranteed to be non-empty. */
     async getAll() {
+        return this.layers.map((layer) => layer.persistence);
+    }
+    async getEntries() {
         return this.layers;
     }
+    async getByKey(key) {
+        return this.layers.find((layer) => layer.key === key)?.persistence;
+    }
 }
 exports.FlowsPersistenceRegistryImpl = FlowsPersistenceRegistryImpl;
 //# sourceMappingURL=FlowsPersistenceRegistry.js.map

package/dist/persistence/suites/SuitesPersistenceRegistry.d.ts

@@ -2,17 +2,34 @@ import type { EnvPick } from 'env-struct';
 import type { env } from '../../envVars';
 import { PersistencePluginRegistry } from '../PersistencePlugin';
 import type { SuitesPersistence } from './SuitesPersistence';
+/**
+ * A persistence layer paired with its `PERSISTENCE_PRIORITY` key. See
+ * {@link FlowsPersistenceLayer} for why keys must align across registries.
+ */
+export interface SuitesPersistenceLayer {
+    key: string;
+    persistence: SuitesPersistence;
+}
 export interface SuitesPersistenceRegistry {
     /** Returns the primary persistence layer. */
     get(): Promise<SuitesPersistence>;
     /** Returns all valid persistence layers. Guaranteed to be non-empty. */
     getAll(): Promise<SuitesPersistence[]>;
+    /** Returns all valid layers paired with their `PERSISTENCE_PRIORITY` key. */
+    getEntries(): Promise<SuitesPersistenceLayer[]>;
+    /**
+     * Returns the persistence layer registered under the given
+     * `PERSISTENCE_PRIORITY` key, or undefined if no such layer exists.
+     */
+    getByKey(key: string): Promise<SuitesPersistence | undefined>;
 }
 export declare class SuitesPersistenceRegistryImpl implements SuitesPersistenceRegistry {
     private readonly layers;
-    constructor(layers: SuitesPersistence[]);
+    constructor(layers: SuitesPersistenceLayer[]);
     static fromEnvironment(environ: EnvPick<typeof env, 'DONOBU_API_BASE_URL' | 'DONOBU_API_KEY' | 'PERSISTENCE_PRIORITY'>, persistencePlugins?: PersistencePluginRegistry): Promise<SuitesPersistenceRegistryImpl>;
     get(): Promise<SuitesPersistence>;
     getAll(): Promise<SuitesPersistence[]>;
+    getEntries(): Promise<SuitesPersistenceLayer[]>;
+    getByKey(key: string): Promise<SuitesPersistence | undefined>;
 }
 //# sourceMappingURL=SuitesPersistenceRegistry.d.ts.map

package/dist/persistence/suites/SuitesPersistenceRegistry.js

@@ -21,21 +21,27 @@ class SuitesPersistenceRegistryImpl {
             switch (key) {
                 case 'DONOBU':
                     if (donobuApiKey && donobuApiBaseUrl) {
-                        layers.push(new SuitesPersistenceDonobuApi_1.SuitesPersistenceDonobuApi(donobuApiBaseUrl, donobuApiKey));
+                        layers.push({
+                            key,
+                            persistence: new SuitesPersistenceDonobuApi_1.SuitesPersistenceDonobuApi(donobuApiBaseUrl, donobuApiKey),
+                        });
                     }
                     break;
                 case 'LOCAL':
-                    layers.push(await SuitesPersistenceSqlite_1.SuitesPersistenceSqlite.create(await (0, DonobuSqliteDb_1.getDonobuSqliteDatabase)()));
+                    layers.push({
+                        key,
+                        persistence: await SuitesPersistenceSqlite_1.SuitesPersistenceSqlite.create(await (0, DonobuSqliteDb_1.getDonobuSqliteDatabase)()),
+                    });
                     break;
                 case 'RAM':
-                    layers.push(new SuitesPersistenceVolatile_1.SuitesPersistenceVolatile());
+                    layers.push({ key, persistence: new SuitesPersistenceVolatile_1.SuitesPersistenceVolatile() });
                     break;
                 default: {
                     const plugin = persistencePlugins.get(key);
                     if (plugin?.createSuitesPersistence) {
                         const impl = await plugin.createSuitesPersistence();
                         if (impl) {
-                            layers.push(impl);
+                            layers.push({ key, persistence: impl });
                         }
                     }
                     break;
@@ -45,11 +51,17 @@ class SuitesPersistenceRegistryImpl {
         return new SuitesPersistenceRegistryImpl(layers);
     }
     async get() {
-        return this.layers[0];
+        return this.layers[0].persistence;
     }
     async getAll() {
+        return this.layers.map((layer) => layer.persistence);
+    }
+    async getEntries() {
         return this.layers;
     }
+    async getByKey(key) {
+        return this.layers.find((layer) => layer.key === key)?.persistence;
+    }
 }
 exports.SuitesPersistenceRegistryImpl = SuitesPersistenceRegistryImpl;
 //# sourceMappingURL=SuitesPersistenceRegistry.js.map

package/dist/persistence/tests/TestsPersistenceRegistry.d.ts

@@ -3,15 +3,30 @@ import type { env } from '../../envVars';
 import type { FlowsPersistenceRegistry } from '../flows/FlowsPersistenceRegistry';
 import { PersistencePluginRegistry } from '../PersistencePlugin';
 import type { TestsPersistence } from './TestsPersistence';
+/**
+ * A persistence layer paired with its `PERSISTENCE_PRIORITY` key. See
+ * {@link FlowsPersistenceLayer} for why keys must align across registries.
+ */
+export interface TestsPersistenceLayer {
+    key: string;
+    persistence: TestsPersistence;
+}
 export interface TestsPersistenceRegistry {
     /** Returns the primary persistence layer. */
     get(): Promise<TestsPersistence>;
     /** Returns all valid persistence layers. Guaranteed to be non-empty. */
     getAll(): Promise<TestsPersistence[]>;
+    /** Returns all valid layers paired with their `PERSISTENCE_PRIORITY` key. */
+    getEntries(): Promise<TestsPersistenceLayer[]>;
+    /**
+     * Returns the persistence layer registered under the given
+     * `PERSISTENCE_PRIORITY` key, or undefined if no such layer exists.
+     */
+    getByKey(key: string): Promise<TestsPersistence | undefined>;
 }
 export declare class TestsPersistenceRegistryImpl implements TestsPersistenceRegistry {
     private readonly layers;
-    constructor(layers: TestsPersistence[]);
+    constructor(layers: TestsPersistenceLayer[]);
     static fromEnvironment(environ: EnvPick<typeof env, 'DONOBU_API_BASE_URL' | 'DONOBU_API_KEY' | 'PERSISTENCE_PRIORITY'>, 
     /**
      * Flows registry — used by the volatile tests layer to compute
@@ -22,5 +37,7 @@ export declare class TestsPersistenceRegistryImpl implements TestsPersistenceReg
     flowsRegistry?: FlowsPersistenceRegistry, persistencePlugins?: PersistencePluginRegistry): Promise<TestsPersistenceRegistryImpl>;
     get(): Promise<TestsPersistence>;
     getAll(): Promise<TestsPersistence[]>;
+    getEntries(): Promise<TestsPersistenceLayer[]>;
+    getByKey(key: string): Promise<TestsPersistence | undefined>;
 }
 //# sourceMappingURL=TestsPersistenceRegistry.d.ts.map