@namzu/sdk 20.0.0 → 20.2.0

package/dist/store/run/listing.js

@@ -0,0 +1,242 @@
+/**
+ * Shared machinery for {@link CheckpointStore.listDurableRuns}.
+ *
+ * Every rule the listing promises — the contiguous-prefix refusal, the park
+ * precedence, the ordering, the paging — lives here and is used by BOTH
+ * shipped implementations. A rule implemented twice is a rule that holds in
+ * one store and not the other, and the whole point of a store contract is
+ * that a host can swap the backend without swapping the semantics.
+ */
+import { NamzuError } from '../../types/errors/index.js';
+/** Page size when the caller names none. */
+export const DEFAULT_DURABLE_RUN_LIMIT = 100;
+/**
+ * Refuse a listing scope with a hole in it.
+ *
+ * `{ tenantId, sessionId }` reads as "that session under whichever project
+ * holds it". A flat backend can answer it; a hierarchical one cannot look up
+ * a session without its project. Answering differently per backend is the
+ * one thing the contract exists to prevent, so neither answers: the caller
+ * names the project it means.
+ */
+export function assertContiguousListingScope(scope, caller) {
+    if (scope.sessionId !== undefined && scope.projectId === undefined) {
+        throw new NamzuError({
+            code: 'invalid_config',
+            message: `${caller}: listing scope has a hole — \`sessionId\` was supplied without \`projectId\`. A run listing scope is a contiguous prefix of tenant → project → session; name the project the session belongs to.`,
+            details: { tenantId: scope.tenantId, sessionId: scope.sessionId },
+        });
+    }
+}
+/** Whether a park's absolute deadline has passed. No deadline never expires. */
+function isPastDeadline(pending, now) {
+    return pending.deadlineAt !== undefined && now >= pending.deadlineAt;
+}
+/**
+ * Which of the three states a recorded park is in.
+ *
+ * `resolved` is checked FIRST: a park that was answered after its deadline
+ * passed is answered, not expired. Reading the deadline first would report
+ * a decision a human actually made as an expiry nobody made, and the
+ * checkpoint is the evidence record for exactly that question.
+ */
+function parkStateOf(pending, now) {
+    if (pending.resolvedAt !== undefined)
+        return 'resolved';
+    return isPastDeadline(pending, now) ? 'expired' : 'outstanding';
+}
+function toParkSummary(cp, pending, now) {
+    return {
+        state: parkStateOf(pending, now),
+        checkpointId: cp.id,
+        requestType: pending.request.type,
+        parkedAt: pending.parkedAt,
+        ...(pending.deadlineAt !== undefined ? { deadlineAt: pending.deadlineAt } : {}),
+        ...(pending.resolvedAt !== undefined ? { resolvedAt: pending.resolvedAt } : {}),
+    };
+}
+/**
+ * The one park that describes what a run is doing now, out of every park it
+ * ever recorded.
+ *
+ * Precedence: newest `outstanding`, else newest `expired`, else newest
+ * `resolved`.
+ *
+ * `outstanding` wins because that is the question an inbox is asking, and
+ * because the answer has to be the SAME checkpoint `findPendingCheckpoint`
+ * returns. A run can hold several parks — it parks, a human answers, it runs
+ * on, it parks again — and it can hold an outstanding one that is older than
+ * a resolved one only in the reverse case, where an earlier park expired
+ * unanswered and the run was resumed past it. Ranking by recency alone would
+ * then hand an inbox a resolved checkpoint and report the live park as
+ * nothing.
+ *
+ * @param checkpoints the run's checkpoints, any order.
+ */
+export function summarizePark(checkpoints, now) {
+    let best;
+    let bestRank = -1;
+    let bestParkedAt = Number.NEGATIVE_INFINITY;
+    for (const cp of checkpoints) {
+        const pending = cp.pending;
+        if (!pending)
+            continue;
+        const summary = toParkSummary(cp, pending, now);
+        const rank = PARK_RANK[summary.state];
+        if (rank > bestRank || (rank === bestRank && pending.parkedAt > bestParkedAt)) {
+            best = summary;
+            bestRank = rank;
+            bestParkedAt = pending.parkedAt;
+        }
+    }
+    return best;
+}
+const PARK_RANK = {
+    resolved: 0,
+    expired: 1,
+    outstanding: 2,
+};
+/**
+ * Project one run's checkpoints into a listing entry.
+ *
+ * Returns `null` for a run with no checkpoints: the listing is of runs with
+ * DURABLE state, and a run with nothing stored has nothing a sweeper could
+ * resume. A disk walk hits this case for real — a sub-run's directory is
+ * created as a bare shell under its own id before anything is written to it.
+ */
+export function toDurableRunEntry(scope, checkpoints, now) {
+    if (checkpoints.length === 0)
+        return null;
+    let latest = checkpoints[0];
+    // The EARLIEST recorded stamp, not the one on any particular checkpoint.
+    // Every checkpoint of a run carries the same value, so under that
+    // invariant the minimum is that value. Taking the minimum rather than
+    // reading one checkpoint is what makes the read safe if the invariant is
+    // ever broken: it can only err toward the run's true attribution, never
+    // away from it, and it cannot move when a later checkpoint is added.
+    let runCreatedAt;
+    for (const cp of checkpoints) {
+        if (cp.createdAt > latest.createdAt)
+            latest = cp;
+        if (cp.runCreatedAt !== undefined &&
+            (runCreatedAt === undefined || cp.runCreatedAt < runCreatedAt)) {
+            runCreatedAt = cp.runCreatedAt;
+        }
+    }
+    const park = summarizePark(checkpoints, now);
+    return {
+        tenantId: scope.tenantId,
+        projectId: scope.projectId,
+        sessionId: scope.sessionId,
+        runId: scope.runId,
+        ...(scope.parentRunId ? { parentRunId: scope.parentRunId } : {}),
+        ...(runCreatedAt !== undefined ? { runCreatedAt } : {}),
+        checkpointCount: checkpoints.length,
+        latestCheckpointId: latest.id,
+        latestCheckpointAt: latest.createdAt,
+        ...(park ? { park } : {}),
+    };
+}
+/**
+ * Apply the park filter, the contract's ordering and the cursor to a set of
+ * entries an implementation has gathered.
+ *
+ * Both shipped stores gather differently — one walks a directory tree, one
+ * reads a map — and then hand the result here, so "ordered by `runId`, page
+ * ends where the next begins" is one implementation rather than two.
+ */
+export function paginateDurableRuns(entries, options) {
+    const wanted = options?.park;
+    const filtered = wanted && wanted.length > 0
+        ? entries.filter((e) => e.park !== undefined && wanted.includes(e.park.state))
+        : entries;
+    // Both orders sort on a key that cannot move under a paging caller — see
+    // the contract comment on `listDurableRuns`.
+    const orderBy = options?.orderBy ?? 'runId';
+    const ordered = [...filtered].sort((a, b) => compareKeys(sortKey(a, orderBy), sortKey(b, orderBy)));
+    const after = options?.cursor === undefined ? undefined : decodeCursor(options.cursor, orderBy);
+    const start = after === undefined ? 0 : ordered.findIndex((e) => compareKeys(sortKey(e, orderBy), after) > 0);
+    const from = start < 0 ? ordered.length : start;
+    const limit = Math.max(1, Math.trunc(options?.limit ?? DEFAULT_DURABLE_RUN_LIMIT));
+    const page = ordered.slice(from, from + limit);
+    const exhausted = from + page.length >= ordered.length;
+    return {
+        entries: page,
+        // No cursor when there is nothing behind it, so `while (cursor)`
+        // terminates rather than fetching one empty page to find out.
+        ...(exhausted || page.length === 0
+            ? {}
+            : { cursor: encodeCursor(sortKey(page[page.length - 1], orderBy)) }),
+    };
+}
+function sortKey(entry, orderBy) {
+    if (orderBy === 'runId')
+        return [0, 0, entry.runId];
+    return entry.runCreatedAt === undefined
+        ? [0, 0, entry.runId]
+        : [1, entry.runCreatedAt, entry.runId];
+}
+function compareKeys(a, b) {
+    if (a[0] !== b[0])
+        return a[0] - b[0];
+    if (a[1] !== b[1])
+        return a[1] - b[1];
+    return a[2] < b[2] ? -1 : a[2] > b[2] ? 1 : 0;
+}
+/**
+ * The cursor is the last row's key, and nothing else.
+ *
+ * Opaque to callers by contract — the shape is written down here rather than
+ * in the type so a host is not tempted to construct one. Run ids come from a
+ * 36-character lowercase alphabet with a `run_` prefix and contain no
+ * separator, so joining on `:` is unambiguous.
+ */
+function encodeCursor(key) {
+    return `${key[0]}:${key[1]}:${key[2]}`;
+}
+function decodeCursor(cursor, orderBy) {
+    const first = cursor.indexOf(':');
+    const second = cursor.indexOf(':', first + 1);
+    if (first < 0 || second < 0) {
+        throw new NamzuError({
+            code: 'invalid_config',
+            message: `listDurableRuns: "${cursor}" is not a cursor this listing issued. Pass back the \`cursor\` from the previous page rather than constructing one; its shape is not part of the contract.`,
+            details: { cursor, orderBy },
+        });
+    }
+    const rank = Number(cursor.slice(0, first));
+    const stamp = Number(cursor.slice(first + 1, second));
+    if (!Number.isFinite(rank) || !Number.isFinite(stamp)) {
+        throw new NamzuError({
+            code: 'invalid_config',
+            message: `listDurableRuns: cursor "${cursor}" is malformed — its position fields are not numbers. Pass back the \`cursor\` from the previous page.`,
+            details: { cursor, orderBy },
+        });
+    }
+    return [rank, stamp, cursor.slice(second + 1)];
+}
+/**
+ * Every run with durable state under a scope, refusing when the store cannot
+ * answer.
+ *
+ * The refusal is the point. `listDurableRuns` is optional on the contract so
+ * that adding it did not break every host that had already implemented the
+ * interface — and an optional capability reached without a check degrades
+ * into a wrong answer: a store that cannot list would hand an approval inbox
+ * an empty page, and "nothing is waiting on a human" is not what "I cannot
+ * tell" means. A host that gets this error knows to supply a backend that
+ * implements the listing; a host that got `[]` would ship an inbox that
+ * silently never fires.
+ */
+export async function listDurableRuns(store, scope, options) {
+    if (typeof store.listDurableRuns !== 'function') {
+        throw new NamzuError({
+            code: 'capability_unavailable',
+            message: 'listDurableRuns: the injected checkpoint store does not implement `listDurableRuns`, so it cannot enumerate runs above a run id. Refusing rather than reporting an empty listing, which would read as "no runs are parked" when the truth is that this store cannot tell. Supply a store that implements it (the built-in disk and in-memory stores both do).',
+            details: { tenantId: scope.tenantId },
+        });
+    }
+    assertContiguousListingScope(scope, 'listDurableRuns');
+    return store.listDurableRuns(scope, options);
+}
+//# sourceMappingURL=listing.js.map

