@cursor/bdk 0.2.2 → 0.2.4

package/src/internal/artifacts-store.ts

@@ -1,836 +0,0 @@
-/**
- * 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;
-  /**
-   * Whether `tag` enforces {@link ArtifactsConfig.max} by listing and
-   * deleting. Default true. Hosted architecture v2 passes false: the
-   * installation store is allowed to grow, and a tag must not list the prefix.
-   */
-  enforceCap?: () => boolean;
-}
-
-/** 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.
- * Architecture v1 and self-hosted v2 evict. Hosted architecture v2 sets
- * {@link CreateArtifactsStoreOptions.enforceCap} false and does not list
- * or delete on tag. 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;
-  private readonly enforceCap: () => boolean;
-  /** 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);
-    this.enforceCap = options.enforceCap ?? (() => true);
-  }
-
-  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 && this.enforceCap()) {
-      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 });
-    },
-  };
-}