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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/space",
-  "version": "0.2.0-alpha.15",
+  "version": "0.2.0-alpha.17",
   "type": "module",
   "files": [
     "src",
@@ -14,12 +14,13 @@
   },
   "dependencies": {
     "@cloudflare/shell": "0.4.3",
-    "@cloudflare/worker-bundler": "0.0.4",
+    "@cloudflare/worker-bundler": "0.2.3",
     "isomorphic-git": "1.38.6"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.20.1",
     "@cloudflare/workers-types": "^4.20251008.0",
+    "@types/node": "26.1.2",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"
   },

package/src/env.ts

@@ -14,6 +14,7 @@ export interface SpaceEnv {
 
   /** Large-file spill and Space blob storage. */
   WORKSPACE_R2?: R2Bucket;
+  WORKSPACE_R2_PUBLIC_ORIGIN?: string;
 
   /**
    * Cloudflare Artifacts binding. Optional: Artifacts is still a private beta,

package/src/index.ts

@@ -1,5 +1,16 @@
 // ── Durable Object classes ────────────────────────────────────────
 export { SpaceDO } from "./space/durable-object";
+export type {
+  RegisterExistingContentsInput,
+  SpaceFileEvidence,
+  SpaceFileInspection,
+  SpaceFileOrigin,
+  SpaceUnderstandingStatus,
+} from "./space/space-files";
+export {
+  normalizeSpaceFileEvidence,
+  SPACE_FILE_EVIDENCE_JSON_SCHEMA,
+} from "./space/space-files";
 
 // ── RPC surface ───────────────────────────────────────────────────
 export type {
@@ -33,6 +44,7 @@ export type {
 
 // ── Preview hardening ─────────────────────────────────────────────
 export { stripPreviewSecurityHeaders, STRIPPED_PREVIEW_HEADERS } from "./space/preview-headers";
+export { handleWorkspaceSiteRequest } from "./space/workspace-site";
 
 // ── Environment bindings type ─────────────────────────────────────
 export type { Env, SpaceEnv } from "./env";

package/src/space/artifacts-fs.ts

@@ -138,6 +138,13 @@ export class ArtifactsFileSystem implements FileSystem {
     return this.materializePromise
   }
 
+  async materializeForMigration(): Promise<void> {
+    await this.ready()
+    if (!this.readyPromise) await this.ready()
+    if (!this.readyPromise) throw new Error("Artifacts base is unavailable for migration")
+    await this.whenFullyMaterialized()
+  }
+
   /**
    * Ensure a single path's content is present in the overlay (hydrating it from
    * the base on demand). Lets callers that read through the underlying Workspace

package/src/space/deploy-engine.ts

@@ -30,6 +30,13 @@ export interface DeployContext {
   fs: FileSystem
   assetBucket?: R2Bucket
   assetPrefix?: string
+  defer?: (promise: Promise<unknown>) => void
+  openFileStream?: (path: string) => Promise<{
+    body: ReadableStream<Uint8Array>
+    size: number
+    mediaType: string
+    contentVersion: string
+  } | null>
 }
 
 export interface DeploymentBundle {
@@ -73,7 +80,7 @@ export interface DeploymentAsset {
 
 type AssetWriter = (
   asset: Omit<DeploymentAsset, "etag">,
-  bytes: Uint8Array,
+  body: ReadableStream<Uint8Array>,
 ) => Promise<string>
 
 const DEFAULT_COMPATIBILITY_DATE = "2025-04-01"
@@ -152,7 +159,11 @@ async function readBranchFiles(
     throw new Error(`Revision "${revision}" was not found on branch "${branch}"`)
   }
 
-  await ctx.git.checkout({ ref: revision ? commitHash : branch, force: true })
+  const branchState = await ctx.git.branch({ list: true })
+  const currentBranch = "current" in branchState ? branchState.current : null
+  if (revision || currentBranch !== branch) {
+    await ctx.git.checkout({ ref: revision ? commitHash : branch, force: true })
+  }
 
   try {
     const entries: Array<{ sourcePath: string; path: string; size: number }> = []
@@ -185,6 +196,7 @@ async function readBranchFiles(
 
     const files: Record<string, string> = { ...configFiles }
     const assets: DeploymentAsset[] = []
+    const assetWrites: Array<Promise<DeploymentAsset>> = []
     for (const entry of entries) {
       if (isAssetPath(entry.path, assetsDirectory)) {
         if (entry.size > MAX_STATIC_ASSET_BYTES) {
@@ -192,17 +204,29 @@ async function readBranchFiles(
             `Static asset "${entry.path}" is ${entry.size} bytes; the limit is ${MAX_STATIC_ASSET_BYTES} bytes`,
           )
         }
-        const bytes = await ctx.fs.readFileBytes(entry.sourcePath)
-        const asset: Omit<DeploymentAsset, "etag"> = {
-          path: toAssetPath(entry.path, assetsDirectory!),
-          sourcePath: entry.sourcePath,
-          contentType: inferContentType(entry.path),
-          size: bytes.byteLength,
-        }
-        const etag = writeAsset
-          ? await writeAsset(asset, bytes)
-          : await computeAssetEtag(bytes)
-        assets.push({ ...asset, etag })
+        assetWrites.push((async () => {
+          const asset: Omit<DeploymentAsset, "etag"> = {
+            path: toAssetPath(entry.path, assetsDirectory!),
+            sourcePath: entry.sourcePath,
+            contentType: inferContentType(entry.path),
+            size: entry.size,
+          }
+          const bytes = writeAsset ? null : await ctx.fs.readFileBytes(entry.sourcePath)
+          let stream: ReadableStream<Uint8Array> | null = null
+          if (writeAsset) {
+            if (ctx.openFileStream) {
+              const opened = await ctx.openFileStream(entry.sourcePath)
+              if (!opened) throw new Error(`Workspace file is missing: ${entry.sourcePath}`)
+              stream = opened.body
+            } else {
+              stream = new Blob([await ctx.fs.readFileBytes(entry.sourcePath)]).stream()
+            }
+          }
+          const etag = writeAsset
+            ? await writeAsset(asset, stream!)
+            : await computeAssetEtag(bytes!)
+          return { ...asset, etag }
+        })())
         continue
       }
 
@@ -212,6 +236,13 @@ async function readBranchFiles(
         files[entry.path] = await ctx.fs.readFile(entry.sourcePath)
       }
     }
+    const assetResults = await Promise.allSettled(assetWrites)
+    const failedAsset = assetResults.find(
+      (result): result is PromiseRejectedResult => result.status === "rejected",
+    )
+    if (failedAsset) throw failedAsset.reason
+    assets.push(...assetResults.map((result) =>
+      (result as PromiseFulfilledResult<DeploymentAsset>).value))
 
     if (!hasWrangler(configFiles) && assetsDirectory !== null) {
       files["wrangler.json"] = JSON.stringify({
@@ -260,12 +291,12 @@ async function deployBranch(
       branch,
       body.appRoot,
       body.revision,
-      async (asset, bytes) => {
+      async (asset, body) => {
         if (!ctx.assetBucket || !assetRoot) {
           throw new Error("Static preview deployment requires the WORKSPACE_R2 binding")
         }
         const key = `${assetRoot}${asset.path}`
-        const uploaded = await ctx.assetBucket.put(key, bytes, {
+        const uploaded = await ctx.assetBucket.put(key, body, {
           ...(asset.contentType ? { httpMetadata: { contentType: asset.contentType } } : {}),
         })
         ctx.sql.exec(
@@ -341,13 +372,15 @@ async function deployBranch(
     })
   }
   if (oldAssetDeploymentId && oldAssetDeploymentId !== assetDeploymentId) {
-    await discardAssetDeployment(
+    const cleanup = discardAssetDeployment(
       ctx,
       oldAssetDeploymentId,
       ctx.assetPrefix ? `${ctx.assetPrefix}/deployments/${oldAssetDeploymentId}` : undefined,
     ).catch((error) => {
       console.warn("Failed to clean replaced static preview deployment", error)
     })
+    if (ctx.defer) ctx.defer(cleanup)
+    else await cleanup
   }
 
   return jsonResponse({
@@ -389,7 +422,7 @@ export async function buildBranchDeployment(
       size: bytes.byteLength,
     }
     const etag = writeAsset
-      ? await writeAsset(asset, bytes)
+      ? await writeAsset(asset, new Blob([bytes]).stream())
       : await computeAssetEtag(bytes)
     assets.push({ ...asset, etag })
   }

package/src/space/durable-object.ts

@@ -15,7 +15,12 @@ import {
   buildInspectorWrapperSource,
   VIBE_APP_MODULE,
 } from "./inspector-wrapper"
-import { ArtifactsBackend, resolveSpaceFsBackendMode, SqlBackend, spaceR2Prefix, type SpaceFsBackend } from "./fs-backend"
+import {
+  migrateArtifactsBackend,
+  SqlBackend,
+  spaceR2Prefix,
+  type SpaceFsBackend,
+} from "./fs-backend"
 import { createGitFs, stageWorkdir } from "./git-objects"
 import * as git from "isomorphic-git"
 import {
@@ -102,6 +107,10 @@ interface DeploymentRow {
 // file listing: git's object store and the ArtifactsFileSystem bookkeeping dir.
 const isReservedPath = isReservedSpacePath
 
+function isMissingFileError(error: unknown): boolean {
+  return error instanceof Error && /ENOENT/u.test(error.message)
+}
+
 // ─── SpaceDO ────────────────────────────────────────────────────────────────
 // Agent space Durable Object backed by @cloudflare/shell.
 //
@@ -195,11 +204,15 @@ export class SpaceDO extends DurableObject<Env>
   }
 
   private async initializeBackend(): Promise<void> {
-    const mode = await resolveSpaceFsBackendMode(this.ctx.storage, this.env)
     const repoName = this.spaceName
-    this.backend = mode === "artifacts"
-      ? new ArtifactsBackend(this.ctx, this.env, repoName)
-      : new SqlBackend(this.ctx, repoName, this.env.WORKSPACE_R2)
+    const sql = new SqlBackend(
+      this.ctx,
+      repoName,
+      this.env.WORKSPACE_R2,
+      this.env.WORKSPACE_R2_PUBLIC_ORIGIN,
+    )
+    await migrateArtifactsBackend(this.ctx, this.env, repoName, sql.workspace)
+    this.backend = sql
   }
 
   private get spaceName(): string {
@@ -214,6 +227,7 @@ export class SpaceDO extends DurableObject<Env>
   }
 
   private async statInfo(path: string): Promise<SpaceFileInfo | null> {
+    if (this.backend instanceof SqlBackend) return this.backend.workspace.stat(path)
     try {
       return toFileInfo(path, await this.overlay.stat(path))
     } catch {
@@ -394,16 +408,12 @@ export class SpaceDO extends DurableObject<Env>
     if (!message) throw new Error("A Space commit needs a reason")
     await this.materializeAll()
     await this.flushCheckpoint()
-    await stageWorkdir(this.fs, isUnversionedSpacePath)
+    const staged = await stageWorkdir(this.fs, isUnversionedSpacePath, prefix)
 
     const gitFs = this.gitFs()
     const head = await this.headOid()
     // Nothing moved between HEAD and the index. An empty commit would appear in
     // the person's version list as a change they never made.
-    const matrix = await git.statusMatrix({ fs: gitFs, dir: "/" })
-    const staged = matrix.some(([filepath, headStatus, , stageStatus]) =>
-      !isUnversionedSpacePath(`/${filepath}`) && headStatus !== stageStatus
-    )
     if (!staged) {
       if (!head) return { revision: null, treeHash: null, changed: false }
       return {
@@ -589,6 +599,11 @@ export class SpaceDO extends DurableObject<Env>
           // Already gone.
         }
       }
+      try {
+        if (this.backend instanceof SqlBackend) await this.backend.workspace.clearCache()
+      } catch (error) {
+        console.warn("Workspace file cache cleanup failed during Space destruction", error)
+      }
       await this.deleteSpilledObjects()
       await this.ctx.storage.deleteAll()
       this.initializationPromise = null
@@ -609,14 +624,18 @@ export class SpaceDO extends DurableObject<Env>
   private async deleteSpilledObjects(): Promise<void> {
     const bucket = this.env.WORKSPACE_R2
     if (!bucket) return
-    const prefix = `${spaceR2Prefix(this.spaceName)}/`
-    let cursor: string | undefined
-    do {
-      const page = await bucket.list({ prefix, limit: 1000, ...(cursor ? { cursor } : {}) })
-      const keys = page.objects.map((object) => object.key)
-      if (keys.length > 0) await bucket.delete(keys)
-      cursor = page.truncated ? page.cursor : undefined
-    } while (cursor)
+    for (const prefix of [
+      `${spaceR2Prefix(this.spaceName)}/`,
+      `spaces/v2/${encodeURIComponent(this.spaceName)}/`,
+    ]) {
+      let cursor: string | undefined
+      do {
+        const page = await bucket.list({ prefix, limit: 1000, ...(cursor ? { cursor } : {}) })
+        const keys = page.objects.map((object) => object.key)
+        if (keys.length > 0) await bucket.delete(keys)
+        cursor = page.truncated ? page.cursor : undefined
+      } while (cursor)
+    }
   }
 
   // ── Filesystem RPC methods ──────────────────────────────────────
@@ -638,8 +657,9 @@ export class SpaceDO extends DurableObject<Env>
     let content: string
     try {
       content = await this.fs.readFile(target)
-    } catch {
-      return null
+    } catch (error) {
+      if (isMissingFileError(error)) return null
+      throw error
     }
 
     if (opts?.offset !== undefined || opts?.limit !== undefined) {
@@ -713,6 +733,8 @@ export class SpaceDO extends DurableObject<Env>
         target,
         counted,
         options?.mediaType ?? "application/octet-stream",
+        options?.origin,
+        expected,
       )
       return { path: target, bytes }
     })
@@ -798,6 +820,11 @@ export class SpaceDO extends DurableObject<Env>
    */
   async glob(pattern: string): Promise<SpaceFileInfo[]> {
     await this.ensureInit()
+    if (this.backend instanceof SqlBackend) {
+      return (await this.backend.workspace.glob(normalizeSpacePattern(pattern)))
+        .filter((file) => file.type === "file" && !isReservedPath(file.path))
+        .sort((a, b) => b.updatedAt - a.updatedAt)
+    }
     await this.materializeAll()
     const files = await globInfos(this.overlay, normalizeSpacePattern(pattern))
     return files
@@ -859,6 +886,7 @@ export class SpaceDO extends DurableObject<Env>
     await this.ensureInit()
     const target = normalizeSpacePath(path)
     await this.hydrate(target)
+    if (this.backend instanceof SqlBackend) return this.backend.workspace.lstat(target)
     try {
       return toFileInfo(target, await this.overlay.lstat(target))
     } catch {
@@ -874,13 +902,19 @@ export class SpaceDO extends DurableObject<Env>
     // throws ENOENT for a missing path, but this RPC's contract returns null.
     try {
       return await this.fs.readFileBytes(target)
-    } catch {
-      return null
+    } catch (error) {
+      if (isMissingFileError(error)) return null
+      throw error
     }
   }
 
   async readDir(dir?: string, opts?: { limit?: number; offset?: number }): Promise<SpaceFileInfo[]> {
     await this.ensureInit()
+    if (this.backend instanceof SqlBackend) {
+      const base = dir === undefined ? "/" : normalizeSpacePath(dir)
+      return (await this.backend.workspace.readDir(base, opts))
+        .filter((entry) => !isReservedPath(entry.path))
+    }
     await this.materializeAll()
     const base = dir === undefined ? "/" : normalizeSpacePath(dir)
     const entries = await readDirInfos(this.overlay, base, opts)
@@ -892,6 +926,39 @@ export class SpaceDO extends DurableObject<Env>
     await this.fs.mkdir(normalizeWritableSpacePath(path), opts)
   }
 
+  async registerExistingContents(input: import("./space-files").RegisterExistingContentsInput) {
+    await this.ensureInit()
+    if (!(this.backend instanceof SqlBackend)) {
+      throw new Error("Existing content registration requires the SQL Space backend")
+    }
+    return this.backend.workspace.registerExistingContents(input)
+  }
+
+  async inspectFile(path: string) {
+    await this.ensureInit()
+    if (!(this.backend instanceof SqlBackend)) return this.stat(path)
+    return this.backend.workspace.inspectFile(normalizeSpacePath(path))
+  }
+
+  async setFileUnderstanding(
+    path: string,
+    contentVersion: string,
+    status: import("./space-files").SpaceUnderstandingStatus,
+    evidence?: import("./space-files").SpaceFileEvidence,
+  ) {
+    await this.ensureInit()
+    if (!(this.backend instanceof SqlBackend)) {
+      throw new Error("File Understanding requires the SQL Space backend")
+    }
+    return this.backend.workspace.setUnderstanding(path, contentVersion, status, evidence)
+  }
+
+  async beginFileUnderstanding(path: string, contentVersion: string, refresh?: boolean): Promise<boolean> {
+    await this.ensureInit()
+    if (!(this.backend instanceof SqlBackend)) return false
+    return this.backend.workspace.beginUnderstanding(path, contentVersion, refresh)
+  }
+
   async rm(path: string, opts?: { recursive?: boolean; force?: boolean }): Promise<void> {
     await this.ensureInit()
     // Route through the overlay-aware FS so base files are tombstoned.
@@ -1130,6 +1197,10 @@ export class SpaceDO extends DurableObject<Env>
         fs: this.fs,
         assetBucket: this.env.WORKSPACE_R2,
         assetPrefix: spaceR2Prefix(this.spaceName),
+        defer: (promise) => this.ctx.waitUntil(promise),
+        openFileStream: (path) => this.backend instanceof SqlBackend
+          ? this.backend.workspace.openFileStream(path)
+          : Promise.resolve(null),
       }
       const res = await handleDeployCommand(ctx, "deploy", fakeRequest)
       const data = await res.json() as Record<string, unknown>

package/src/space/file-content-cache.ts

@@ -0,0 +1,194 @@
+export type CachedFileVersion = {
+  attachmentId: string
+  contentVersion: string
+  size: number
+}
+
+export interface FileContentCache {
+  get(file: CachedFileVersion): Promise<Uint8Array | null>
+  put(file: CachedFileVersion, bytes: Uint8Array): Promise<void>
+  remove(file: CachedFileVersion): Promise<void>
+  clear(): Promise<void>
+}
+
+export type FileContentCacheOptions = {
+  maxEntryBytes: number
+  maxTotalBytes: number
+  touchIntervalMs: number
+}
+
+export const FILE_CACHE_MAX_ENTRY_BYTES = 1.5 * 1024 * 1024
+export const FILE_CACHE_MAX_TOTAL_BYTES = 200 * 1024 * 1024
+export const FILE_CACHE_TOUCH_INTERVAL_MS = 60 * 60 * 1000
+
+const DEFAULT_OPTIONS: FileContentCacheOptions = {
+  maxEntryBytes: FILE_CACHE_MAX_ENTRY_BYTES,
+  maxTotalBytes: FILE_CACHE_MAX_TOTAL_BYTES,
+  touchIntervalMs: FILE_CACHE_TOUCH_INTERVAL_MS,
+}
+
+export class NoopFileContentCache implements FileContentCache {
+  async get(_file: CachedFileVersion): Promise<null> { return null }
+  async put(_file: CachedFileVersion, _bytes: Uint8Array): Promise<void> {}
+  async remove(_file: CachedFileVersion): Promise<void> {}
+  async clear(): Promise<void> {}
+}
+
+export function createFileContentCache(
+  sql: SqlStorage,
+  options: FileContentCacheOptions = DEFAULT_OPTIONS,
+): FileContentCache {
+  return options.maxTotalBytes === 0
+    ? new NoopFileContentCache()
+    : new SqliteFileContentCache(sql, options)
+}
+
+type CacheRow = {
+  size: number
+  content: ArrayBuffer
+  accessedAt: number
+}
+
+export class SqliteFileContentCache implements FileContentCache {
+  constructor(
+    private readonly sql: SqlStorage,
+    private readonly options: FileContentCacheOptions,
+  ) {
+    this.sql.exec(`
+      CREATE TABLE IF NOT EXISTS space_file_cache (
+        attachment_id TEXT NOT NULL,
+        content_version TEXT NOT NULL,
+        size INTEGER NOT NULL,
+        cached_content BLOB NOT NULL,
+        accessed_at INTEGER NOT NULL,
+        PRIMARY KEY (attachment_id, content_version),
+        CHECK (size = length(cached_content))
+      );
+      CREATE INDEX IF NOT EXISTS space_file_cache_accessed
+        ON space_file_cache(accessed_at, attachment_id, content_version);
+      CREATE TABLE IF NOT EXISTS space_file_cache_metrics (
+        singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+        hit_total INTEGER NOT NULL DEFAULT 0,
+        miss_total INTEGER NOT NULL DEFAULT 0,
+        put_total INTEGER NOT NULL DEFAULT 0,
+        skip_large_total INTEGER NOT NULL DEFAULT 0,
+        eviction_total INTEGER NOT NULL DEFAULT 0,
+        cached_bytes INTEGER NOT NULL DEFAULT 0
+      );
+      INSERT OR IGNORE INTO space_file_cache_metrics (singleton) VALUES (1);
+    `)
+  }
+
+  async get(file: CachedFileVersion): Promise<Uint8Array | null> {
+    const row = this.sql.exec<CacheRow>(`
+      SELECT size, cached_content AS content, accessed_at AS accessedAt
+      FROM space_file_cache
+      WHERE attachment_id = ? AND content_version = ?
+    `, file.attachmentId, file.contentVersion).toArray()[0]
+    if (!row) {
+      this.bump("miss_total")
+      return null
+    }
+    if (row.size !== file.size || row.content.byteLength !== file.size) {
+      await this.remove(file)
+      this.bump("miss_total")
+      return null
+    }
+    if (this.options.touchIntervalMs === 0 || Date.now() - row.accessedAt >= this.options.touchIntervalMs) {
+      this.sql.exec(
+        `UPDATE space_file_cache SET accessed_at = ?
+         WHERE attachment_id = ? AND content_version = ?`,
+        this.nextAccessedAt(),
+        file.attachmentId,
+        file.contentVersion,
+      )
+    }
+    this.bump("hit_total")
+    return new Uint8Array(row.content)
+  }
+
+  async put(file: CachedFileVersion, bytes: Uint8Array): Promise<void> {
+    if (this.options.maxTotalBytes === 0 || file.size !== bytes.byteLength) return
+    if (bytes.byteLength > this.options.maxEntryBytes || bytes.byteLength > this.options.maxTotalBytes) {
+      this.bump("skip_large_total")
+      return
+    }
+    const currentBytes = this.sql.exec<{ bytes: number }>(`
+      SELECT COALESCE(SUM(size), 0) AS bytes
+      FROM space_file_cache
+      WHERE NOT (attachment_id = ? AND content_version = ?)
+    `,
+      file.attachmentId,
+      file.contentVersion,
+    ).one().bytes
+    const bytesToFree = Math.max(0, currentBytes + bytes.byteLength - this.options.maxTotalBytes)
+    const evictions = bytesToFree === 0 ? 0 : this.sql.exec<{ removed: number }>(`
+      DELETE FROM space_file_cache
+      WHERE rowid IN (
+        SELECT rowid FROM (
+          SELECT rowid, size,
+            SUM(size) OVER (
+              ORDER BY accessed_at, attachment_id, content_version
+            ) AS freed_bytes
+          FROM space_file_cache
+          WHERE NOT (attachment_id = ? AND content_version = ?)
+        )
+        WHERE freed_bytes - size < ?
+      )
+      RETURNING 1 AS removed
+    `, file.attachmentId, file.contentVersion, bytesToFree).toArray().length
+    this.sql.exec(
+      `INSERT OR REPLACE INTO space_file_cache
+        (attachment_id, content_version, size, cached_content, accessed_at)
+       VALUES (?, ?, ?, ?, ?)`,
+      file.attachmentId,
+      file.contentVersion,
+      bytes.byteLength,
+      bytes.slice().buffer,
+      this.nextAccessedAt(),
+    )
+    this.sql.exec(
+      `UPDATE space_file_cache_metrics
+       SET put_total = put_total + 1,
+         eviction_total = eviction_total + ?,
+         cached_bytes = (SELECT COALESCE(SUM(size), 0) FROM space_file_cache)
+       WHERE singleton = 1`,
+      evictions,
+    )
+  }
+
+  async remove(file: CachedFileVersion): Promise<void> {
+    this.sql.exec(
+      "DELETE FROM space_file_cache WHERE attachment_id = ? AND content_version = ?",
+      file.attachmentId,
+      file.contentVersion,
+    )
+    this.refreshCachedBytes()
+  }
+
+  async clear(): Promise<void> {
+    this.sql.exec("DELETE FROM space_file_cache")
+    this.refreshCachedBytes()
+  }
+
+  private nextAccessedAt(): number {
+    const latest = this.sql.exec<{ value: number }>(
+      "SELECT COALESCE(MAX(accessed_at), 0) AS value FROM space_file_cache",
+    ).one().value
+    return Math.max(Date.now(), latest + 1)
+  }
+
+  private bump(column: "hit_total" | "miss_total" | "skip_large_total"): void {
+    this.sql.exec(
+      `UPDATE space_file_cache_metrics SET ${column} = ${column} + 1 WHERE singleton = 1`,
+    )
+  }
+
+  private refreshCachedBytes(): void {
+    this.sql.exec(`
+      UPDATE space_file_cache_metrics
+      SET cached_bytes = (SELECT COALESCE(SUM(size), 0) FROM space_file_cache)
+      WHERE singleton = 1
+    `)
+  }
+}