package/dist/store/run/listing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listing.js","sourceRoot":"","sources":["../../../src/store/run/listing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAcxD,4CAA4C;AAC5C,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAG,CAAA;AAE5C;;;;;;;;GAQG;AACH,MAAM,UAAU,4BAA4B,CAAC,KAA6B,EAAE,MAAc;IACzF,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACpE,MAAM,IAAI,UAAU,CAAC;YACpB,IAAI,EAAE,gBAAgB;YACtB,OAAO,EAAE,GAAG,MAAM,mMAAmM;YACrN,OAAO,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE;SACjE,CAAC,CAAA;IACH,CAAC;AACF,CAAC;AAED,gFAAgF;AAChF,SAAS,cAAc,CAAC,OAAwB,EAAE,GAAW;IAC5D,OAAO,OAAO,CAAC,UAAU,KAAK,SAAS,IAAI,GAAG,IAAI,OAAO,CAAC,UAAU,CAAA;AACrE,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,WAAW,CAAC,OAAwB,EAAE,GAAW;IACzD,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS;QAAE,OAAO,UAAU,CAAA;IACvD,OAAO,cAAc,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,CAAA;AAChE,CAAC;AAED,SAAS,aAAa,CACrB,EAAuB,EACvB,OAAwB,EACxB,GAAW;IAEX,OAAO;QACN,KAAK,EAAE,WAAW,CAAC,OAAO,EAAE,GAAG,CAAC;QAChC,YAAY,EAAE,EAAE,CAAC,EAAE;QACnB,WAAW,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI;QACjC,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/E,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/E,CAAA;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,aAAa,CAC5B,WAA2C,EAC3C,GAAW;IAEX,IAAI,IAA6B,CAAA;IACjC,IAAI,QAAQ,GAAG,CAAC,CAAC,CAAA;IACjB,IAAI,YAAY,GAAG,MAAM,CAAC,iBAAiB,CAAA;IAE3C,KAAK,MAAM,EAAE,IAAI,WAAW,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,EAAE,CAAC,OAAO,CAAA;QAC1B,IAAI,CAAC,OAAO;YAAE,SAAQ;QACtB,MAAM,OAAO,GAAG,aAAa,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,CAAA;QAC/C,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;QACrC,IAAI,IAAI,GAAG,QAAQ,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,CAAC,QAAQ,GAAG,YAAY,CAAC,EAAE,CAAC;YAC/E,IAAI,GAAG,OAAO,CAAA;YACd,QAAQ,GAAG,IAAI,CAAA;YACf,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAA;QAChC,CAAC;IACF,CAAC;IAED,OAAO,IAAI,CAAA;AACZ,CAAC;AAED,MAAM,SAAS,GAA8B;IAC5C,QAAQ,EAAE,CAAC;IACX,OAAO,EAAE,CAAC;IACV,WAAW,EAAE,CAAC;CACd,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAChC,KAAyB,EACzB,WAA2C,EAC3C,GAAW;IAEX,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAEzC,IAAI,MAAM,GAAG,WAAW,CAAC,CAAC,CAAwB,CAAA;IAClD,yEAAyE;IACzE,kEAAkE;IAClE,sEAAsE;IACtE,yEAAyE;IACzE,wEAAwE;IACxE,qEAAqE;IACrE,IAAI,YAAgC,CAAA;IACpC,KAAK,MAAM,EAAE,IAAI,WAAW,EAAE,CAAC;QAC9B,IAAI,EAAE,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS;YAAE,MAAM,GAAG,EAAE,CAAA;QAChD,IACC,EAAE,CAAC,YAAY,KAAK,SAAS;YAC7B,CAAC,YAAY,KAAK,SAAS,IAAI,EAAE,CAAC,YAAY,GAAG,YAAY,CAAC,EAC7D,CAAC;YACF,YAAY,GAAG,EAAE,CAAC,YAAY,CAAA;QAC/B,CAAC;IACF,CAAC;IAED,MAAM,IAAI,GAAG,aAAa,CAAC,WAAW,EAAE,GAAG,CAAC,CAAA;IAE5C,OAAO;QACN,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,eAAe,EAAE,WAAW,CAAC,MAAM;QACnC,kBAAkB,EAAE,MAAM,CAAC,EAAE;QAC7B,kBAAkB,EAAE,MAAM,CAAC,SAAS;QACpC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACzB,CAAA;AACF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAClC,OAAmC,EACnC,OAAgC;IAEhC,MAAM,MAAM,GAAG,OAAO,EAAE,IAAI,CAAA;IAC5B,MAAM,QAAQ,GACb,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAC1B,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9E,CAAC,CAAC,OAAO,CAAA;IAEX,yEAAyE;IACzE,6CAA6C;IAC7C,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,OAAO,CAAA;IAC3C,MAAM,OAAO,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAC3C,WAAW,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CACrD,CAAA;IAED,MAAM,KAAK,GAAG,OAAO,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/F,MAAM,KAAK,GACV,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAA;IAChG,MAAM,IAAI,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAA;IAE/C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,IAAI,yBAAyB,CAAC,CAAC,CAAA;IAClF,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,GAAG,KAAK,CAAC,CAAA;IAC9C,MAAM,SAAS,GAAG,IAAI,GAAG,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAA;IAEtD,OAAO;QACN,OAAO,EAAE,IAAI;QACb,iEAAiE;QACjE,8DAA8D;QAC9D,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YACjC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAoB,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;KACxF,CAAA;AACF,CAAC;AAcD,SAAS,OAAO,CAAC,KAAsB,EAAE,OAAwB;IAChE,IAAI,OAAO,KAAK,OAAO;QAAE,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;IACnD,OAAO,KAAK,CAAC,YAAY,KAAK,SAAS;QACtC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC;QACrB,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;AACxC,CAAC;AAED,SAAS,WAAW,CAAC,CAAU,EAAE,CAAU;IAC1C,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;IACrC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;IACrC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAC9C,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,YAAY,CAAC,GAAY;IACjC,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;AACvC,CAAC;AAED,SAAS,YAAY,CAAC,MAAc,EAAE,OAAwB;IAC7D,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IACjC,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC,CAAA;IAC7C,IAAI,KAAK,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,UAAU,CAAC;YACpB,IAAI,EAAE,gBAAgB;YACtB,OAAO,EAAE,qBAAqB,MAAM,6JAA6J;YACjM,OAAO,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE;SAC5B,CAAC,CAAA;IACH,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAA;IAC3C,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAA;IACrD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,UAAU,CAAC;YACpB,IAAI,EAAE,gBAAgB;YACtB,OAAO,EAAE,4BAA4B,MAAM,wGAAwG;YACnJ,OAAO,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE;SAC5B,CAAC,CAAA;IACH,CAAC;IACD,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAA;AAC/C,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACpC,KAAsB,EACtB,KAA6B,EAC7B,OAAgC;IAEhC,IAAI,OAAO,KAAK,CAAC,eAAe,KAAK,UAAU,EAAE,CAAC;QACjD,MAAM,IAAI,UAAU,CAAC;YACpB,IAAI,EAAE,wBAAwB;YAC9B,OAAO,EACN,+VAA+V;YAChW,OAAO,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE;SACrC,CAAC,CAAA;IACH,CAAC;IACD,4BAA4B,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAA;IACtD,OAAO,KAAK,CAAC,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;AAC7C,CAAC"}

