@cursor/bdk 0.2.1

package/src/internal/artifacts-store.ts

@@ -0,0 +1,825 @@
+/**
+ * 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.
+ */
+
+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, type FileSink } from "../files.js";
+import {
+  cursorHostedFiles,
+  isCursorHostedFilesAvailable,
+} from "../files-backends/cursor-hosted.js";
+import type {
+  ArtifactListFilter,
+  ArtifactPage,
+  ArtifactPageOptions,
+  ArtifactRecord,
+  ArtifactsConfig,
+  ArtifactTagInput,
+  JsonValue,
+} from "../types.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 = 1_000;
+/**
+ * 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;
+
+/** One row's identity + modification metadata, without its body. */
+interface ArtifactRowMeta {
+  id: string;
+  /** Last-modified epoch ms, when the backing store tracks one. */
+  mtimeMs?: number;
+}
+
+interface ArtifactRowStore {
+  get(id: string): Promise<ArtifactRecord | undefined>;
+  /**
+   * Batched {@link get}, index-aligned with `ids`; a miss is `undefined`.
+   * Optional — the paged scan falls back to bounded per-id gets. The sink
+   * row store implements it over `FileSink.getMany` so a page walk spends
+   * one control-plane call per 100 rows instead of one per row.
+   */
+  getMany?(ids: readonly string[]): Promise<Array<ArtifactRecord | undefined>>;
+  put(record: ArtifactRecord): Promise<void>;
+  delete(id: string): Promise<void>;
+  list(): Promise<ArtifactRecord[]>;
+  /**
+   * Row ids + modification metadata without hydrating bodies — the
+   * per-insert cap check and (when mtimes are tracked) the eviction order.
+   */
+  listMeta(): Promise<ArtifactRowMeta[]>;
+}
+
+/** File/blob payload bytes, keyed by artifact id (metadata lives on the row). */
+interface ArtifactContentStore {
+  get(id: string): Promise<Uint8Array | undefined>;
+  put(id: string, body: Uint8Array): Promise<void>;
+  delete(id: string): Promise<void>;
+}
+
+export interface CreateArtifactsStoreOptions {
+  stateRoot: string;
+  agentName: string;
+  /** `agent/artifacts.ts` config, when authored. */
+  config?: ArtifactsConfig;
+  /** Explicit sink override (tests). Omitted → hosted store or local disk. */
+  sink?: FileSink;
+}
+
+/** 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 {
+  private readonly rows: ArtifactRowStore;
+  private readonly content: ArtifactContentStore;
+  private readonly config: ArtifactsConfig | undefined;
+  private readonly max: number;
+  /** Serializes tags so read-modify-write upserts and eviction don't race. */
+  private tagChain: Promise<unknown> = Promise.resolve();
+
+  constructor(options: CreateArtifactsStoreOptions) {
+    const sink = options.sink ?? (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: ArtifactTagInput): Promise<ArtifactRecord> {
+    const result = this.tagChain.then(() => this.tagSerialized(input));
+    this.tagChain = result.catch(() => {});
+    return result;
+  }
+
+  private async tagSerialized(input: ArtifactTagInput): Promise<ArtifactRecord> {
+    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 : await this.rows.get(id);
+    const now = new Date().toISOString();
+    const record: ArtifactRecord = {
+      id,
+      kind,
+      key: input.key,
+      title: input.title,
+      data,
+      sessionId: input.sessionId,
+      turnId: input.turnId,
+      source: input.source ?? "host",
+      createdAt: existing?.createdAt ?? now,
+      updatedAt: now,
+    };
+    if (input.contents !== undefined) {
+      const body =
+        typeof input.contents === "string" ? Buffer.from(input.contents, "utf8") : input.contents;
+      await this.content.put(id, body);
+      record.content = {
+        size: body.byteLength,
+        contentType: input.contentType,
+      };
+    } else if (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.
+        await this.content.delete(id);
+      }
+    }
+    await this.rows.put(record);
+    if (existing === undefined) {
+      await this.evictPastCap();
+    }
+    return record;
+  }
+
+  get(id: string): Promise<ArtifactRecord | undefined> {
+    return this.rows.get(id);
+  }
+
+  /** Payload bytes for one artifact; undefined when it carries none. */
+  getContent(id: string): Promise<Uint8Array | undefined> {
+    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}.
+   */
+  async list(filter?: ArtifactListFilter): Promise<ArtifactRecord[]> {
+    const page = await 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).
+   */
+  async page(
+    options?: ArtifactPageOptions & {
+      matches?: (record: ArtifactRecord) => boolean;
+    },
+  ): Promise<ArtifactPage> {
+    const limit = Math.min(
+      Math.max(options?.limit ?? ARTIFACTS_PAGE_DEFAULT_LIMIT, 1),
+      ARTIFACTS_PAGE_MAX_LIMIT,
+    );
+    const cursor =
+      options?.cursor === undefined ? undefined : decodeArtifactPageCursor(options.cursor);
+    const matches = (record: ArtifactRecord): boolean =>
+      (options?.kind === undefined || record.kind === options.kind) &&
+      (options?.sessionId === undefined || record.sessionId === options.sessionId) &&
+      (options?.matches === undefined || options.matches(record));
+
+    if (options?.matches === undefined) {
+      const metas = await this.rows.listMeta();
+      if (metas.some(meta => meta.mtimeMs !== undefined)) {
+        return this.pageFromMetadata(
+          metas,
+          limit,
+          cursor,
+          matches,
+          options?.kind !== undefined || 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.
+   */
+  private async pageFromMetadata(
+    metas: ArtifactRowMeta[],
+    limit: number,
+    cursor: ArtifactPageCursor | undefined,
+    matches: (record: ArtifactRecord) => boolean,
+    filtered: boolean,
+  ): Promise<ArtifactPage> {
+    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 => (meta.mtimeMs ?? 0) <= cursor.m);
+      if (start === -1) {
+        return { records: [] };
+      }
+      let skipped = 0;
+      while (
+        start < newestFirst.length &&
+        (newestFirst[start]?.mtimeMs ?? 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: ArtifactRecord[] = [];
+    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
+          ? await this.rows.getMany(batch.map(meta => meta.id))
+          : await 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 = (newestFirst[lastExamined] as ArtifactRowMeta).mtimeMs ?? 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 && (newestFirst[i]?.mtimeMs ?? 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.
+   */
+  private async pageFromRecords(
+    limit: number,
+    cursor: ArtifactPageCursor | undefined,
+    matches: (record: ArtifactRecord) => boolean,
+  ): Promise<ArtifactPage> {
+    const records = (await 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,
+      } as ArtifactRecord;
+      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.
+   */
+  private resolveKindAndData(input: ArtifactTagInput): {
+    kind: string;
+    data: JsonValue;
+  } {
+    const kind = input.kind ?? ARTIFACT_DEFAULT_KIND;
+    if (kind.trim() === "") {
+      throw new Error("artifacts.tag: kind must be a non-empty string");
+    }
+    const kinds = this.config?.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 as JsonValue };
+    }
+    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.
+   */
+  private async evictPastCap(): Promise<void> {
+    const metas = await this.rows.listMeta();
+    const excess = Math.min(metas.length - this.max, ARTIFACTS_EVICT_MAX_PER_PASS);
+    if (excess <= 0) {
+      return;
+    }
+    await mapBounded(
+      await this.oldestRowIds(metas, excess),
+      ROW_HYDRATION_CONCURRENCY,
+      async id => {
+        await 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.
+        await this.content.delete(id);
+      },
+    );
+  }
+
+  /** The `excess` oldest row ids, cheapest available ordering first. */
+  private async oldestRowIds(metas: ArtifactRowMeta[], excess: number): Promise<string[]> {
+    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 = await 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";
+  }
+}
+
+/**
+ * Resume position, opaque to callers (base64url JSON). Which kind a store
+ * mints follows which ordering source it paged from.
+ *
+ * `mtime` is purely positional — the boundary modification stamp plus how
+ * many rows of that same-stamp cohort were already examined. It must never
+ * carry a row id: the scan examines rows the caller's visibility predicate
+ * then rejects, so a cursor naming the last *examined* row would hand
+ * strict-auth callers other principals' artifact ids inside an unsigned
+ * token. `updated` names only the last *returned* record, which the caller
+ * already received.
+ */
+type ArtifactPageCursor =
+  | { v: 1; kind: "mtime"; m: number; s: number }
+  | { v: 1; kind: "updated"; u: string; c: string; id: string };
+
+function encodeArtifactPageCursor(cursor: ArtifactPageCursor): string {
+  return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+
+/** Throws {@link InvalidArtifactCursorError} on anything undecodable. */
+function decodeArtifactPageCursor(raw: string): ArtifactPageCursor {
+  let value: unknown;
+  try {
+    value = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
+  } catch {
+    throw new InvalidArtifactCursorError();
+  }
+  if (typeof value !== "object" || value === null) {
+    throw new InvalidArtifactCursorError();
+  }
+  const cursor = value as Record<string, unknown>;
+  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: string): string {
+  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: ArtifactRowMeta, b: ArtifactRowMeta): number {
+  if (a.mtimeMs !== b.mtimeMs) {
+    return (a.mtimeMs ?? 0) - (b.mtimeMs ?? 0);
+  }
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+
+function byNewestUpdated(a: ArtifactRecord, b: ArtifactRecord): number {
+  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: JsonValue | undefined): value is ArtifactRecord & JsonValue {
+  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"] as const) {
+    if (value[field] !== undefined && typeof value[field] !== "string") {
+      return false;
+    }
+  }
+  return true;
+}
+
+function parseRecordBytes(bytes: Uint8Array | undefined): ArtifactRecord | undefined {
+  if (bytes === undefined) {
+    return undefined;
+  }
+  let value: JsonValue;
+  try {
+    value = JSON.parse(Buffer.from(bytes).toString("utf8")) as JsonValue;
+  } catch {
+    // A corrupt row must not poison list().
+    return undefined;
+  }
+  return isArtifactRecord(value) ? value : undefined;
+}
+
+function sinkBody(found: Awaited<ReturnType<FileSink["get"]>>): Uint8Array | undefined {
+  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: FileSink, agentName: string): ArtifactRowStore {
+  const key = (id: string): string => agentStoreKeys.artifactRow(agentName, id);
+  return {
+    async get(id): Promise<ArtifactRecord | undefined> {
+      return parseRecordBytes(sinkBody(await sink.get(key(id))));
+    },
+    async put(record): Promise<void> {
+      await sink.put(key(record.id), Buffer.from(JSON.stringify(record), "utf8"));
+    },
+    async delete(id): Promise<void> {
+      await sink.delete(key(id));
+    },
+    async getMany(ids): Promise<Array<ArtifactRecord | undefined>> {
+      const keys = ids.map(id => key(id));
+      const bodies =
+        sink.getMany !== undefined
+          ? await sink.getMany(keys)
+          : await mapBounded(keys, ROW_HYDRATION_CONCURRENCY, rowKey => sink.get(rowKey));
+      return bodies.map(body => parseRecordBytes(sinkBody(body)));
+    },
+    async list(): Promise<ArtifactRecord[]> {
+      const entries = await sink.list(agentStoreKeys.artifactRowPrefix(agentName));
+      const bodies =
+        sink.getMany !== undefined
+          ? await sink.getMany(entries.map(entry => entry.key))
+          : await mapBounded(entries, ROW_HYDRATION_CONCURRENCY, entry => sink.get(entry.key));
+      const records: ArtifactRecord[] = [];
+      for (const body of bodies) {
+        const record = parseRecordBytes(sinkBody(body));
+        if (record !== undefined) {
+          records.push(record);
+        }
+      }
+      return records;
+    },
+    async listMeta(): Promise<ArtifactRowMeta[]> {
+      const prefix = agentStoreKeys.artifactRowPrefix(agentName);
+      const metas: ArtifactRowMeta[] = [];
+      for (const entry of await 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: string): string | undefined {
+  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 {
+    return undefined;
+  }
+}
+
+function createSinkContentStore(sink: FileSink, agentName: string): ArtifactContentStore {
+  const key = (id: string): string => agentStoreKeys.artifactContent(agentName, id);
+  return {
+    async get(id): Promise<Uint8Array | undefined> {
+      return sinkBody(await sink.get(key(id)));
+    },
+    async put(id, body): Promise<void> {
+      await sink.put(key(id), body);
+    },
+    async delete(id): Promise<void> {
+      await sink.delete(key(id));
+    },
+  };
+}
+
+function createFilesystemRowStore(stateRoot: string): ArtifactRowStore {
+  const dir = join(stateRoot, "artifacts");
+  const filePath = (id: string): string => 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 = async (path: string): Promise<ArtifactRecord | undefined> => {
+    try {
+      const value = JSON.parse(await readFile(path, "utf8")) as JsonValue;
+      return isArtifactRecord(value) ? value : undefined;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT" || error instanceof SyntaxError) {
+        return undefined;
+      }
+      throw error;
+    }
+  };
+
+  return {
+    get(id): Promise<ArtifactRecord | undefined> {
+      return readRecord(filePath(id));
+    },
+    async put(record): Promise<void> {
+      await mkdir(dir, { recursive: true });
+      const tmp = join(dir, `.tmp-${randomUUID()}`);
+      await writeFile(tmp, JSON.stringify(record), "utf8");
+      await rename(tmp, filePath(record.id));
+    },
+    async delete(id): Promise<void> {
+      await rm(filePath(id), { force: true });
+    },
+    async list(): Promise<ArtifactRecord[]> {
+      let names: string[];
+      try {
+        names = await readdir(dir);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+          return [];
+        }
+        throw error;
+      }
+      const records: ArtifactRecord[] = [];
+      for (const name of names.sort()) {
+        if (name.startsWith(".") || !name.endsWith(".json")) {
+          continue;
+        }
+        const record = await readRecord(join(dir, name));
+        if (record !== undefined) {
+          records.push(record);
+        }
+      }
+      return records;
+    },
+    async listMeta(): Promise<ArtifactRowMeta[]> {
+      // 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: string[];
+      try {
+        names = await readdir(dir);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+          return [];
+        }
+        throw error;
+      }
+      const metas: ArtifactRowMeta[] = [];
+      for (const name of names) {
+        if (name.startsWith(".")) {
+          continue;
+        }
+        const id = rowIdFromName(name);
+        if (id !== undefined) {
+          metas.push({ id });
+        }
+      }
+      return metas;
+    },
+  };
+}
+
+function createFilesystemContentStore(stateRoot: string): ArtifactContentStore {
+  const dir = join(stateRoot, "artifacts", "content");
+  const filePath = (id: string): string => join(dir, encodeURIComponent(id));
+  return {
+    async get(id): Promise<Uint8Array | undefined> {
+      try {
+        return new Uint8Array(await readFile(filePath(id)));
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+          return undefined;
+        }
+        throw error;
+      }
+    },
+    async put(id, body): Promise<void> {
+      await mkdir(dir, { recursive: true });
+      const tmp = join(dir, `.tmp-${randomUUID()}`);
+      await writeFile(tmp, body);
+      await rename(tmp, filePath(id));
+    },
+    async delete(id): Promise<void> {
+      await rm(filePath(id), { force: true });
+    },
+  };
+}