@cursor/bdk 0.2.1

package/dist/internal/artifacts-store.js

@@ -0,0 +1,737 @@
+/**
+ * Durable artifact rows and payloads behind `ctx.artifacts`
+ * ({@link ArtifactsApi}).
+ *
+ * On Cursor-managed hosting rows and file payloads live on the deployment's
+ * Agent Store (the same store behind `ctx.host.files`, so they survive
+ * deploys and are visible on cloud VMs under the store mount); otherwise
+ * they land under `--state-root/artifacts` on local disk.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveArtifactsMax } from "../artifacts.js";
+import { agentStoreKeys } from "../files.js";
+import { cursorHostedFiles, isCursorHostedFilesAvailable, } from "../files-backends/cursor-hosted.js";
+import { mapBounded } from "./bounded.js";
+/** Default {@link ArtifactPageOptions.limit}; also `GET /v1/artifacts`. */
+export const ARTIFACTS_PAGE_DEFAULT_LIMIT = 200;
+/** Ceiling for {@link ArtifactPageOptions.limit}; larger asks clamp. */
+export const ARTIFACTS_PAGE_MAX_LIMIT = 1000;
+/**
+ * Rows examined per `page()` call, floor. Filters live in row bodies, so a
+ * sparse filter must hydrate rows just to reject them; this stops one call
+ * from scanning an arbitrarily large store, returning a short (possibly
+ * empty) page with a `nextCursor` instead. `Math.max(limit, …)` keeps a
+ * full unfiltered page satisfiable in one call.
+ */
+const ARTIFACTS_PAGE_SCAN_MIN = 250;
+/**
+ * Row-body hydration fan-out cap. `list()` fetches one object per row; on
+ * the Agent Store each fetch is a control-plane request, and an unbounded
+ * `Promise.all` over ~1k rows is a fleet-visible read burst (the 2026-09-18
+ * Agent Store read storm was this exact fan-out, run once per insert by the
+ * pre-metadata eviction path).
+ */
+const ROW_HYDRATION_CONCURRENCY = 8;
+/**
+ * Rows hydrated per round trip when the row store batches
+ * ({@link ArtifactRowStore.getMany}). Matches the hosted sink's presign
+ * batch, so one page-scan slice is one control-plane request instead of one
+ * per row.
+ */
+const ARTIFACTS_SCAN_BATCH_ROWS = 100;
+/**
+ * Most rows one eviction pass may delete. Bounds the tag-latency cost of
+ * draining a store that sits far past the retention cap (see
+ * {@link ArtifactsStore.evictPastCap}): at ~0.7s per Agent Store delete and
+ * {@link ROW_HYDRATION_CONCURRENCY}-way batching, a full pass stays under
+ * ~10s while a backlog drains across the inserts that keep arriving.
+ */
+const ARTIFACTS_EVICT_MAX_PER_PASS = 64;
+/** Kind used by freeform tags when no kinds are declared. */
+export const ARTIFACT_DEFAULT_KIND = "artifact";
+/**
+ * Upsert + list semantics over one {@link ArtifactRowStore}: kind/schema
+ * validation, deterministic ids for keyed tags, and `max` eviction. The
+ * engine wraps this into the per-context {@link ArtifactsApi} facades and
+ * owns the `artifact.tagged` event append.
+ */
+export class ArtifactsStore {
+    constructor(options) {
+        var _a;
+        /** Serializes tags so read-modify-write upserts and eviction don't race. */
+        this.tagChain = Promise.resolve();
+        const sink = (_a = options.sink) !== null && _a !== void 0 ? _a : (isCursorHostedFilesAvailable() ? cursorHostedFiles() : undefined);
+        if (sink === undefined) {
+            this.rows = createFilesystemRowStore(options.stateRoot);
+            this.content = createFilesystemContentStore(options.stateRoot);
+        }
+        else {
+            this.rows = createSinkRowStore(sink, options.agentName);
+            this.content = createSinkContentStore(sink, options.agentName);
+        }
+        this.config = options.config;
+        this.max = resolveArtifactsMax(options.config);
+    }
+    tag(input) {
+        const result = this.tagChain.then(() => this.tagSerialized(input));
+        this.tagChain = result.catch(() => { });
+        return result;
+    }
+    tagSerialized(input) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const { kind, data } = this.resolveKindAndData(input);
+            const id = input.key === undefined ? `art_${randomUUID()}` : artifactIdForKey(input.key);
+            // Fresh random ids can't collide; only keyed tags upsert.
+            const existing = input.key === undefined ? undefined : yield this.rows.get(id);
+            const now = new Date().toISOString();
+            const record = {
+                id,
+                kind,
+                key: input.key,
+                title: input.title,
+                data,
+                sessionId: input.sessionId,
+                turnId: input.turnId,
+                source: (_a = input.source) !== null && _a !== void 0 ? _a : "host",
+                createdAt: (_b = existing === null || existing === void 0 ? void 0 : existing.createdAt) !== null && _b !== void 0 ? _b : now,
+                updatedAt: now,
+            };
+            if (input.contents !== undefined) {
+                const body = typeof input.contents === "string" ? Buffer.from(input.contents, "utf8") : input.contents;
+                yield this.content.put(id, body);
+                record.content = {
+                    size: body.byteLength,
+                    contentType: input.contentType,
+                };
+            }
+            else if ((existing === null || existing === void 0 ? void 0 : existing.content) !== undefined) {
+                if (existing.sessionId === record.sessionId) {
+                    record.content = existing.content;
+                }
+                else {
+                    // Keys are deployment-global: rebinding a keyed row to another
+                    // session must not carry the prior session's payload with it.
+                    yield this.content.delete(id);
+                }
+            }
+            yield this.rows.put(record);
+            if (existing === undefined) {
+                yield this.evictPastCap();
+            }
+            return record;
+        });
+    }
+    get(id) {
+        return this.rows.get(id);
+    }
+    /** Payload bytes for one artifact; undefined when it carries none. */
+    getContent(id) {
+        return this.content.get(id);
+    }
+    /**
+     * Newest page only (default limit, no cursor) — the bounded
+     * {@link ArtifactsApi.list} contract. Walk the full set via
+     * {@link ArtifactsStore.page}.
+     */
+    list(filter) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const page = yield this.page(filter);
+            return page.records;
+        });
+    }
+    /**
+     * Bounded cursor pagination, newest-updated first. On a store whose
+     * listing tracks mtimes (the hosted Agent Store), a page hydrates only
+     * the rows it examines — roughly `limit` bodies, never the whole store.
+     * Row-body order is the listing's mtime order (upserts rewrite the row,
+     * so mtime tracks `updatedAt`; same argument as eviction). The
+     * filesystem store hydrates everything (cheap local reads) and orders
+     * exactly by `updatedAt`.
+     *
+     * `matches` is a host-side *visibility* predicate composed with the
+     * public filter — the engine passes session-ownership through it. Its
+     * presence forces the exact hydrated lane: the metadata lane's cursor
+     * and its short-page continuation are derived from every row in the
+     * store, and handing them to a caller who may not see every row is a
+     * side channel (existence, count within the scan budget, boundary
+     * mtimes and cohort depths of hidden rows) that the pre-pagination
+     * filtered list never had. The exact lane's cursor names only a record
+     * the caller received, and continues only while more *visible* records
+     * remain — at the pre-pagination cost (hydrate all rows, bounded).
+     */
+    page(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const limit = Math.min(Math.max((_a = options === null || options === void 0 ? void 0 : options.limit) !== null && _a !== void 0 ? _a : ARTIFACTS_PAGE_DEFAULT_LIMIT, 1), ARTIFACTS_PAGE_MAX_LIMIT);
+            const cursor = (options === null || options === void 0 ? void 0 : options.cursor) === undefined ? undefined : decodeArtifactPageCursor(options.cursor);
+            const matches = (record) => ((options === null || options === void 0 ? void 0 : options.kind) === undefined || record.kind === options.kind) &&
+                ((options === null || options === void 0 ? void 0 : options.sessionId) === undefined || record.sessionId === options.sessionId) &&
+                ((options === null || options === void 0 ? void 0 : options.matches) === undefined || options.matches(record));
+            if ((options === null || options === void 0 ? void 0 : options.matches) === undefined) {
+                const metas = yield this.rows.listMeta();
+                if (metas.some(meta => meta.mtimeMs !== undefined)) {
+                    return this.pageFromMetadata(metas, limit, cursor, matches, (options === null || options === void 0 ? void 0 : options.kind) !== undefined || (options === null || options === void 0 ? void 0 : options.sessionId) !== undefined);
+                }
+            }
+            return this.pageFromRecords(limit, cursor, matches);
+        });
+    }
+    /**
+     * Metadata-ordered page: sort metas newest first, resume after the
+     * cursor, hydrate in bounded batches until the page fills, the scan
+     * budget runs out, or the metas do. The cursor marks the last *examined*
+     * meta, so a budget-limited call still makes progress.
+     */
+    pageFromMetadata(metas, limit, cursor, matches, filtered) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            var _c, _d, _e;
+            const newestFirst = metas.sort((a, b) => byOldestModified(b, a));
+            let start = 0;
+            if (cursor !== undefined && cursor.kind === "mtime") {
+                // Resume after (boundary stamp, rows of that cohort already
+                // examined). Same-stamp rows sit contiguously in the sort, so the
+                // pair names an exact position without identifying any row.
+                start = newestFirst.findIndex(meta => { var _a; return ((_a = meta.mtimeMs) !== null && _a !== void 0 ? _a : 0) <= cursor.m; });
+                if (start === -1) {
+                    return { records: [] };
+                }
+                let skipped = 0;
+                while (start < newestFirst.length &&
+                    ((_c = (_a = newestFirst[start]) === null || _a === void 0 ? void 0 : _a.mtimeMs) !== null && _c !== void 0 ? _c : 0) === cursor.m &&
+                    skipped < cursor.s) {
+                    start += 1;
+                    skipped += 1;
+                }
+                if (start >= newestFirst.length) {
+                    return { records: [] };
+                }
+            }
+            // A cursor of the other kind means the store's listing gained mtimes
+            // between pages (a mode flip, not caller error): restart from the top
+            // rather than fail the walk.
+            const budget = Math.max(limit, ARTIFACTS_PAGE_SCAN_MIN);
+            const records = [];
+            let examined = 0;
+            let lastExamined = start - 1;
+            // A batched row store hydrates a bigger slice per round trip (one
+            // control-plane call on the hosted sink); without one, keep the slice at
+            // the per-row fan-out bound so concurrency stays capped. An unfiltered
+            // page needs exactly the rows it returns — every hydrated row matches —
+            // so cap its slice at the remaining page instead of over-hydrating a
+            // full batch for a small `limit`.
+            const scanBatchSize = this.rows.getMany !== undefined ? ARTIFACTS_SCAN_BATCH_ROWS : ROW_HYDRATION_CONCURRENCY;
+            scan: while (lastExamined + 1 < newestFirst.length &&
+                records.length < limit &&
+                examined < budget) {
+                const from = lastExamined + 1;
+                const sliceCap = filtered ? scanBatchSize : Math.min(scanBatchSize, limit - records.length);
+                const batch = newestFirst.slice(from, from + Math.min(sliceCap, budget - examined));
+                const bodies = this.rows.getMany !== undefined
+                    ? yield this.rows.getMany(batch.map(meta => meta.id))
+                    : yield mapBounded(batch, ROW_HYDRATION_CONCURRENCY, meta => this.rows.get(meta.id));
+                for (let i = 0; i < batch.length; i += 1) {
+                    lastExamined = from + i;
+                    examined += 1;
+                    const record = bodies[i];
+                    if (record !== undefined && matches(record)) {
+                        records.push(record);
+                        if (records.length === limit) {
+                            break scan;
+                        }
+                    }
+                }
+            }
+            if (lastExamined >= newestFirst.length - 1) {
+                return { records };
+            }
+            const boundary = (_d = newestFirst[lastExamined].mtimeMs) !== null && _d !== void 0 ? _d : 0;
+            // How deep into the boundary's same-stamp cohort the scan got —
+            // cohorts are contiguous, so count back from the last examined row.
+            let cohortExamined = 0;
+            for (let i = lastExamined; i >= 0 && ((_e = (_b = newestFirst[i]) === null || _b === void 0 ? void 0 : _b.mtimeMs) !== null && _e !== void 0 ? _e : 0) === boundary; i -= 1) {
+                cohortExamined += 1;
+            }
+            return {
+                records,
+                nextCursor: encodeArtifactPageCursor({
+                    v: 1,
+                    kind: "mtime",
+                    m: boundary,
+                    s: cohortExamined,
+                }),
+            };
+        });
+    }
+    /**
+     * Hydrate-everything page: exact `updatedAt` order, cursor = the last
+     * *returned* record's position. Serves stores without listing mtimes
+     * (the local filesystem store) and every visibility-filtered walk — see
+     * {@link ArtifactsStore.page} for why filtered callers must not receive
+     * metadata-lane cursors.
+     */
+    pageFromRecords(limit, cursor, matches) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const records = (yield this.rows.list()).filter(matches).sort(byNewestUpdated);
+            let start = 0;
+            if (cursor !== undefined && cursor.kind === "updated") {
+                const position = {
+                    updatedAt: cursor.u,
+                    createdAt: cursor.c,
+                    id: cursor.id,
+                };
+                start = records.findIndex(record => byNewestUpdated(record, position) > 0);
+                if (start === -1) {
+                    return { records: [] };
+                }
+            }
+            const page = records.slice(start, start + limit);
+            const last = page[page.length - 1];
+            if (last === undefined || start + page.length >= records.length) {
+                return { records: page };
+            }
+            return {
+                records: page,
+                nextCursor: encodeArtifactPageCursor({
+                    v: 1,
+                    kind: "updated",
+                    u: last.updatedAt,
+                    c: last.createdAt,
+                    id: last.id,
+                }),
+            };
+        });
+    }
+    /**
+     * Resolve the effective kind (freeform when no kinds are declared) and
+     * the payload to persist. Like tool input schemas
+     * (`validateToolInput`), zod schemas validate *and* transform: the
+     * parsed output — defaults and coercions applied — is what gets stored.
+     */
+    resolveKindAndData(input) {
+        var _a;
+        var _b;
+        const kind = (_b = input.kind) !== null && _b !== void 0 ? _b : ARTIFACT_DEFAULT_KIND;
+        if (kind.trim() === "") {
+            throw new Error("artifacts.tag: kind must be a non-empty string");
+        }
+        const kinds = (_a = this.config) === null || _a === void 0 ? void 0 : _a.kinds;
+        if (kinds === undefined || Object.keys(kinds).length === 0) {
+            return { kind, data: input.data };
+        }
+        const kindConfig = kinds[kind];
+        if (kindConfig === undefined) {
+            throw new Error(`artifacts.tag: unknown kind ${JSON.stringify(kind)} (declared: ${Object.keys(kinds).join(", ")})`);
+        }
+        if (kindConfig.schema !== undefined) {
+            const parsed = kindConfig.schema.safeParse(input.data);
+            if (!parsed.success) {
+                throw new Error(`artifacts.tag: data does not match the ${JSON.stringify(kind)} schema: ${parsed.error.message}`);
+            }
+            return { kind, data: parsed.data };
+        }
+        return { kind, data: input.data };
+    }
+    /**
+     * Trim toward the retention cap from listing metadata alone. Past the
+     * cap this runs on every new-row insert, so it must not hydrate row
+     * bodies: on the Agent Store that is one read per row (~`max` reads per
+     * insert, forever, since eviction trims right back to the cap) — the
+     * 2026-09-18 read storm on the security-reviewer deployment. The store
+     * listing carries last-modified metadata, and a row is rewritten on
+     * every upsert, so listing mtime orders rows the same way their
+     * `updatedAt` does.
+     *
+     * Deletes are capped per pass: eviction runs inside `tag()`'s per-pod
+     * chain, so its wall time is tag latency for every queued caller. A
+     * store far past the cap (evictions failed during the 2026-09-19 read
+     * throttling and the backlog grew unchecked) must drain amortized
+     * across inserts, not wedge one insert deleting the whole backlog — on
+     * 2026-09-20 an uncapped pass held security-reviewer tags for hours and
+     * tripled review stage durations. Steady state (excess of 1) is
+     * unaffected.
+     */
+    evictPastCap() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const metas = yield this.rows.listMeta();
+            const excess = Math.min(metas.length - this.max, ARTIFACTS_EVICT_MAX_PER_PASS);
+            if (excess <= 0) {
+                return;
+            }
+            yield mapBounded(yield this.oldestRowIds(metas, excess), ROW_HYDRATION_CONCURRENCY, (id) => __awaiter(this, void 0, void 0, function* () {
+                yield this.rows.delete(id);
+                // Without the row body there is no `content` flag to consult;
+                // delete the payload unconditionally — absent ones are a no-op.
+                yield this.content.delete(id);
+            }));
+        });
+    }
+    /** The `excess` oldest row ids, cheapest available ordering first. */
+    oldestRowIds(metas, excess) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (metas.some(meta => meta.mtimeMs !== undefined)) {
+                // A store that tracks mtimes must never regress to per-insert
+                // hydration. The rare entry missing one (anomalous on such a store)
+                // sorts oldest via the comparator's `?? 0` and gets evicted first —
+                // evicting an anomaly beats re-reading every row on every insert.
+                return metas
+                    .sort(byOldestModified)
+                    .slice(0, excess)
+                    .map(meta => meta.id);
+            }
+            // A store that tracks no modification times at all (the local
+            // filesystem store, deliberately) leaves only the rows' own
+            // `updatedAt`: hydrate — bounded — and order exactly. Corrupt rows
+            // drop out of `list()`, so recompute the excess against the rows that
+            // actually parsed.
+            const records = yield this.rows.list();
+            return records
+                .sort((a, b) => byNewestUpdated(b, a))
+                .slice(0, Math.min(excess, Math.max(0, records.length - this.max)))
+                .map(record => record.id);
+        });
+    }
+}
+/** A syntactically invalid {@link ArtifactPageOptions.cursor}. */
+export class InvalidArtifactCursorError extends Error {
+    constructor() {
+        super("artifacts.page: invalid cursor");
+        this.name = "InvalidArtifactCursorError";
+    }
+}
+function encodeArtifactPageCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+/** Throws {@link InvalidArtifactCursorError} on anything undecodable. */
+function decodeArtifactPageCursor(raw) {
+    let value;
+    try {
+        value = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
+    }
+    catch (_a) {
+        throw new InvalidArtifactCursorError();
+    }
+    if (typeof value !== "object" || value === null) {
+        throw new InvalidArtifactCursorError();
+    }
+    const cursor = value;
+    if (cursor.v !== 1) {
+        throw new InvalidArtifactCursorError();
+    }
+    if (cursor.kind === "mtime" &&
+        typeof cursor.m === "number" &&
+        typeof cursor.s === "number" &&
+        Number.isInteger(cursor.s) &&
+        cursor.s >= 0) {
+        return { v: 1, kind: "mtime", m: cursor.m, s: cursor.s };
+    }
+    if (cursor.kind === "updated" &&
+        typeof cursor.u === "string" &&
+        typeof cursor.c === "string" &&
+        typeof cursor.id === "string") {
+        return { v: 1, kind: "updated", u: cursor.u, c: cursor.c, id: cursor.id };
+    }
+    throw new InvalidArtifactCursorError();
+}
+/** Deterministic id for a keyed tag (same key ⇒ same id ⇒ upsert). */
+export function artifactIdForKey(key) {
+    if (key.trim() === "") {
+        throw new Error("artifacts.tag: key must be a non-empty string");
+    }
+    return `art_${createHash("sha256").update(key, "utf8").digest("hex").slice(0, 32)}`;
+}
+/**
+ * Oldest-modified first. Store mtimes can be coarse (S3 rounds to the
+ * second), so equal stamps tie-break by id — deterministic, and within a
+ * same-stamp cohort any victim is equally past the retention cap.
+ */
+function byOldestModified(a, b) {
+    var _a, _b;
+    if (a.mtimeMs !== b.mtimeMs) {
+        return ((_a = a.mtimeMs) !== null && _a !== void 0 ? _a : 0) - ((_b = b.mtimeMs) !== null && _b !== void 0 ? _b : 0);
+    }
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+function byNewestUpdated(a, b) {
+    if (a.updatedAt !== b.updatedAt) {
+        return a.updatedAt < b.updatedAt ? 1 : -1;
+    }
+    // Tie-break so eviction and listing stay deterministic.
+    if (a.createdAt !== b.createdAt) {
+        return a.createdAt < b.createdAt ? 1 : -1;
+    }
+    return a.id < b.id ? 1 : a.id > b.id ? -1 : 0;
+}
+function isArtifactRecord(value) {
+    if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value) ||
+        typeof value.id !== "string" ||
+        typeof value.kind !== "string" ||
+        (value.source !== "host" && value.source !== "model") ||
+        typeof value.createdAt !== "string" ||
+        typeof value.updatedAt !== "string" ||
+        !("data" in value)) {
+        return false;
+    }
+    for (const field of ["key", "title", "sessionId", "turnId"]) {
+        if (value[field] !== undefined && typeof value[field] !== "string") {
+            return false;
+        }
+    }
+    return true;
+}
+function parseRecordBytes(bytes) {
+    if (bytes === undefined) {
+        return undefined;
+    }
+    let value;
+    try {
+        value = JSON.parse(Buffer.from(bytes).toString("utf8"));
+    }
+    catch (_a) {
+        // A corrupt row must not poison list().
+        return undefined;
+    }
+    return isArtifactRecord(value) ? value : undefined;
+}
+function sinkBody(found) {
+    if (found === undefined) {
+        return undefined;
+    }
+    return found instanceof Uint8Array ? found : found.body;
+}
+/** Rows as one JSON file each on the deployment's Agent Store. */
+function createSinkRowStore(sink, agentName) {
+    const key = (id) => agentStoreKeys.artifactRow(agentName, id);
+    return {
+        get(id) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return parseRecordBytes(sinkBody(yield sink.get(key(id))));
+            });
+        },
+        put(record) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield sink.put(key(record.id), Buffer.from(JSON.stringify(record), "utf8"));
+            });
+        },
+        delete(id) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield sink.delete(key(id));
+            });
+        },
+        getMany(ids) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const keys = ids.map(id => key(id));
+                const bodies = sink.getMany !== undefined
+                    ? yield sink.getMany(keys)
+                    : yield mapBounded(keys, ROW_HYDRATION_CONCURRENCY, rowKey => sink.get(rowKey));
+                return bodies.map(body => parseRecordBytes(sinkBody(body)));
+            });
+        },
+        list() {
+            return __awaiter(this, void 0, void 0, function* () {
+                const entries = yield sink.list(agentStoreKeys.artifactRowPrefix(agentName));
+                const bodies = sink.getMany !== undefined
+                    ? yield sink.getMany(entries.map(entry => entry.key))
+                    : yield mapBounded(entries, ROW_HYDRATION_CONCURRENCY, entry => sink.get(entry.key));
+                const records = [];
+                for (const body of bodies) {
+                    const record = parseRecordBytes(sinkBody(body));
+                    if (record !== undefined) {
+                        records.push(record);
+                    }
+                }
+                return records;
+            });
+        },
+        listMeta() {
+            return __awaiter(this, void 0, void 0, function* () {
+                const prefix = agentStoreKeys.artifactRowPrefix(agentName);
+                const metas = [];
+                for (const entry of yield sink.list(prefix)) {
+                    const id = rowIdFromName(entry.key.slice(prefix.length));
+                    if (id !== undefined) {
+                        metas.push({ id, mtimeMs: entry.mtimeMs });
+                    }
+                }
+                return metas;
+            });
+        },
+    };
+}
+/**
+ * Invert the row naming scheme (`encodeURIComponent(id) + ".json"`).
+ * Foreign keys under the prefix — no `.json` suffix, malformed escapes,
+ * non-canonical encodings — read as absent rather than throwing. The
+ * round-trip check matters for eviction: a name that decodes but does not
+ * re-encode to itself (`a+b.json`, `foo bar.json`) would count toward the
+ * cap yet be undeletable through `key(id)`, leaving a phantom victim that
+ * every subsequent insert re-selects and fails to remove.
+ */
+function rowIdFromName(name) {
+    if (!name.endsWith(".json") || name.includes("/")) {
+        return undefined;
+    }
+    const encoded = name.slice(0, -".json".length);
+    try {
+        const id = decodeURIComponent(encoded);
+        return encodeURIComponent(id) === encoded ? id : undefined;
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+function createSinkContentStore(sink, agentName) {
+    const key = (id) => agentStoreKeys.artifactContent(agentName, id);
+    return {
+        get(id) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return sinkBody(yield sink.get(key(id)));
+            });
+        },
+        put(id, body) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield sink.put(key(id), body);
+            });
+        },
+        delete(id) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield sink.delete(key(id));
+            });
+        },
+    };
+}
+function createFilesystemRowStore(stateRoot) {
+    const dir = join(stateRoot, "artifacts");
+    const filePath = (id) => join(dir, `${encodeURIComponent(id)}.json`);
+    // Missing and corrupt rows both read as absent — a truncated/garbled
+    // file must not poison list() (and with it every insert's eviction).
+    const readRecord = (path) => __awaiter(this, void 0, void 0, function* () {
+        try {
+            const value = JSON.parse(yield readFile(path, "utf8"));
+            return isArtifactRecord(value) ? value : undefined;
+        }
+        catch (error) {
+            if (error.code === "ENOENT" || error instanceof SyntaxError) {
+                return undefined;
+            }
+            throw error;
+        }
+    });
+    return {
+        get(id) {
+            return readRecord(filePath(id));
+        },
+        put(record) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield mkdir(dir, { recursive: true });
+                const tmp = join(dir, `.tmp-${randomUUID()}`);
+                yield writeFile(tmp, JSON.stringify(record), "utf8");
+                yield rename(tmp, filePath(record.id));
+            });
+        },
+        delete(id) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield rm(filePath(id), { force: true });
+            });
+        },
+        list() {
+            return __awaiter(this, void 0, void 0, function* () {
+                let names;
+                try {
+                    names = yield readdir(dir);
+                }
+                catch (error) {
+                    if (error.code === "ENOENT") {
+                        return [];
+                    }
+                    throw error;
+                }
+                const records = [];
+                for (const name of names.sort()) {
+                    if (name.startsWith(".") || !name.endsWith(".json")) {
+                        continue;
+                    }
+                    const record = yield readRecord(join(dir, name));
+                    if (record !== undefined) {
+                        records.push(record);
+                    }
+                }
+                return records;
+            });
+        },
+        listMeta() {
+            return __awaiter(this, void 0, void 0, function* () {
+                // No mtimes on purpose: local rows are cheap to hydrate, and the
+                // rows' own `updatedAt` orders eviction exactly, immune to coarse
+                // filesystem timestamp granularity.
+                let names;
+                try {
+                    names = yield readdir(dir);
+                }
+                catch (error) {
+                    if (error.code === "ENOENT") {
+                        return [];
+                    }
+                    throw error;
+                }
+                const metas = [];
+                for (const name of names) {
+                    if (name.startsWith(".")) {
+                        continue;
+                    }
+                    const id = rowIdFromName(name);
+                    if (id !== undefined) {
+                        metas.push({ id });
+                    }
+                }
+                return metas;
+            });
+        },
+    };
+}
+function createFilesystemContentStore(stateRoot) {
+    const dir = join(stateRoot, "artifacts", "content");
+    const filePath = (id) => join(dir, encodeURIComponent(id));
+    return {
+        get(id) {
+            return __awaiter(this, void 0, void 0, function* () {
+                try {
+                    return new Uint8Array(yield readFile(filePath(id)));
+                }
+                catch (error) {
+                    if (error.code === "ENOENT") {
+                        return undefined;
+                    }
+                    throw error;
+                }
+            });
+        },
+        put(id, body) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield mkdir(dir, { recursive: true });
+                const tmp = join(dir, `.tmp-${randomUUID()}`);
+                yield writeFile(tmp, body);
+                yield rename(tmp, filePath(id));
+            });
+        },
+        delete(id) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield rm(filePath(id), { force: true });
+            });
+        },
+    };
+}