package/dist/types/hitl/index.d.ts

@@ -217,6 +217,33 @@ export interface IterationCheckpoint {
      * @deprecated No producer. Removed in the next major.
      */
     planStatus?: PlanStatus;
+    /**
+     * When the RUN was attributed — not when this checkpoint was written.
+     * See {@link IterationCheckpoint.createdAt} for the latter.
+     *
+     * Denormalized onto every checkpoint of the run, identically, and that
+     * repetition is the whole point. A listing above the run needs a key it
+     * can order by, and a key a paging caller can trust is one that cannot
+     * MOVE. Every other time a checkpoint store can derive per run moves: the
+     * newest checkpoint's `createdAt` advances every time the run checkpoints
+     * again, and the oldest one's advances every time `prune` deletes
+     * oldest-first. Carried on all of them, this one survives both — pruning
+     * cannot reach a value every survivor also holds.
+     *
+     * `readonly`, and written exactly once per run by
+     * {@link import('../../runtime/query/checkpoint.js').CheckpointManager},
+     * which settles it on whichever comes first — adopting it from the
+     * checkpoint a resume restores, or minting it from the run's own start
+     * instant — and never reassigns after. A field that COULD be updated is
+     * one edit away from moving again, which would put the ordering back
+     * where it started.
+     *
+     * Absent on checkpoints written before this existed. That absence is
+     * information, not a gap: a run with no stamp on any of its checkpoints
+     * was attributed before the stamp existed, and therefore before every
+     * run that has one.
+     */
+    readonly runCreatedAt?: number;
     /**
      * Present when the run parked at this checkpoint awaiting a human.
      * See {@link PendingDecision}.

package/dist/types/hitl/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/hitl/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/hitl/index.ts"],"names":[],"mappings":"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"}

package/dist/types/hitl/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/hitl/index.ts"],"names":[],"mappings":"AA4PA,MAAM,UAAU,kBAAkB,CAAC,OAA4B;IAC9D,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACtB,KAAK,eAAe;YACnB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAA;QACnD,KAAK,aAAa;YACjB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,CAAA;QACpD,KAAK,sBAAsB;YAC1B,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAA;QAC/C,KAAK,eAAe;YACnB,2DAA2D;YAC3D,yDAAyD;YACzD,6DAA6D;YAC7D,uCAAuC;YACvC,OAAO,OAAO,CAAC,OAAO,CAAC;gBACtB,MAAM,EAAE,iBAAiB;gBACzB,iBAAiB,EAAE,EAAE;gBACrB,QAAQ,EAAE,mEAAmE;gBAC7E,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,UAAU;aACvC,CAAC,CAAA;QACH,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,WAAW,GAAU,OAAO,CAAA;YAClC,MAAM,IAAI,KAAK,CAAC,gCAAiC,WAAmC,CAAC,IAAI,EAAE,CAAC,CAAA;QAC7F,CAAC;IACF,CAAC;AACF,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/hitl/index.ts"],"names":[],"mappings":"AAwRA,MAAM,UAAU,kBAAkB,CAAC,OAA4B;IAC9D,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACtB,KAAK,eAAe;YACnB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAA;QACnD,KAAK,aAAa;YACjB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,CAAA;QACpD,KAAK,sBAAsB;YAC1B,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAA;QAC/C,KAAK,eAAe;YACnB,2DAA2D;YAC3D,yDAAyD;YACzD,6DAA6D;YAC7D,uCAAuC;YACvC,OAAO,OAAO,CAAC,OAAO,CAAC;gBACtB,MAAM,EAAE,iBAAiB;gBACzB,iBAAiB,EAAE,EAAE;gBACrB,QAAQ,EAAE,mEAAmE;gBAC7E,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,UAAU;aACvC,CAAC,CAAA;QACH,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,WAAW,GAAU,OAAO,CAAA;YAClC,MAAM,IAAI,KAAK,CAAC,gCAAiC,WAAmC,CAAC,IAAI,EAAE,CAAC,CAAA;QAC7F,CAAC;IACF,CAAC;AACF,CAAC"}

package/dist/types/run/checkpoint-store.d.ts

@@ -8,7 +8,7 @@
  * {@link CheckpointRunScope} so a shared backend can key rows by the full
  * five-layer attribution (Convention #17) instead of a filesystem path.
  */
-import type { CheckpointId, IterationCheckpoint } from '../hitl/index.js';
+import type { CheckpointId, HITLDecisionRequest, IterationCheckpoint } from '../hitl/index.js';
 import type { RunId, SessionId, TenantId } from '../ids/index.js';
 import type { ProjectId } from '../session/ids.js';
 /**
@@ -36,6 +36,203 @@ export interface CheckpointRunScope {
      */
     parentRunId?: RunId;
 }
