@springbrand/space 0.2.0-alpha.15 → 0.2.0-alpha.17

package/src/space/space-files.ts

@@ -0,0 +1,1055 @@
+import type { FileInfo, WorkspaceFsLike } from "@cloudflare/shell"
+import { createHash } from "node:crypto"
+import {
+  createFileContentCache,
+  FILE_CACHE_MAX_ENTRY_BYTES,
+  type CachedFileVersion,
+  type FileContentCache,
+  type FileContentCacheOptions,
+} from "./file-content-cache"
+import { inferMimeType } from "./fileinfo"
+import { isReservedSpacePath, normalizeSpacePath, toBytes } from "./workspace-port"
+
+export type SpaceFileOrigin = "user_upload" | "https_import" | "action" | "agent" | "userspace"
+export type SpaceUnderstandingStatus = "not_requested" | "pending" | "ready" | "failed" | "unsupported"
+
+export type SpaceFileEvidence = {
+  summary: string
+  body: string
+  warnings: string[]
+  truncated: boolean
+}
+
+export const SPACE_FILE_EVIDENCE_JSON_SCHEMA = {
+  type: "object",
+  properties: {
+    summary: { type: "string" },
+    body: { type: "string" },
+    warnings: { type: "array", items: { type: "string" } },
+    truncated: { type: "boolean" },
+  },
+  required: ["summary", "body", "warnings", "truncated"],
+  additionalProperties: false,
+} as const
+
+const EVIDENCE_MAX_BYTES = 32 * 1024
+export const WORKSPACE_BUFFERED_READ_MAX_BYTES = 50 * 1024 * 1024
+
+export function normalizeSpaceFileEvidence(input: unknown): SpaceFileEvidence {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("Invalid Workspace file Evidence")
+  }
+  const value = input as Record<string, unknown>
+  const keys = Object.keys(value)
+  if (
+    keys.length !== 4 ||
+    keys.some((key) => !["summary", "body", "warnings", "truncated"].includes(key)) ||
+    typeof value.summary !== "string" || typeof value.body !== "string" ||
+    !Array.isArray(value.warnings) || !value.warnings.every((warning) => typeof warning === "string") ||
+    typeof value.truncated !== "boolean"
+  ) throw new Error("Invalid Workspace file Evidence")
+  let truncated = value.truncated
+  const clamp = (text: string, max: number) => {
+    const points = [...text]
+    if (points.length <= max) return text
+    truncated = true
+    return points.slice(0, max).join("")
+  }
+  const evidence: SpaceFileEvidence = {
+    summary: clamp(value.summary, 2_000),
+    body: value.body,
+    warnings: value.warnings.slice(0, 16).map((warning) => clamp(warning, 1_000)),
+    truncated,
+  }
+  if (evidence.warnings.length !== value.warnings.length) evidence.truncated = true
+  while (new TextEncoder().encode(JSON.stringify(evidence)).byteLength > EVIDENCE_MAX_BYTES) {
+    if (evidence.body) evidence.body = [...evidence.body].slice(0, Math.floor([...evidence.body].length / 2)).join("")
+    else if (evidence.warnings.length) evidence.warnings.pop()
+    else evidence.summary = ""
+    evidence.truncated = true
+  }
+  return evidence
+}
+
+export type RegisterExistingContentsInput = {
+  parent: string
+  ownerId: string
+  maxTotalBytes?: number
+  files: Array<{
+    name: string
+    contentKey: string
+    mediaType: string
+    origin: SpaceFileOrigin
+  }>
+}
+
+export type SpaceFileInspection = FileInfo & {
+  attachmentId?: string
+  contentVersion?: string
+  cdnUrl?: string
+  origin?: SpaceFileOrigin
+  understandingStatus?: SpaceUnderstandingStatus
+  evidence?: SpaceFileEvidence
+}
+
+export type WorkspaceFileStream = {
+  body: ReadableStream<Uint8Array>
+  size: number
+  mediaType: string
+  contentVersion: string
+}
+
+type FileRow = {
+  rowId: string
+  path: string
+  parentPath: string
+  name: string
+  type: "file" | "directory" | "symlink"
+  mimeType: string
+  size: number
+  target: string | null
+  createdAt: number
+  modifiedAt: number
+  attachmentId: string | null
+  contentVersion: string | null
+  contentKey: string | null
+  sha256: string | null
+  origin: SpaceFileOrigin | null
+  contentOwnership: "workspace_owned" | "referenced" | null
+  understandingStatus: SpaceUnderstandingStatus | null
+  evidenceJson: string | null
+  inlineContent: ArrayBuffer | null
+}
+
+function modifiedAtAfter(previous: FileRow | null): number {
+  return Math.max(Date.now(), (previous?.modifiedAt ?? 0) + 1_000)
+}
+
+const TABLE = "space_files"
+const FILE_ROW_COLUMNS = `
+  row_id AS rowId, path, parent_path AS parentPath, name, type,
+  mime_type AS mimeType, size, target, created_at AS createdAt,
+  modified_at AS modifiedAt, attachment_id AS attachmentId,
+  content_version AS contentVersion, content_key AS contentKey, sha256,
+  origin, content_ownership AS contentOwnership,
+  understanding_status AS understandingStatus, evidence_json AS evidenceJson,
+  inline_content AS inlineContent
+`
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+function id(prefix: "att" | "ver" | "row"): string {
+  return `${prefix}_${crypto.randomUUID()}`
+}
+
+function parentPath(path: string): string {
+  const index = path.lastIndexOf("/")
+  return index <= 0 ? "/" : path.slice(0, index)
+}
+
+function basename(path: string): string {
+  return path === "/" ? "" : path.slice(path.lastIndexOf("/") + 1)
+}
+
+// Internal filesystem calls from Git may contain dot segments. Public Space
+// methods normalize and reject caller traversal before they reach this adapter.
+function normalizeInternalPath(path: string): string {
+  const value = path.trim().replaceAll("\\", "/")
+  const parts: string[] = []
+  for (const part of value.split("/")) {
+    if (!part || part === ".") continue
+    if (part === "..") parts.pop()
+    else parts.push(part)
+  }
+  return `/${parts.join("/")}`
+}
+
+function writableFilePath(path: string): string {
+  const value = normalizeInternalPath(path)
+  if (value === "/") throw new Error("The Space root is not a file")
+  return value
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[|\\{}()[\]^$+?.]/gu, "\\$&")
+}
+
+function globRegex(pattern: string): RegExp {
+  const normalized = normalizeInternalPath(pattern)
+  let source = ""
+  for (let index = 0; index < normalized.length; index++) {
+    const char = normalized[index]!
+    if (char !== "*") {
+      source += char === "?" ? "[^/]" : escapeRegex(char)
+      continue
+    }
+    if (normalized[index + 1] === "*") {
+      if (normalized[index + 2] === "/") {
+        source += "(?:.*/)?"
+        index += 2
+      } else {
+        source += ".*"
+        index++
+      }
+    } else {
+      source += "[^/]*"
+    }
+  }
+  return new RegExp(`^${source}$`, "u")
+}
+
+async function digest(bytes: Uint8Array): Promise<string> {
+  const value = await crypto.subtle.digest("SHA-256", bytes)
+  return [...new Uint8Array(value)].map((part) => part.toString(16).padStart(2, "0")).join("")
+}
+
+async function putStream(
+  bucket: R2Bucket,
+  key: string,
+  body: ReadableStream<Uint8Array>,
+  mediaType: string,
+): Promise<void> {
+  const upload = await bucket.createMultipartUpload(key, {
+    httpMetadata: { contentType: mediaType },
+  })
+  const reader = body.getReader()
+  const parts: R2UploadedPart[] = []
+  const chunkBytes = 5 * 1024 * 1024
+  let buffer = new Uint8Array(chunkBytes)
+  let buffered = 0
+  let partNumber = 1
+  const flush = async () => {
+    if (buffered === 0) return
+    parts.push(await upload.uploadPart(partNumber++, buffer.slice(0, buffered)))
+    buffer = new Uint8Array(chunkBytes)
+    buffered = 0
+  }
+  try {
+    while (true) {
+      const chunk = await reader.read()
+      if (chunk.done) break
+      let offset = 0
+      while (offset < chunk.value.byteLength) {
+        const length = Math.min(buffer.byteLength - buffered, chunk.value.byteLength - offset)
+        buffer.set(chunk.value.subarray(offset, offset + length), buffered)
+        buffered += length
+        offset += length
+        if (buffered === buffer.byteLength) await flush()
+      }
+    }
+    await flush()
+    if (parts.length === 0) {
+      await upload.abort()
+      await bucket.put(key, new Uint8Array(), { httpMetadata: { contentType: mediaType } })
+      return
+    }
+    await upload.complete(parts)
+  } catch (error) {
+    await upload.abort().catch(() => undefined)
+    throw error
+  } finally {
+    reader.releaseLock()
+  }
+}
+
+/** Space-owned file store: one SQLite file table and immutable R2 content. */
+export class SpaceFiles implements WorkspaceFsLike {
+  private readonly cache: FileContentCache
+
+  constructor(
+    private readonly state: DurableObjectState,
+    private readonly bucket: R2Bucket,
+    private readonly spaceId: string,
+    private readonly publicOrigin: string,
+    cacheOptions?: FileContentCacheOptions,
+  ) {
+    this.cache = createFileContentCache(state.storage.sql, cacheOptions)
+    this.ensureSchema()
+  }
+
+  private ensureSchema(): void {
+    this.state.storage.sql.exec(`
+      CREATE TABLE IF NOT EXISTS ${TABLE} (
+        row_id TEXT PRIMARY KEY,
+        path TEXT NOT NULL,
+        parent_path TEXT NOT NULL,
+        name TEXT NOT NULL,
+        type TEXT NOT NULL CHECK(type IN ('file','directory','symlink')),
+        mime_type TEXT NOT NULL,
+        size INTEGER NOT NULL DEFAULT 0,
+        target TEXT,
+        created_at INTEGER NOT NULL,
+        modified_at INTEGER NOT NULL,
+        attachment_id TEXT,
+        content_version TEXT,
+        content_key TEXT,
+        sha256 TEXT,
+        origin TEXT CHECK(origin IS NULL OR origin IN ('user_upload','https_import','action','agent','userspace')),
+        content_ownership TEXT CHECK(content_ownership IS NULL OR content_ownership IN ('workspace_owned','referenced')),
+        understanding_status TEXT CHECK(understanding_status IS NULL OR understanding_status IN ('not_requested','pending','ready','failed','unsupported')),
+        understanding_attempts INTEGER NOT NULL DEFAULT 0,
+        evidence_json TEXT,
+        inline_content BLOB,
+        write_state TEXT NOT NULL CHECK(write_state IN ('writing','ready')),
+        current INTEGER NOT NULL CHECK(current IN (0,1))
+      );
+      CREATE UNIQUE INDEX IF NOT EXISTS space_files_current_path
+        ON ${TABLE}(path) WHERE current = 1;
+      CREATE UNIQUE INDEX IF NOT EXISTS space_files_attachment_version
+        ON ${TABLE}(attachment_id, content_version)
+        WHERE attachment_id IS NOT NULL AND content_version IS NOT NULL;
+      CREATE INDEX IF NOT EXISTS space_files_parent
+        ON ${TABLE}(parent_path, current, write_state);
+    `)
+    const columns = new Set(
+      this.state.storage.sql.exec<{ name: string }>(`PRAGMA table_info(${TABLE})`)
+        .toArray().map(({ name }) => name),
+    )
+    if (!columns.has("inline_content")) {
+      this.state.storage.sql.exec(`ALTER TABLE ${TABLE} ADD COLUMN inline_content BLOB`)
+    }
+    if (!this.row("/")) {
+      const now = Date.now()
+      this.state.storage.sql.exec(
+        `INSERT INTO ${TABLE}
+          (row_id,path,parent_path,name,type,mime_type,size,created_at,modified_at,write_state,current)
+         VALUES (?, '/', '/', '', 'directory', 'inode/directory', 0, ?, ?, 'ready', 1)`,
+        id("row"), now, now,
+      )
+    }
+  }
+
+  async ready(): Promise<void> {
+    const legacy = this.state.storage.sql.exec<{ name: string }>(
+      "SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'cf_workspace_default'",
+    ).toArray()[0]
+    if (legacy) {
+      const rows = this.state.storage.sql.exec<{
+        path: string
+        type: "file" | "directory" | "symlink"
+        mimeType: string
+        storageBackend: "inline" | "r2"
+        r2Key: string | null
+        target: string | null
+        contentEncoding: "utf8" | "base64"
+        content: string | null
+      }>(`
+        SELECT path, type, mime_type AS mimeType, storage_backend AS storageBackend,
+          r2_key AS r2Key, target, content_encoding AS contentEncoding, content
+        FROM cf_workspace_default WHERE path <> '/' ORDER BY length(path), path
+      `).toArray()
+      for (const row of rows) {
+        if (row.type === "directory") {
+          await this.mkdir(row.path, { recursive: true })
+          continue
+        }
+        if (row.type === "symlink") {
+          await this.symlink(row.target ?? "", row.path)
+          continue
+        }
+        const bytes = row.storageBackend === "r2" && row.r2Key
+          ? await this.bucket.get(row.r2Key).then(async (object) =>
+              object ? new Uint8Array(await object.arrayBuffer()) : null)
+          : row.contentEncoding === "base64"
+            ? Uint8Array.from(atob(row.content ?? ""), (character) => character.charCodeAt(0))
+            : encoder.encode(row.content ?? "")
+        if (!bytes) throw new Error(`Legacy Workspace content is missing: ${row.path}`)
+        await this.commitBytes(row.path, bytes, row.mimeType, "agent")
+      }
+      this.state.storage.sql.exec("DROP TABLE cf_workspace_default")
+    }
+    await this.recoverWritingRows()
+    await this.inlineSystemContent()
+  }
+
+  async clearCache(): Promise<void> {
+    await this.cache.clear()
+  }
+
+  private async recoverWritingRows(): Promise<void> {
+    const rows = this.state.storage.sql.exec<{
+      rowId: string
+      path: string
+      attachmentId: string | null
+      contentVersion: string | null
+      contentKey: string | null
+      mediaType: string
+      size: number
+      sha256: string | null
+    }>(`
+      SELECT row_id AS rowId, path, attachment_id AS attachmentId,
+        content_version AS contentVersion, content_key AS contentKey,
+        mime_type AS mediaType, size, sha256
+      FROM ${TABLE}
+      WHERE write_state = 'writing'
+      ORDER BY modified_at, row_id
+    `).toArray()
+    for (const row of rows) {
+      const cached = row.attachmentId && row.contentVersion
+        ? { attachmentId: row.attachmentId, contentVersion: row.contentVersion, size: row.size }
+        : null
+      const object = row.contentKey ? await this.bucket.get(row.contentKey) : null
+      if (!object || object.httpMetadata?.contentType !== row.mediaType) {
+        if (row.contentKey && object) await this.bucket.delete(row.contentKey)
+        this.state.storage.sql.exec(`DELETE FROM ${TABLE} WHERE row_id = ?`, row.rowId)
+        await this.removeCached(cached)
+        continue
+      }
+      const bytes = new Uint8Array(await object.arrayBuffer())
+      const sha256 = await digest(bytes)
+      if (row.sha256 !== null && (row.size !== bytes.byteLength || row.sha256 !== sha256)) {
+        await this.bucket.delete(row.contentKey!)
+        this.state.storage.sql.exec(`DELETE FROM ${TABLE} WHERE row_id = ?`, row.rowId)
+        await this.removeCached(cached)
+        continue
+      }
+      this.state.storage.transactionSync(() => {
+        this.state.storage.sql.exec(
+          `UPDATE ${TABLE} SET current = 0 WHERE path = ? AND current = 1`,
+          row.path,
+        )
+        this.state.storage.sql.exec(
+          `UPDATE ${TABLE}
+           SET size = ?, sha256 = ?, write_state = 'ready', current = 1
+           WHERE row_id = ?`,
+          bytes.byteLength, sha256, row.rowId,
+        )
+      })
+    }
+  }
+
+  private async inlineSystemContent(): Promise<void> {
+    const rows = this.state.storage.sql.exec<{
+      rowId: string
+      contentKey: string
+    }>(`
+      SELECT row_id AS rowId, content_key AS contentKey
+      FROM ${TABLE}
+      WHERE current = 1 AND type = 'file' AND inline_content IS NULL
+        AND content_key IS NOT NULL
+        AND size <= ?
+        AND (path = '/.git' OR path LIKE '/.git/%' OR path = '/.afs' OR path LIKE '/.afs/%')
+    `, FILE_CACHE_MAX_ENTRY_BYTES).toArray()
+    for (let offset = 0; offset < rows.length; offset += 16) {
+      await Promise.all(rows.slice(offset, offset + 16).map(async ({ rowId, contentKey }) => {
+        const object = await this.bucket.get(contentKey)
+        if (!object) throw new Error(`Space system content is missing: ${contentKey}`)
+        const bytes = new Uint8Array(await object.arrayBuffer())
+        this.state.storage.sql.exec(
+          `UPDATE ${TABLE}
+           SET inline_content = ?, content_key = NULL, attachment_id = NULL,
+             content_version = NULL, sha256 = NULL, origin = NULL,
+             content_ownership = NULL, understanding_status = NULL,
+             understanding_attempts = 0, evidence_json = NULL
+           WHERE row_id = ?`,
+          bytes.buffer, rowId,
+        )
+        await this.bucket.delete(contentKey)
+      }))
+    }
+  }
+
+  private row(path: string): FileRow | null {
+    return this.state.storage.sql.exec<FileRow>(`
+      SELECT ${FILE_ROW_COLUMNS}
+      FROM ${TABLE}
+      WHERE path = ? AND current = 1 AND write_state = 'ready'
+      LIMIT 1
+    `, normalizeInternalPath(path)).toArray()[0] ?? null
+  }
+
+  private info(row: FileRow): SpaceFileInspection {
+    return {
+      path: row.path,
+      name: row.name,
+      type: row.type,
+      mimeType: row.mimeType,
+      size: row.size,
+      createdAt: row.createdAt,
+      updatedAt: row.modifiedAt,
+      ...(row.target ? { target: row.target } : {}),
+      ...(row.attachmentId ? { attachmentId: row.attachmentId } : {}),
+      ...(row.contentVersion ? { contentVersion: row.contentVersion } : {}),
+      ...(row.contentKey ? { cdnUrl: new URL(`/${row.contentKey}`, this.publicOrigin).href } : {}),
+      ...(row.origin ? { origin: row.origin } : {}),
+      ...(row.understandingStatus ? { understandingStatus: row.understandingStatus } : {}),
+      ...(row.evidenceJson ? { evidence: JSON.parse(row.evidenceJson) as SpaceFileEvidence } : {}),
+    }
+  }
+
+  private async ensureParent(path: string): Promise<void> {
+    await this.mkdir(parentPath(path), { recursive: true })
+  }
+
+  private contentKey(attachmentId: string, contentVersion: string): string {
+    return `spaces/v2/${encodeURIComponent(this.spaceId)}/files/${attachmentId}/${contentVersion}`
+  }
+
+  private cachedVersion(row: FileRow): CachedFileVersion | null {
+    return row.attachmentId && row.contentVersion
+      ? { attachmentId: row.attachmentId, contentVersion: row.contentVersion, size: row.size }
+      : null
+  }
+
+  private async cachedBytes(row: FileRow): Promise<Uint8Array | null> {
+    const file = this.cachedVersion(row)
+    if (!file) return null
+    try {
+      return await this.cache.get(file)
+    } catch (error) {
+      console.warn("Workspace file cache read failed; falling back to R2", error)
+      return null
+    }
+  }
+
+  private async cacheBytes(file: CachedFileVersion, bytes: Uint8Array): Promise<void> {
+    try {
+      await this.cache.put(file, bytes)
+    } catch (error) {
+      console.warn("Workspace file cache write failed; continuing with R2", error)
+    }
+  }
+
+  private async removeCached(file: CachedFileVersion | null): Promise<void> {
+    if (!file) return
+    try {
+      await this.cache.remove(file)
+    } catch (error) {
+      console.warn("Workspace file cache cleanup failed", error)
+    }
+  }
+
+  private async commitBytes(
+    path: string,
+    bytes: Uint8Array,
+    mediaType: string,
+    origin: SpaceFileOrigin,
+  ): Promise<void> {
+    const target = writableFilePath(path)
+    await this.ensureParent(target)
+    const previous = this.row(target)
+    if (previous?.type === "directory") throw new Error(`EISDIR: ${target} is a directory`)
+    if (isReservedSpacePath(target) && bytes.byteLength <= FILE_CACHE_MAX_ENTRY_BYTES) {
+      const now = modifiedAtAfter(previous)
+      this.state.storage.transactionSync(() => {
+        this.state.storage.sql.exec(
+          `UPDATE ${TABLE} SET current = 0 WHERE path = ? AND current = 1`,
+          target,
+        )
+        this.state.storage.sql.exec(
+          `INSERT INTO ${TABLE}
+            (row_id,path,parent_path,name,type,mime_type,size,created_at,modified_at,
+             inline_content,write_state,current)
+           VALUES (?,?,?,?, 'file', ?, ?, ?, ?, ?, 'ready', 1)`,
+          id("row"), target, parentPath(target), basename(target), mediaType,
+          bytes.byteLength, previous?.createdAt ?? now, now, bytes.slice().buffer,
+        )
+      })
+      return
+    }
+    const attachmentId = previous?.type === "file" && previous.attachmentId
+      ? previous.attachmentId
+      : id("att")
+    const contentVersion = id("ver")
+    const contentKey = this.contentKey(attachmentId, contentVersion)
+    const checksum = await digest(bytes)
+    const now = modifiedAtAfter(previous)
+    const rowId = id("row")
+    this.state.storage.sql.exec(
+      `INSERT INTO ${TABLE}
+        (row_id,path,parent_path,name,type,mime_type,size,created_at,modified_at,
+         attachment_id,content_version,content_key,sha256,origin,content_ownership,
+         understanding_status,write_state,current)
+       VALUES (?,?,?,?, 'file', ?, ?, ?, ?, ?, ?, ?, ?, ?, 'workspace_owned',
+         'not_requested', 'writing', 0)`,
+      rowId, target, parentPath(target), basename(target), mediaType, bytes.byteLength,
+      previous?.createdAt ?? now, now, attachmentId, contentVersion, contentKey,
+      checksum, origin,
+    )
+    const cached = { attachmentId, contentVersion, size: bytes.byteLength }
+    await this.cacheBytes(cached, bytes)
+    try {
+      await this.bucket.put(contentKey, bytes, {
+        httpMetadata: { contentType: mediaType },
+        customMetadata: { sha256: checksum, attachmentId, contentVersion },
+      })
+      this.state.storage.transactionSync(() => {
+        this.state.storage.sql.exec(
+          `UPDATE ${TABLE} SET current = 0 WHERE path = ? AND current = 1`,
+          target,
+        )
+        this.state.storage.sql.exec(
+          `UPDATE ${TABLE} SET write_state = 'ready', current = 1 WHERE row_id = ?`,
+          rowId,
+        )
+      })
+      await this.removeCached(previous ? this.cachedVersion(previous) : null)
+    } catch (error) {
+      this.state.storage.sql.exec(`DELETE FROM ${TABLE} WHERE row_id = ?`, rowId)
+      await this.removeCached(cached)
+      throw error
+    }
+  }
+
+  async registerExistingContents(
+    input: RegisterExistingContentsInput,
+  ): Promise<SpaceFileInspection[] | null> {
+    const parent = writableFilePath(input.parent)
+    if (input.maxTotalBytes !== undefined &&
+      (!Number.isSafeInteger(input.maxTotalBytes) || input.maxTotalBytes < 0)) return null
+    if (input.files.some(({ name }) =>
+      !name || name.includes("/") || name.includes("\\"))) return null
+    if (new Set(input.files.map(({ contentKey }) => contentKey)).size !== input.files.length) return null
+    const checked = await Promise.all(input.files.map(async (file) => ({
+      file,
+      object: await this.bucket.head(file.contentKey),
+    })))
+    let totalBytes = 0
+    for (const { file, object } of checked) {
+      const sha256 = object?.customMetadata?.sha256
+      if (!object || !sha256 || object.httpMetadata?.contentType !== file.mediaType ||
+        object.customMetadata?.owner !== input.ownerId ||
+        (file.origin === "user_upload" &&
+          object.customMetadata?.name !== encodeURIComponent(file.name))) return null
+      totalBytes += object.size
+    }
+    if (input.maxTotalBytes !== undefined && totalBytes > input.maxTotalBytes) return null
+    const paths: string[] = []
+    const pending: Array<{
+      path: string
+      attachmentId: string
+      contentVersion: string
+      file: RegisterExistingContentsInput["files"][number]
+      object: R2Object
+    }> = []
+    for (const { file, object } of checked) {
+      const existing = this.state.storage.sql.exec<FileRow>(`
+        SELECT ${FILE_ROW_COLUMNS}
+        FROM ${TABLE}
+        WHERE content_key = ? AND current = 1 AND write_state = 'ready'
+        LIMIT 1
+      `, file.contentKey).toArray()[0]
+      if (existing) {
+        paths.push(existing.path)
+        continue
+      }
+      const attachmentId = id("att")
+      const contentVersion = id("ver")
+      const path = `${parent}/${attachmentId}/${file.name}`
+      await this.ensureParent(path)
+      paths.push(path)
+      pending.push({
+        path,
+        attachmentId,
+        contentVersion,
+        file,
+        object: object!,
+      })
+    }
+    const now = Date.now()
+    this.state.storage.transactionSync(() => {
+      for (const registration of pending) {
+        this.state.storage.sql.exec(
+          `INSERT INTO ${TABLE}
+            (row_id,path,parent_path,name,type,mime_type,size,created_at,modified_at,
+             attachment_id,content_version,content_key,sha256,origin,content_ownership,
+             understanding_status,write_state,current)
+           VALUES (?,?,?,?, 'file', ?, ?, ?, ?, ?, ?, ?, ?, ?, 'referenced',
+             'pending', 'ready', 1)`,
+          id("row"),
+          registration.path,
+          parentPath(registration.path),
+          registration.file.name,
+          registration.file.mediaType,
+          registration.object.size,
+          now,
+          now,
+          registration.attachmentId,
+          registration.contentVersion,
+          registration.file.contentKey,
+          registration.object.customMetadata!.sha256!,
+          registration.file.origin,
+        )
+      }
+    })
+    return paths.map((path) => this.info(this.row(path)!))
+  }
+
+  async inspectFile(path: string): Promise<SpaceFileInspection | null> {
+    const row = this.row(path)
+    return row ? this.info(row) : null
+  }
+
+  async setUnderstanding(
+    path: string,
+    contentVersion: string,
+    status: SpaceUnderstandingStatus,
+    evidence?: SpaceFileEvidence,
+  ): Promise<SpaceFileInspection> {
+    const target = normalizeInternalPath(path)
+    const changed = this.state.storage.sql.exec<{ rowId: string }>(
+      `UPDATE ${TABLE}
+       SET understanding_status = ?, evidence_json = ?
+       WHERE path = ? AND content_version = ? AND current = 1 AND type = 'file'
+       RETURNING row_id AS rowId`,
+      status, evidence ? JSON.stringify(evidence) : null, target, contentVersion,
+    ).toArray()[0]
+    if (!changed) throw new Error("Workspace file not found")
+    return this.info(this.row(target)!)
+  }
+
+  beginUnderstanding(path: string, contentVersion: string, refresh = false): boolean {
+    return this.state.storage.sql.exec<{ rowId: string }>(
+      `UPDATE ${TABLE}
+       SET understanding_status = 'pending',
+         understanding_attempts = understanding_attempts + CASE WHEN ? = 1 THEN 0 ELSE 1 END,
+         evidence_json = NULL
+       WHERE path = ? AND content_version = ? AND current = 1 AND type = 'file'
+         AND ((? = 1 AND understanding_status IN ('ready', 'pending', 'failed'))
+           OR (? = 0 AND understanding_attempts < 2
+             AND understanding_status IN ('not_requested', 'pending', 'failed')))
+       RETURNING row_id AS rowId`,
+      refresh ? 1 : 0, normalizeInternalPath(path), contentVersion,
+      refresh ? 1 : 0, refresh ? 1 : 0,
+    ).toArray().length === 1
+  }
+
+  async readFile(path: string): Promise<string | null> {
+    const bytes = await this.readFileBytes(path)
+    return bytes ? decoder.decode(bytes) : null
+  }
+
+  async readFileBytes(path: string): Promise<Uint8Array | null> {
+    const row = this.row(path)
+    if (!row || row.type !== "file") return null
+    if (row.size > WORKSPACE_BUFFERED_READ_MAX_BYTES) {
+      throw new Error(`Workspace file exceeds the 50 MiB buffered read limit: ${row.path}`)
+    }
+    if (row.inlineContent) return new Uint8Array(row.inlineContent)
+    if (!row.contentKey) return null
+    const cached = await this.cachedBytes(row)
+    if (cached) return cached
+    const object = await this.bucket.get(row.contentKey)
+    if (!object) {
+      await this.removeCached(this.cachedVersion(row))
+      throw new Error(`Workspace content is missing: ${row.path}`)
+    }
+    const bytes = new Uint8Array(await object.arrayBuffer())
+    const version = this.cachedVersion(row)
+    if (version) await this.cacheBytes(version, bytes)
+    return bytes
+  }
+
+  async openFileStream(path: string): Promise<WorkspaceFileStream | null> {
+    const row = this.row(path)
+    if (!row || row.type !== "file") return null
+    if (!row.attachmentId || !row.contentVersion || !row.contentKey) return null
+    const cached = await this.cachedBytes(row)
+    if (cached) {
+      console.info("deployment_asset_source", { source: "sqlite_cache" })
+      return {
+        body: new Blob([cached]).stream(),
+        size: row.size,
+        mediaType: row.mimeType,
+        contentVersion: row.contentVersion,
+      }
+    }
+    const object = await this.bucket.get(row.contentKey)
+    if (!object) {
+      await this.removeCached(this.cachedVersion(row))
+      throw new Error(`Workspace content is missing: ${row.path}`)
+    }
+    console.info("deployment_asset_source", { source: "r2_stream" })
+    return {
+      body: object.body,
+      size: row.size,
+      mediaType: row.mimeType,
+      contentVersion: row.contentVersion,
+    }
+  }
+
+  async writeFile(path: string, content: string, mediaType?: string): Promise<void> {
+    await this.commitBytes(path, encoder.encode(content), mediaType ?? inferMimeType(path), "agent")
+  }
+
+  async writeFileBytes(path: string, content: Uint8Array | ArrayBuffer, mediaType?: string): Promise<void> {
+    await this.commitBytes(path, toBytes(content), mediaType ?? inferMimeType(path), "agent")
+  }
+
+  async writeFileStream(
+    path: string,
+    stream: ReadableStream<Uint8Array>,
+    mediaType: string,
+    origin: SpaceFileOrigin = "agent",
+    contentLength?: number,
+  ): Promise<number> {
+    const target = writableFilePath(path)
+    await this.ensureParent(target)
+    const previous = this.row(target)
+    if (previous?.type === "directory") throw new Error(`EISDIR: ${target} is a directory`)
+    const attachmentId = previous?.type === "file" && previous.attachmentId
+      ? previous.attachmentId
+      : id("att")
+    const contentVersion = id("ver")
+    const contentKey = this.contentKey(attachmentId, contentVersion)
+    const rowId = id("row")
+    const now = modifiedAtAfter(previous)
+    this.state.storage.sql.exec(
+      `INSERT INTO ${TABLE}
+        (row_id,path,parent_path,name,type,mime_type,size,created_at,modified_at,
+         attachment_id,content_version,content_key,origin,content_ownership,
+         understanding_status,write_state,current)
+       VALUES (?,?,?,?, 'file', ?, 0, ?, ?, ?, ?, ?, ?, 'workspace_owned',
+         'not_requested', 'writing', 0)`,
+      rowId, target, parentPath(target), basename(target), mediaType,
+      previous?.createdAt ?? now, now, attachmentId, contentVersion, contentKey, origin,
+    )
+    let size = 0
+    const counted = stream.pipeThrough(new TransformStream<Uint8Array, Uint8Array>({
+      transform(chunk, controller) {
+        size += chunk.byteLength
+        if (contentLength !== undefined && contentLength <= FILE_CACHE_MAX_ENTRY_BYTES &&
+          size > FILE_CACHE_MAX_ENTRY_BYTES) {
+          throw new Error("Stream exceeded the Workspace file cache collection limit")
+        }
+        controller.enqueue(chunk)
+      },
+    }))
+    const [uploadBody, localBody] = counted.tee()
+    let digesting: Promise<ArrayBuffer>
+    let caching = Promise.resolve()
+    if (contentLength !== undefined && contentLength <= FILE_CACHE_MAX_ENTRY_BYTES) {
+      const collected = new Response(localBody).arrayBuffer()
+        .then((body) => new Uint8Array(body))
+      digesting = collected.then((bytes) => crypto.subtle.digest("SHA-256", bytes))
+      caching = collected.then((bytes) => this.cacheBytes(
+        { attachmentId, contentVersion, size: bytes.byteLength },
+        bytes,
+      ))
+    } else {
+      const hash = createHash("sha256")
+      digesting = localBody.pipeTo(new WritableStream<Uint8Array>({
+        write(chunk) { hash.update(chunk) },
+      })).then(() => Uint8Array.from(hash.digest()).buffer)
+    }
+    try {
+      const [, hash] = await Promise.all([
+        putStream(this.bucket, contentKey, uploadBody, mediaType),
+        digesting,
+        caching,
+      ])
+      const sha256 = [...new Uint8Array(hash)]
+        .map((part) => part.toString(16).padStart(2, "0"))
+        .join("")
+      this.state.storage.transactionSync(() => {
+        this.state.storage.sql.exec(
+          `UPDATE ${TABLE} SET current = 0 WHERE path = ? AND current = 1`,
+          target,
+        )
+        this.state.storage.sql.exec(
+          `UPDATE ${TABLE}
+           SET size = ?, sha256 = ?, write_state = 'ready', current = 1
+           WHERE row_id = ?`,
+          size, sha256, rowId,
+        )
+      })
+      await this.removeCached(previous ? this.cachedVersion(previous) : null)
+      return size
+    } catch (error) {
+      this.state.storage.sql.exec(`DELETE FROM ${TABLE} WHERE row_id = ?`, rowId)
+      await this.removeCached({ attachmentId, contentVersion, size })
+      throw error
+    }
+  }
+
+  async appendFile(path: string, content: string | Uint8Array): Promise<void> {
+    const current = await this.readFileBytes(path) ?? new Uint8Array()
+    const appended = typeof content === "string" ? encoder.encode(content) : content
+    const bytes = new Uint8Array(current.byteLength + appended.byteLength)
+    bytes.set(current)
+    bytes.set(appended, current.byteLength)
+    await this.commitBytes(path, bytes, this.row(path)?.mimeType ?? inferMimeType(path), "agent")
+  }
+
+  async exists(path: string): Promise<boolean> {
+    return this.row(path) !== null
+  }
+
+  async stat(path: string): Promise<SpaceFileInspection | null> {
+    const row = this.row(path)
+    return row ? this.info(row) : null
+  }
+
+  async lstat(path: string): Promise<SpaceFileInspection | null> {
+    return this.stat(path)
+  }
+
+  async mkdir(path: string, options?: { recursive?: boolean }): Promise<void> {
+    const target = normalizeInternalPath(path)
+    if (target === "/" || this.row(target)) return
+    const parent = parentPath(target)
+    if (!this.row(parent)) {
+      if (!options?.recursive) throw new Error(`ENOENT: ${parent}`)
+      await this.mkdir(parent, { recursive: true })
+    }
+    const now = Date.now()
+    this.state.storage.sql.exec(
+      `INSERT INTO ${TABLE}
+        (row_id,path,parent_path,name,type,mime_type,size,created_at,modified_at,write_state,current)
+       VALUES (?,?,?,?, 'directory', 'inode/directory', 0, ?, ?, 'ready', 1)`,
+      id("row"), target, parent, basename(target), now, now,
+    )
+  }
+
+  async readDir(dir = "/", opts?: { limit?: number; offset?: number }): Promise<SpaceFileInspection[]> {
+    const target = normalizeInternalPath(dir)
+    const rows = this.state.storage.sql.exec<FileRow>(`
+      SELECT ${FILE_ROW_COLUMNS}
+      FROM ${TABLE}
+      WHERE parent_path = ? AND path <> ? AND current = 1 AND write_state = 'ready'
+      ORDER BY name LIMIT ? OFFSET ?
+    `, target, target, opts?.limit ?? 100_000, opts?.offset ?? 0).toArray()
+    return rows.map((row) => this.info(row))
+  }
+
+  async rm(path: string, opts?: { recursive?: boolean; force?: boolean }): Promise<void> {
+    const target = writableFilePath(path)
+    const row = this.row(target)
+    if (!row) {
+      if (opts?.force) return
+      throw new Error(`ENOENT: ${target}`)
+    }
+    if (row.type === "directory" && !opts?.recursive && (await this.readDir(target)).length > 0) {
+      throw new Error(`ENOTEMPTY: ${target}`)
+    }
+    const cachedFiles = this.state.storage.sql.exec<FileRow>(`
+      SELECT ${FILE_ROW_COLUMNS}
+      FROM ${TABLE}
+      WHERE current = 1 AND type = 'file'
+        AND (path = ? OR substr(path, 1, ?) = ?)
+    `, target, target.length + 1, `${target}/`).toArray()
+    this.state.storage.sql.exec(
+      `UPDATE ${TABLE} SET current = 0
+       WHERE current = 1 AND (path = ? OR substr(path, 1, ?) = ?)`,
+      target, target.length + 1, `${target}/`,
+    )
+    await Promise.all(cachedFiles.map((file) => this.removeCached(this.cachedVersion(file))))
+  }
+
+  async cp(src: string, dest: string, opts?: { recursive?: boolean }): Promise<void> {
+    const from = normalizeInternalPath(src)
+    const to = writableFilePath(dest)
+    const source = this.row(from)
+    if (!source) throw new Error(`ENOENT: ${from}`)
+    if (source.type === "directory" && !opts?.recursive) throw new Error("A directory copy requires recursive: true")
+    const rows = source.type === "directory"
+      ? this.state.storage.sql.exec<FileRow>(`
+          SELECT ${FILE_ROW_COLUMNS}
+          FROM ${TABLE} WHERE current = 1 AND write_state = 'ready'
+            AND (path = ? OR substr(path, 1, ?) = ?)
+          ORDER BY length(path)
+        `, from, from.length + 1, `${from}/`).toArray()
+      : [source]
+    await this.rm(to, { recursive: true, force: true })
+    for (const row of rows) {
+      const path = `${to}${row.path.slice(from.length)}`
+      if (row.type === "directory") {
+        await this.mkdir(path, { recursive: true })
+        continue
+      }
+      if (row.type === "symlink") {
+        await this.symlink(row.target ?? "", path)
+        continue
+      }
+      await this.ensureParent(path)
+      const now = Date.now()
+      this.state.storage.sql.exec(
+        `INSERT INTO ${TABLE}
+          (row_id,path,parent_path,name,type,mime_type,size,created_at,modified_at,
+           attachment_id,content_version,content_key,sha256,origin,content_ownership,
+           understanding_status,evidence_json,write_state,current)
+         VALUES (?,?,?,?, 'file', ?, ?, ?, ?, ?, ?, ?, ?, ?, 'referenced', ?, ?, 'ready', 1)`,
+        id("row"), path, parentPath(path), basename(path), row.mimeType, row.size, now, now,
+        id("att"), id("ver"), row.contentKey, row.sha256, row.origin,
+        row.understandingStatus, row.evidenceJson,
+      )
+    }
+  }
+
+  async mv(src: string, dest: string): Promise<void> {
+    const from = writableFilePath(src)
+    const to = writableFilePath(dest)
+    if (!this.row(from)) throw new Error(`ENOENT: ${from}`)
+    await this.ensureParent(to)
+    await this.rm(to, { recursive: true, force: true })
+    this.state.storage.sql.exec(
+      `UPDATE ${TABLE}
+       SET path = ? || substr(path, ?),
+           parent_path = CASE
+             WHEN parent_path = ? THEN ?
+             ELSE ? || substr(parent_path, ?)
+           END,
+           name = CASE WHEN path = ? THEN ? ELSE name END,
+           modified_at = ?
+       WHERE path = ? OR substr(path, 1, ?) = ?`,
+      to, from.length + 1, parentPath(from), parentPath(to), to, from.length + 1,
+      from, basename(to), Date.now(), from, from.length + 1, `${from}/`,
+    )
+  }
+
+  async symlink(target: string, linkPath: string): Promise<void> {
+    const path = writableFilePath(linkPath)
+    await this.ensureParent(path)
+    await this.rm(path, { force: true, recursive: true })
+    const now = Date.now()
+    this.state.storage.sql.exec(
+      `INSERT INTO ${TABLE}
+        (row_id,path,parent_path,name,type,mime_type,size,target,created_at,modified_at,write_state,current)
+       VALUES (?,?,?,?, 'symlink', 'inode/symlink', 0, ?, ?, ?, 'ready', 1)`,
+      id("row"), path, parentPath(path), basename(path), target, now, now,
+    )
+  }
+
+  async readlink(path: string): Promise<string> {
+    const row = this.row(path)
+    if (!row || row.type !== "symlink" || !row.target) throw new Error(`EINVAL: ${path}`)
+    return row.target
+  }
+
+  async glob(pattern: string): Promise<SpaceFileInspection[]> {
+    const matcher = globRegex(pattern)
+    const rows = this.state.storage.sql.exec<FileRow>(`
+      SELECT ${FILE_ROW_COLUMNS}
+      FROM ${TABLE} WHERE current = 1 AND write_state = 'ready'
+    `).toArray()
+    return rows.filter((row) => matcher.test(row.path)).map((row) => this.info(row))
+  }
+
+  async getWorkspaceInfo(): Promise<{ fileCount: number; directoryCount: number; totalBytes: number; r2FileCount: number }> {
+    const result = this.state.storage.sql.exec<{
+      fileCount: number
+      directoryCount: number
+      totalBytes: number
+    }>(`
+      SELECT
+        SUM(CASE WHEN type = 'file' THEN 1 ELSE 0 END) AS fileCount,
+        SUM(CASE WHEN type = 'directory' THEN 1 ELSE 0 END) AS directoryCount,
+        SUM(CASE WHEN type = 'file' THEN size ELSE 0 END) AS totalBytes
+      FROM ${TABLE} WHERE current = 1 AND write_state = 'ready'
+    `).one()
+    return { ...result, r2FileCount: result.fileCount }
+  }
+
+  async _getAllPaths(): Promise<string[]> {
+    return this.state.storage.sql.exec<{ path: string }>(
+      `SELECT path FROM ${TABLE} WHERE current = 1 AND write_state = 'ready' ORDER BY path`,
+    ).toArray().map(({ path }) => path)
+  }
+
+  async _updateModifiedAt(path: string, mtime: Date): Promise<void> {
+    this.state.storage.sql.exec(
+      `UPDATE ${TABLE} SET modified_at = ? WHERE path = ? AND current = 1`,
+      mtime.getTime(), normalizeInternalPath(path),
+    )
+  }
+}