+/**
+ * A CONTIGUOUS PREFIX of the run attribution hierarchy, addressing a SET of
+ * runs rather than one.
+ *
+ * A separate type from {@link CheckpointRunScope} on purpose. That type
+ * addresses exactly one run and four accessors depend on it doing so; making
+ * its one distinguishing field optional in place would turn "the scope of a
+ * run" into "some identifiers, maybe", and every accessor's guarantee with
+ * it.
+ *
+ * Three properties, each deliberate:
+ *
+ *  - **`tenantId` is required.** Isolation is the one boundary that is never
+ *    optional here. An untenanted listing is a cross-tenant read with a
+ *    friendly name.
+ *  - **It stops ABOVE the run.** No `runId`, no `parentRunId`. A caller
+ *    holding a run id already has a full {@link CheckpointRunScope} and four
+ *    accessors that take it; admitting one here would make
+ *    `CheckpointRunScope` structurally assignable to this type and re-merge
+ *    the two ideas the split exists to keep apart.
+ *  - **The prefix must be contiguous.** A `sessionId` with no `projectId` is
+ *    REFUSED, not silently widened to "that session under whichever project
+ *    holds it". A flat backend can answer it and a hierarchical one cannot,
+ *    so the answer would depend on the backend's storage shape — which is
+ *    the one thing a store contract exists to hide.
+ */
+export interface CheckpointListingScope {
+    /** Isolation boundary (Convention #17). Never optional. */
+    readonly tenantId: TenantId;
+    /** Narrow to one project. Absent = every project of the tenant. */
+    readonly projectId?: ProjectId;
+    /** Narrow to one session. Requires `projectId`. */
+    readonly sessionId?: SessionId;
+}
+/**
+ * What a run's human-in-the-loop park is doing, as far as durable state can
+ * tell.
+ *
+ * A closed union rather than a boolean because the two unanswered states are
+ * drained by DIFFERENT operators: `outstanding` is an approval inbox's queue
+ * and `expired` is a reclamation sweep's, and serving one to the other either
+ * re-presents a dead approval forever or discards a live one.
+ */
+export type ParkState = 
+/** `pending` set, no `resolvedAt`, deadline not passed. A human owes an answer. */
+'outstanding'
+/** `pending` set, no `resolvedAt`, deadline passed. Nobody will answer it. */
+ | 'expired'
+/** `pending` set with `resolvedAt`. Kept as evidence of who decided what. */
+ | 'resolved';
+/**
+ * **Do not widen this union to say who is working on the run.**
+ *
+ * A consumer switches over `ParkState` exhaustively, so a fourth member is a
+ * backward-incompatible change and a `major` — and the pull to add one is
+ * real, because the next capability this contract takes is a cross-process
+ * claim, and a queue worker draining the inbox wants to skip runs another
+ * worker already holds.
+ *
+ * That is a different fact about a different subject. A park is a question
+ * put to a HUMAN; a claim is a lease held by a PROCESS, and one run can have
+ * both, neither, or either. Encoding them in one union makes the pair
+ * unsayable and loses the state a worker needs most: parked AND unclaimed.
+ *
+ * The additive shape is a sibling optional field — `claim?: …` on
+ * {@link DurableRunEntry}, `claimed?: …` on {@link ListDurableRunsOptions}.
+ * A consumer reading rows is not broken by a new optional field, so the
+ * claim ships as a second `minor` on this contract rather than a second
+ * migration of it. This note exists because the union is the obvious place
+ * to reach for and the wrong one.
+ */
+/** A run's park disposition, projected from the checkpoint that carries it. */
+export interface ParkSummary {
+    readonly state: ParkState;
+    /** The parked checkpoint — address it directly with `readCheckpoint`. */
+    readonly checkpointId: CheckpointId;
+    /** What the human was asked. Enough to route an inbox without a second read. */
+    readonly requestType: HITLDecisionRequest['type'];
+    /** Epoch ms at which the run parked. */
+    readonly parkedAt: number;
+    /** Absolute expiry, when the park carries one. */
+    readonly deadlineAt?: number;
+    /** Epoch ms at which the answer arrived. Only on `resolved`. */
+    readonly resolvedAt?: number;
+}
+/**
+ * One run that has durable checkpoint state under the queried scope.
+ *
+ * **Extends {@link CheckpointRunScope}, and that is the load-bearing part.**
+ * A listing whose rows cannot be turned back into an addressable scope is a
+ * report, not a work queue. Because an entry IS a run scope,
+ * `findPendingCheckpoint(store, entry)`, `new CheckpointManager(store, entry)`
+ * and `resumeRun({ scope: entry, … })` all accept a row straight out of the
+ * listing — with no re-assembly, and so no chance of assembling it wrong.
+ *
+ * ### What an entry deliberately does NOT carry
+ *
+ * A run STATUS. A checkpoint is written mid-flight, so nothing in this store
+ * distinguishes a run that finished from one that died — the same fact
+ * {@link import('../../runtime/query/run-state.js').loadRunState} already
+ * states, where a rebuilt snapshot always reports `running` and the host's
+ * own record stays the authority. A `status` field here would answer
+ * "mid-flight" for every run that ever succeeded, and a sweeper built on it
+ * would resume finished work.
+ *
+ * A crash sweep is therefore: list every run with durable state under the
+ * scope, intersect with the host's own run records, resume the difference.
+ */
+export interface DurableRunEntry extends CheckpointRunScope {
+    /**
+     * When the run was attributed. Absent when it was never recorded.
+     *
+     * The only per-run key this store holds that does not move, which is why
+     * it is the one an oldest-first listing can page over — see
+     * {@link CheckpointStore.listDurableRuns} and
+     * `IterationCheckpoint.runCreatedAt`.
+     *
+     * **Absent means "not recorded", and a caller should render it that way
+     * rather than as a date it invents.** Every run checkpointed by a build
+     * carrying the stamp has one; a run that has none was checkpointed
+     * before the stamp existed.
+     */
+    readonly runCreatedAt?: number;
+    /** How many checkpoints the run has right now. Pruning lowers it. */
+    readonly checkpointCount: number;
+    /** Newest checkpoint by `createdAt` — the one a resume restores by default. */
+    readonly latestCheckpointId: CheckpointId;
+    /** `createdAt` of {@link DurableRunEntry.latestCheckpointId}. */
+    readonly latestCheckpointAt: number;
+    /** Absent when the run has never parked. */
+    readonly park?: ParkSummary;
+}
+/**
+ * Which order a listing comes back in.
+ *
+ * Explicit rather than implied, because the two available orders answer
+ * different questions and neither is right for both. "Show me every run
+ * waiting on a human" wants stable paging; "show me the one that has been
+ * waiting longest" wants chronology. A listing that silently picked one
+ * would be the same ambiguity the scope type removed by splitting.
+ */
+export type DurableRunOrder = 
+/**
+ * By `runId` ascending. Stable and total, and meaningless as chronology —
+ * run ids carry no timestamp. The default, because it is what shipped.
+ */
+'runId'
+/**
+ * Oldest first, by {@link DurableRunEntry.runCreatedAt} then `runId`.
+ * This is the triage order: it answers which run has been waiting
+ * longest. Safe to page over, because the stamp is recorded once at
+ * attribution and never rewritten.
+ *
+ * **Runs whose creation was never recorded come FIRST**, ordered among
+ * themselves by `runId`. That is not a guess dressed up as a date: the
+ * stamp is written by the checkpoint manager, so a run lacking it on
+ * every checkpoint was checkpointed by a build that predates the stamp,
+ * and therefore predates every run that has one. Their
+ * `runCreatedAt` is absent on the row, so a caller can render "unknown"
+ * instead of a date nobody recorded.
+ */
+ | 'createdAt';
+/** Filters and paging for {@link CheckpointStore.listDurableRuns}. */
+export interface ListDurableRunsOptions {
+    /**
+     * Ordering, and therefore what the cursor is a position in. Defaults to
+     * `'runId'`. A cursor is only meaningful within one order — do not carry
+     * one across a change of `orderBy`.
+     */
+    readonly orderBy?: DurableRunOrder;
+    /**
+     * Keep only runs whose park is in one of these states. A run that never
+     * parked has no state and is excluded by ANY value here; omit the filter
+     * to include it.
+     */
+    readonly park?: readonly ParkState[];
+    /** Page size. Defaults to 100, clamped to at least 1. */
+    readonly limit?: number;
+    /** Resume token from the previous page's {@link DurableRunPage.cursor}. */
+    readonly cursor?: string;
+    /**
+     * Clock for expiry, so a sweep can be tested and so every entry in one
+     * page is judged against the same instant. Defaults to `Date.now()` — the
+     * same seam `findPendingCheckpoint` already takes.
+     */
+    readonly now?: number;
+}
+/** One page of {@link DurableRunEntry}. */
+export interface DurableRunPage {
+    readonly entries: readonly DurableRunEntry[];
+    /**
+     * Pass to the next call. **Absent means the listing is exhausted**, so
+     * `while (cursor)` terminates; a store never returns a cursor it already
+     * knows yields nothing.
+     */
+    readonly cursor?: string;
+}
 /**
  * Persistence contract consumed by
  * {@link import('../../runtime/query/checkpoint.js').CheckpointManager} and
@@ -46,6 +243,27 @@ export interface CheckpointRunScope {
  * not-found error. `deleteCheckpoint` is idempotent: deleting an absent
  * checkpoint succeeds as a no-op (mirrors the disk store's ENOENT
  * swallowing).
+ *
+ * ## Optional capabilities, and the rule that comes with them
+ *
+ * {@link CheckpointStore.listDurableRuns} is optional, following
+ * `SessionStore.listSessionsByProject`. A required method would break every
+ * host that has already implemented this interface, which is a `major` for
+ * what is otherwise an additive capability.
+ *
+ * The rule optionality obliges: **a caller of an optional capability REFUSES
+ * when it is absent; it never degrades.** An approval inbox built on a store
+ * that cannot list has to throw, because an empty page would say "nothing is
+ * waiting on a human" when the truth is "I cannot tell" — an optional
+ * dependency degrading a check, which this repository has been bitten by
+ * before. Reach the capability through
+ * {@link import('../../store/run/listing.js').listDurableRuns}, which
+ * refuses on absence rather than answering.
+ *
+ * Any capability added here later takes the same shape — optional method,
+ * refusing helper. A cross-process claim is the next one, and a two-worker
+ * deployment against a store with no lease has to fail loudly rather than
+ * proceed.
  */
 export interface CheckpointStore {
     /** Persist one checkpoint. Overwrites an existing checkpoint with the same id. */
@@ -60,5 +278,46 @@ export interface CheckpointStore {
     listCheckpoints(scope: CheckpointRunScope): Promise<IterationCheckpoint[]>;
     /** Delete a checkpoint by id. Absent checkpoints succeed as a no-op. */
     deleteCheckpoint(scope: CheckpointRunScope, checkpointId: CheckpointId): Promise<void>;
+    /**
+     * Every run with durable checkpoint state under a scope ABOVE the run.
+     * OPTIONAL — see the optional-capability rule on this interface.
+     *
+     * This is the read an approval inbox and a park sweep are built from, and
+     * the one thing this contract had no way to express: every other accessor
+     * needs a `runId`, so a host could only ask about runs it already knew
+     * about. `hitlParkTtlMs` documents a host sweep as the reclamation path
+     * for an unanswered park, and until this existed the sweep had no way to
+     * enumerate what to sweep.
+     *
+     * ### Ordering
+     *
+     * Two orders, named by `options.orderBy`, and the cursor is a position in
+     * whichever one was asked for. See {@link DurableRunOrder}.
+     *
+     * Both sort on a key that cannot MOVE, which is the property a cursor
+     * needs — sort on a moving key and a paging caller skips rows and repeats
+     * rows. That rules out every time a checkpoint store can derive on its
+     * own: the newest checkpoint's timestamp advances whenever the run
+     * checkpoints again, and the oldest one's advances whenever
+     * `CheckpointManager.prune` deletes oldest-first, which is what pruning
+     * does. It leaves `runId`, which is immutable and unique but carries no
+     * timestamp, and `runCreatedAt`, which is recorded once at attribution
+     * and denormalized onto every checkpoint so pruning cannot reach it.
+     *
+     * `'runId'` alone is already a total order. `'createdAt'` tiebreaks on
+     * `runId`, which is the rule `orderChildren` follows: sort on a key that
+     * cannot move, make the order total with an id.
+     *
+     * A run whose FIRST checkpoint is written after paging began may be
+     * missed by that pass, in either order — it lands wherever its key puts
+     * it, possibly behind the cursor. That is the right trade for a queue:
+     * the sweep runs again and picks it up next pass, whereas a moving sort
+     * key loses runs that already existed.
+     *
+     * @param scope contiguous prefix; `tenantId` required. Implementations
+     *   reject a hole (`sessionId` with no `projectId`) rather than guessing.
+     * @param options filters and paging. See {@link ListDurableRunsOptions}.
+     */
+    listDurableRuns?(scope: CheckpointListingScope, options?: ListDurableRunsOptions): Promise<DurableRunPage>;
 }
 //# sourceMappingURL=checkpoint-store.d.ts.map

package/dist/types/run/checkpoint-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkpoint-store.d.ts","sourceRoot":"","sources":["../../../src/types/run/checkpoint-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AACzE,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAElD;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IAClC,2CAA2C;IAC3C,QAAQ,EAAE,QAAQ,CAAA;IAClB,gDAAgD;IAChD,SAAS,EAAE,SAAS,CAAA;IACpB,wCAAwC;IACxC,SAAS,EAAE,SAAS,CAAA;IACpB,2CAA2C;IAC3C,KAAK,EAAE,KAAK,CAAA;IACZ;;;;OAIG;IACH,WAAW,CAAC,EAAE,KAAK,CAAA;CACnB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe;IAC/B,kFAAkF;IAClF,eAAe,CAAC,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE1F,6EAA6E;IAC7E,cAAc,CACb,KAAK,EAAE,kBAAkB,EACzB,YAAY,EAAE,YAAY,GACxB,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAA;IAEtC;;;;OAIG;IACH,eAAe,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAA;IAE1E,wEAAwE;IACxE,gBAAgB,CAAC,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACtF"}
+{"version":3,"file":"checkpoint-store.d.ts","sourceRoot":"","sources":["../../../src/types/run/checkpoint-store.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/sdk",
-  "version": "20.0.0",
+  "version": "20.2.0",
   "description": "Open-source AI agent SDK with a built-in runtime. Nothing between you and your agents.",
   "license": "FSL-1.1-MIT",
   "type": "module",

package/src/manager/run/persistence.ts

@@ -45,12 +45,26 @@ export class RunPersistence {
 
 		// Checkpoints go through the injectable seam; the disk layout under
 		// `outputDir` (same tree the runStore writes to) stays the default.
+		//
+		// The attribution is handed over because the layout does not record
+		// it — there is no tenant segment in the path at all — and without it
+		// the default store can persist checkpoints but cannot ENUMERATE
+		// them, which is the state the contract just stopped being in. A
+		// listing capability the default store declines is a capability no
+		// host reaches.
 		this.checkpointStore =
 			config.checkpointStore ??
-			new DiskCheckpointStore({
-				baseDir: config.outputDir,
-				logger: config.log,
-			})
+			new DiskCheckpointStore(
+				{
+					baseDir: config.outputDir,
+					logger: config.log,
+				},
+				{
+					tenantId: config.tenantId,
+					projectId: config.projectId,
+					sessionId: config.sessionId,
+				},
+			)
 
 		this.run = {
 			id: config.runId,