@springbrand/space 0.1.0-alpha.1

package/src/space/durable-object.ts

@@ -0,0 +1,1557 @@
+import { DurableObject } from "cloudflare:workers"
+import { type FileSystem, type FileInfo } from "@cloudflare/shell"
+import { type Git, type GitLogEntry, type GitStatusEntry } from "@cloudflare/shell/git"
+import type { Env } from "../env"
+import {
+  buildBranchDeployment,
+  handleDeployCommand,
+  type BranchDeploymentBundle,
+  type DeployContext,
+} from "./deploy-engine"
+import { globInfos, readDirInfos, toFileInfo } from "./fileinfo"
+import { handleAssetRequest, buildAssetManifest, createMemoryStorage, type AssetConfig } from "@cloudflare/worker-bundler"
+import {
+  buildInspectorWrapperSource,
+  VIBE_APP_MODULE,
+} from "./inspector-wrapper"
+import { ArtifactsBackend, resolveSpaceFsBackendMode, SqlBackend, spaceR2Prefix, type SpaceFsBackend } from "./fs-backend"
+import { createGitFs, stageWorkdir } from "./git-objects"
+import { stripPreviewSecurityHeaders } from "./preview-headers"
+import * as git from "isomorphic-git"
+import {
+  defaultSpaceQuota,
+  isReservedSpacePath,
+  isUnversionedSpacePath,
+  normalizeSpacePath,
+  normalizeSpacePattern,
+  normalizeWritableSpacePath,
+  toBytes,
+  versionOf,
+  type SpaceCommit,
+  type SpaceCommitManifest,
+  type SpaceConditionalWriteResult,
+  type SpaceAppPort,
+  type SpaceControlPort,
+  type SpaceFileInfo,
+  type SpaceFileVersion,
+  type SpaceQuota,
+  type SpaceUsage,
+  type SpaceWorkspacePort,
+} from "./workspace-port"
+
+export {
+  SPACE_RESERVED_PREFIXES,
+  SPACE_UNVERSIONED_PREFIXES,
+} from "./workspace-port"
+export type {
+  SpaceAppPort,
+  SpaceCommit,
+  SpaceCommitManifest,
+  SpaceConditionalWriteResult,
+  SpaceControlPort,
+  SpaceFileInfo,
+  SpaceFileVersion,
+  SpaceQuota,
+  SpaceUsage,
+  SpaceWorkspacePort,
+} from "./workspace-port"
+
+/** The complete capability a host holds over one Space. */
+export type SpaceStub = SpaceWorkspacePort & SpaceControlPort & SpaceAppPort
+
+// ─── Inspector result types ────────────────────────────────────────────────
+// These mirror the shapes returned by the wrapper-subclass injected into
+// the dynamic worker (see `inspector-wrapper.ts`). Re-exported at the
+// package boundary so the host controller types match.
+
+export interface AppDatabaseColumn {
+  name: string
+  type: string
+  notnull: number
+  pk: number
+}
+export interface AppDatabaseTable {
+  name: string
+  rowCount: number
+  columns: AppDatabaseColumn[]
+}
+export interface AppDatabaseReadResult {
+  columns: string[]
+  rows: Record<string, unknown>[]
+  totalCount: number
+}
+
+export interface AppTableQueryOpts {
+  limit?: number
+  offset?: number
+  orderBy?: string
+  orderDir?: "asc" | "desc"
+}
+
+interface DeploymentRow {
+  branch: string
+  commitHash: string
+  mainModule: string
+  modules: Record<string, string | Record<string, unknown>>
+  assets: Record<string, string>
+  assetConfig: AssetConfig
+  compatibilityDate: string
+}
+
+// Overlay-only paths that must never leak into a deploy, rollback tree, or any
+// file listing: git's object store and the ArtifactsFileSystem bookkeeping dir.
+const isReservedPath = isReservedSpacePath
+
+// ─── SpaceDO ────────────────────────────────────────────────────────────────
+// Agent space Durable Object backed by @cloudflare/shell.
+//
+// Each named instance provides an isolated filesystem + git repo.
+// The host worker calls methods via DO RPC (same worker, no HTTP).
+// Commits/deploys are mirrored to a per-app Cloudflare Artifacts repo
+// (see artifacts-sync.ts), which is the durable source of truth for history.
+
+// Built asset manifest + in-memory storage for a single deployment. Rebuilding
+// these on every request is wasteful (CWE-770 amplification under a preview
+// flood), so we cache them per `branch:commitHash` with an LRU + TTL bound.
+type CachedAssets = {
+  manifest: Awaited<ReturnType<typeof buildAssetManifest>>
+  storage: ReturnType<typeof createMemoryStorage>
+  expiresAt: number
+}
+const ASSET_CACHE_MAX_ENTRIES = 8
+const ASSET_CACHE_TTL_MS = 5 * 60 * 1000 // 5 minutes
+
+export class SpaceDO extends DurableObject<Env>
+  implements SpaceWorkspacePort, SpaceControlPort, SpaceAppPort {
+  private backend!: SpaceFsBackend
+  private initializationPromise: Promise<void> | null = null
+  private assetCache = new Map<string, CachedAssets>()
+  /**
+   * One lane for every operation that reads or rewrites the whole tree.
+   *
+   * A Durable Object's input gate closes across a single call, not across the
+   * awaits inside one — and a commit, a deploy and a restore each walk the
+   * entire working tree. Two of them interleaved would commit half of one
+   * caller's write, so they queue here instead.
+   */
+  private treeLane: Promise<unknown> = Promise.resolve()
+
+  private get overlay(): FileSystem { return this.backend.overlay }
+  private get fs(): FileSystem { return this.backend.fs }
+  private get git(): Git { return this.backend.git }
+  private get stateBackend() { return this.backend.stateBackend }
+
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env)
+  }
+
+  private async flushCheckpoint(): Promise<void> {
+    await this.backend.flushCheckpoint()
+  }
+
+  // ── ArtifactsFileSystem hydration helpers ──
+
+  private async hydrate(path: string): Promise<void> {
+    await this.backend.hydrate(path)
+  }
+
+  private async materializeAll(): Promise<void> {
+    await this.backend.materializeAll()
+  }
+
+  private async ensureInit(): Promise<void> {
+    if (!this.initializationPromise) {
+      this.initializationPromise = this.initializeSpace().catch((error) => {
+        this.initializationPromise = null
+        throw error
+      })
+    }
+    await this.initializationPromise
+  }
+
+  private async initializeSpace(): Promise<void> {
+    await this.initializeBackend()
+
+    // Table needed by the deploy engine. (Git objects/refs live in the
+    // Workspace FS under `.git/`, managed by isomorphic-git — the old `refs`
+    // and `git_internal` tables from the retired smart-HTTP server are gone.)
+    this.ctx.storage.sql.exec(`
+      CREATE TABLE IF NOT EXISTS deployments (
+        branch TEXT PRIMARY KEY,
+        commit_hash TEXT NOT NULL,
+        main_module TEXT NOT NULL,
+        modules TEXT NOT NULL,
+        assets TEXT NOT NULL DEFAULT '{}',
+        asset_config TEXT NOT NULL DEFAULT '{}',
+        compatibility_date TEXT NOT NULL DEFAULT '',
+        deployed_at INTEGER NOT NULL
+      )
+    `)
+
+    // Migrate existing deployments tables that lack new columns
+    try { this.ctx.storage.sql.exec(`ALTER TABLE deployments ADD COLUMN assets TEXT NOT NULL DEFAULT '{}'`) } catch {}
+    try { this.ctx.storage.sql.exec(`ALTER TABLE deployments ADD COLUMN asset_config TEXT NOT NULL DEFAULT '{}'`) } catch {}
+    try { this.ctx.storage.sql.exec(`ALTER TABLE deployments ADD COLUMN compatibility_date TEXT NOT NULL DEFAULT ''`) } catch {}
+
+    // Initialize git repo if not already done
+    try {
+      await this.git.init({ defaultBranch: "main" })
+    } catch {
+      // Already initialized — ignore
+    }
+
+    await this.backend.ready()
+  }
+
+  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)
+  }
+
+  private get spaceName(): string {
+    return this.ctx.id.name ?? "space"
+  }
+
+  /** Serialize whole-tree work: commits, restores, deploys and destruction. */
+  private lane<T>(operation: () => Promise<T>): Promise<T> {
+    const next = this.treeLane.then(operation, operation)
+    this.treeLane = next.then(() => undefined, () => undefined)
+    return next
+  }
+
+  private async statInfo(path: string): Promise<SpaceFileInfo | null> {
+    try {
+      return toFileInfo(path, await this.overlay.stat(path))
+    } catch {
+      return null
+    }
+  }
+
+  private async ensureParent(path: string): Promise<void> {
+    const parent = path.slice(0, path.lastIndexOf("/"))
+    if (!parent) return
+    try {
+      await this.fs.mkdir(parent, { recursive: true })
+    } catch {
+      // Already a directory, which is the only outcome that matters here.
+    }
+  }
+
+  /**
+   * Refuse a write that would take the Space past its limits.
+   *
+   * A Space is one Chat's storage inside one Durable Object, and a runaway
+   * loop writing a file per iteration will exhaust it. The check runs on the
+   * Space's own write boundary, not only in the host wrapper, because the
+   * wrapper is one caller among several.
+   */
+  private async assertWritable(path: string, incomingBytes: number): Promise<void> {
+    const quota = defaultSpaceQuota()
+    if (quota.maxFileBytes !== null && incomingBytes > quota.maxFileBytes) {
+      throw new Error(
+        `Space file exceeds the ${quota.maxFileBytes}-byte limit: ${path}`,
+      )
+    }
+    if (quota.maxTotalBytes === null && quota.maxFiles === null) return
+    const existing = await this.statInfo(path)
+    const usage = await this.usageOf()
+    const projectedBytes = usage.totalBytes - (existing?.size ?? 0) + incomingBytes
+    if (quota.maxTotalBytes !== null && projectedBytes > quota.maxTotalBytes) {
+      throw new Error("Space storage quota exceeded")
+    }
+    const projectedFiles = usage.fileCount + (existing ? 0 : 1)
+    if (quota.maxFiles !== null && projectedFiles > quota.maxFiles) {
+      throw new Error("Space file count quota exceeded")
+    }
+  }
+
+  private async usageOf(): Promise<SpaceUsage> {
+    let fileCount = 0
+    let directoryCount = 0
+    let totalBytes = 0
+    for (const info of await globInfos(this.overlay, "**/*")) {
+      if (isReservedPath(info.path)) continue
+      if (info.type === "file") {
+        fileCount++
+        totalBytes += info.size
+      } else if (info.type === "directory") {
+        directoryCount++
+      }
+    }
+    return { fileCount, directoryCount, totalBytes }
+  }
+
+  async getUsage(): Promise<SpaceUsage> {
+    await this.ensureInit()
+    await this.materializeAll()
+    return this.usageOf()
+  }
+
+  async getQuota(): Promise<SpaceQuota> {
+    return defaultSpaceQuota()
+  }
+
+  // ── Space history ───────────────────────────────────────────────
+  //
+  // A Space has one Git history covering everything it holds. The host projects
+  // a slice of that history — today `/creations` — into the Workspace Revisions
+  // a person sees, so a commit that only touched a scratch script never shows
+  // up as a version of their work.
+
+  private gitFs(): git.FsClient {
+    return createGitFs(this.fs)
+  }
+
+  private async headOid(): Promise<string | null> {
+    try {
+      return await git.resolveRef({ fs: this.gitFs(), dir: "/", ref: "HEAD" })
+    } catch {
+      return null
+    }
+  }
+
+  private async expandOid(revision: string): Promise<string> {
+    if (!/^[0-9a-f]{7,40}$/u.test(revision)) throw new SpaceCommitNotFoundError()
+    try {
+      return await git.expandOid({ fs: this.gitFs(), dir: "/", oid: revision })
+    } catch {
+      throw new SpaceCommitNotFoundError()
+    }
+  }
+
+  /** The tree oid a commit records for `prefix`, or `null` when absent. */
+  private async subtreeOid(commitOid: string, prefix: string): Promise<string | null> {
+    const filepath = relativeTo(prefix)
+    try {
+      const result = filepath
+        ? await git.readTree({ fs: this.gitFs(), dir: "/", oid: commitOid, filepath })
+        : await git.readTree({ fs: this.gitFs(), dir: "/", oid: commitOid })
+      return result.oid
+    } catch {
+      return null
+    }
+  }
+
+  /** Every blob a commit holds under `prefix`, as absolute Space paths. */
+  private async filesInCommit(
+    commitOid: string,
+    prefix: string,
+  ): Promise<Map<string, string>> {
+    const rel = relativeTo(prefix)
+    const gitFs = this.gitFs()
+    const found = new Map<string, string>()
+    const entries = (await git.walk({
+      fs: gitFs,
+      dir: "/",
+      trees: [git.TREE({ ref: commitOid })],
+      map: async (filepath, walkerEntries) => {
+        if (filepath === ".") return undefined
+        const entry = walkerEntries?.[0]
+        if (!entry) return undefined
+        if (rel && filepath !== rel && !filepath.startsWith(`${rel}/`)) return undefined
+        if ((await entry.type()) !== "blob") return undefined
+        return { path: `/${filepath}`, oid: await entry.oid() }
+      },
+    })) as Array<{ path: string; oid: string } | undefined>
+    for (const entry of entries) {
+      if (entry) found.set(entry.path, entry.oid)
+    }
+    return found
+  }
+
+  private async commitEntry(commitOid: string, prefix: string): Promise<SpaceCommit | null> {
+    const treeHash = await this.subtreeOid(commitOid, prefix)
+    if (treeHash === null) return null
+    const { commit } = await git.readCommit({ fs: this.gitFs(), dir: "/", oid: commitOid })
+    return {
+      revision: commitOid,
+      treeHash,
+      reason: commit.message.trim(),
+      createdAt: commit.author.timestamp * 1000,
+    }
+  }
+
+  /**
+   * Commit everything the Space holds that belongs in history.
+   *
+   * Runs inside the tree lane already held by the caller.
+   */
+  private async commitNow(reason: string, prefix = "/"): Promise<{
+    revision: string | null
+    treeHash: string | null
+    changed: boolean
+  }> {
+    const message = reason.trim()
+    if (!message) throw new Error("A Space commit needs a reason")
+    await this.materializeAll()
+    await this.flushCheckpoint()
+    await stageWorkdir(this.fs, isUnversionedSpacePath)
+
+    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 {
+        revision: head,
+        treeHash: await this.subtreeOid(head, prefix),
+        changed: false,
+      }
+    }
+
+    const revision = await git.commit({
+      fs: gitFs,
+      dir: "/",
+      message,
+      author: SPACE_AUTHOR,
+    })
+    return {
+      revision,
+      treeHash: await this.subtreeOid(revision, prefix),
+      changed: true,
+    }
+  }
+
+  /**
+   * Commit the whole Space, reporting the tree of `prefix`.
+   *
+   * Everything is committed — a checkpoint is only useful if all of it is
+   * recoverable — but the hash returned describes the slice the caller cares
+   * about, so it matches what `listCommits` reports for the same projection.
+   */
+  async commit(reason: string, prefix = "/"): Promise<{
+    revision: string | null
+    treeHash: string | null
+    changed: boolean
+  }> {
+    await this.ensureInit()
+    return this.lane(() => this.commitNow(reason, prefix))
+  }
+
+  /**
+   * The commits in which `prefix` actually changed, newest first.
+   *
+   * History is Space-wide, but a version list is about the person's work. A
+   * commit whose `/creations` tree is identical to its parent's is invisible
+   * here, so restoring "the previous version" restores a different set of
+   * files, not merely an earlier timestamp.
+   */
+  async listCommits(prefix: string, limit?: number): Promise<readonly SpaceCommit[]> {
+    await this.ensureInit()
+    const cap = limit === undefined ? 100 : limit
+    if (!Number.isInteger(cap) || cap < 1 || cap > 100) {
+      throw new Error("Invalid Space commit limit")
+    }
+    const head = await this.headOid()
+    if (!head) return []
+    // Newest first, so the entry after each one is its parent. A commit counts
+    // as a version when its projected tree differs from that parent's; the
+    // oldest entry counts whenever it has a projected tree at all.
+    const log = await git.log({ fs: this.gitFs(), dir: "/", depth: 1000 })
+    const trees = await Promise.all(
+      log.map((entry) => this.subtreeOid(entry.oid, prefix)),
+    )
+    const commits: SpaceCommit[] = []
+    for (const [index, entry] of log.entries()) {
+      const treeHash = trees[index]
+      if (treeHash === null || treeHash === undefined) continue
+      if (index + 1 < trees.length && trees[index + 1] === treeHash) continue
+      commits.push({
+        revision: entry.oid,
+        treeHash,
+        reason: entry.commit.message.trim(),
+        createdAt: entry.commit.author.timestamp * 1000,
+      })
+      if (commits.length >= cap) break
+    }
+    return commits
+  }
+
+  async currentCommit(prefix: string): Promise<SpaceCommit | null> {
+    await this.ensureInit()
+    const head = await this.headOid()
+    return head ? this.commitEntry(head, prefix) : null
+  }
+
+  /** The files a commit holds under `prefix`, named relative to it. */
+  async commitManifest(prefix: string, revision: string): Promise<SpaceCommitManifest> {
+    await this.ensureInit()
+    const oid = await this.expandOid(revision)
+    const treeHash = await this.subtreeOid(oid, prefix)
+    if (treeHash === null) throw new SpaceCommitNotFoundError()
+    const blobs = await this.filesInCommit(oid, prefix)
+    const root = `${normalizeSpacePath(prefix)}/`
+    const files: { path: string; size: number }[] = []
+    for (const [path, blobOid] of blobs) {
+      const { blob } = await git.readBlob({ fs: this.gitFs(), dir: "/", oid: blobOid })
+      files.push({ path: path.slice(root.length), size: blob.byteLength })
+    }
+    files.sort((left, right) => left.path.localeCompare(right.path))
+    return { revision: oid, treeHash, files }
+  }
+
+  async readCommitFile(prefix: string, revision: string, path: string): Promise<Uint8Array> {
+    await this.ensureInit()
+    const oid = await this.expandOid(revision)
+    const root = normalizeSpacePath(prefix)
+    const target = `${root}/${commitRelativePath(path)}`
+    const blobOid = (await this.filesInCommit(oid, prefix)).get(target)
+    if (!blobOid) throw new SpaceCommitNotFoundError()
+    const { blob } = await git.readBlob({ fs: this.gitFs(), dir: "/", oid: blobOid })
+    return blob
+  }
+
+  /**
+   * Put `prefix` back the way a commit had it, and record that as a new commit.
+   *
+   * Restoring moves history forward rather than rewriting it, so the state
+   * being replaced stays recoverable. Only `prefix` is touched: a person
+   * restoring a document must not silently roll back the scripts and data
+   * beside it. Nothing is deployed — restoring files is not shipping a site.
+   */
+  async restorePathsFromCommit(
+    prefix: string,
+    revision: string,
+    reason: string,
+  ): Promise<{ revision: string; treeHash: string }> {
+    await this.ensureInit()
+    return this.lane(async () => {
+      await this.materializeAll()
+      const oid = await this.expandOid(revision)
+      const targetTree = await this.subtreeOid(oid, prefix)
+      if (targetTree === null) throw new SpaceCommitNotFoundError()
+
+      // Capture what is there now before overwriting it. Work done since the
+      // last checkpoint is still the person's work, and a restore that erased
+      // it would leave them nothing to go back to.
+      const preserved = await this.commitNow("Before restore", prefix)
+      if (preserved.revision && preserved.treeHash === targetTree) {
+        // Already exactly this. Committing again would add a version that
+        // records no change.
+        return { revision: preserved.revision, treeHash: preserved.treeHash }
+      }
+
+      const wanted = await this.filesInCommit(oid, prefix)
+      const root = normalizeSpacePath(prefix)
+
+      for (const info of await globInfos(this.overlay, `${root}/**/*`)) {
+        if (info.type !== "file" || isReservedPath(info.path)) continue
+        if (!wanted.has(info.path)) await this.fs.rm(info.path, { force: true })
+      }
+      for (const [path, blobOid] of wanted) {
+        const { blob } = await git.readBlob({ fs: this.gitFs(), dir: "/", oid: blobOid })
+        await this.ensureParent(path)
+        await this.fs.writeFileBytes(path, blob)
+      }
+
+      const committed = await this.commitNow(reason, prefix)
+      const head = committed.revision ?? (await this.headOid())
+      if (!head) throw new SpaceCommitNotFoundError()
+      return { revision: head, treeHash: committed.treeHash ?? EMPTY_TREE_OID }
+    })
+  }
+
+  /**
+   * Erase this Space and everything it caused to exist.
+   *
+   * Called when the Chat that owns it is deleted. It is idempotent because the
+   * host retries: a cleanup that fails halfway must be safe to run again, and a
+   * Space that survives its Chat costs storage forever with nobody to notice.
+   */
+  async destroySpace(): Promise<void> {
+    await this.lane(async () => {
+      for (const branch of this.deployedBranches()) {
+        try {
+          await this.ctx.facets.abort(
+            facetNameForApp(branch),
+            new Error("Space destroyed"),
+          )
+        } catch {
+          // Never started, or already gone.
+        }
+        try {
+          await this.ctx.facets.delete(facetNameForApp(branch))
+        } catch {
+          // Already gone.
+        }
+      }
+      await this.deleteSpilledObjects()
+      this.assetCache.clear()
+      await this.ctx.storage.deleteAll()
+      this.initializationPromise = null
+    })
+  }
+
+  private deployedBranches(): string[] {
+    try {
+      return this.ctx.storage.sql
+        .exec("SELECT branch FROM deployments")
+        .toArray()
+        .map((row) => row.branch as string)
+    } catch {
+      return []
+    }
+  }
+
+  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, ...(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 ──────────────────────────────────────
+
+  /**
+   * Read a text file, or `null` when it is not there.
+   *
+   * Upstream threw for a missing path. The runtime contract asks for `null`
+   * instead, and the distinction matters: a caller has to be able to tell "no
+   * such file" from "the store is broken", and every tool that checks before
+   * writing would otherwise have to catch and re-classify an exception.
+   */
+  async readFile(path: string, opts?: { offset?: number; limit?: number }): Promise<string | null> {
+    await this.ensureInit()
+    const target = normalizeSpacePath(path)
+    await this.hydrate(target)
+    // Read through the overlay FS: it hydrates the blob from the Artifacts base
+    // on demand and honours whiteouts (a deleted base file stays deleted).
+    let content: string
+    try {
+      content = await this.fs.readFile(target)
+    } catch {
+      return null
+    }
+
+    if (opts?.offset !== undefined || opts?.limit !== undefined) {
+      const lines = content.split("\n")
+      const start = (opts.offset ?? 1) - 1
+      const end = opts.limit !== undefined ? start + opts.limit : lines.length
+      return lines
+        .slice(start, end)
+        .map((line, i) => `${start + i + 1}\t${line}`)
+        .join("\n")
+    }
+
+    return content
+  }
+
+  async writeFile(path: string, content: string, mimeType?: string): Promise<void> {
+    void mimeType // MIME is derived from the path; the argument keeps the runtime contract.
+    await this.ensureInit()
+    const target = normalizeWritableSpacePath(path)
+    await this.assertWritable(target, byteLength(content))
+    await this.ensureParent(target)
+    // Route through the overlay FS so a write to a previously-deleted base path
+    // clears its whiteout tombstone and makes the file visible again.
+    await this.fs.writeFile(target, content)
+  }
+
+  async writeFileBytes(
+    path: string,
+    data: Uint8Array | ArrayBuffer,
+    mimeType?: string,
+  ): Promise<void> {
+    void mimeType
+    await this.ensureInit()
+    const target = normalizeWritableSpacePath(path)
+    const bytes = toBytes(data)
+    await this.assertWritable(target, bytes.byteLength)
+    await this.ensureParent(target)
+    await this.fs.writeFileBytes(target, bytes)
+  }
+
+  async appendFile(path: string, content: string, mimeType?: string): Promise<void> {
+    void mimeType
+    await this.ensureInit()
+    const target = normalizeWritableSpacePath(path)
+    await this.hydrate(target)
+    const existing = await this.statInfo(target)
+    await this.assertWritable(target, (existing?.size ?? 0) + byteLength(content))
+    await this.ensureParent(target)
+    await this.fs.appendFile(target, content)
+  }
+
+  async exists(path: string): Promise<boolean> {
+    await this.ensureInit()
+    const target = normalizeSpacePath(path)
+    await this.hydrate(target)
+    return this.fs.exists(target)
+  }
+
+  /**
+   * Write only if the file is still exactly what the caller last saw.
+   *
+   * The Sandbox holds a copy of the Space and publishes back into it minutes
+   * later. Without this check a publish silently overwrites whatever the Agent
+   * or the person changed in between, and the loss is invisible — there is no
+   * error and no second copy to recover from.
+   */
+  async writeFileBytesIfUnchanged(
+    path: string,
+    data: Uint8Array,
+    mimeType: string,
+    expected: SpaceFileVersion | null,
+  ): Promise<SpaceConditionalWriteResult> {
+    await this.ensureInit()
+    const target = normalizeWritableSpacePath(path)
+    await this.hydrate(target)
+    const current = await this.statInfo(target)
+    const currentVersion = versionOf(current)
+    const matches = expected === null
+      ? current === null
+      : current?.type === "file" &&
+        current.updatedAt === expected.updatedAt &&
+        current.size === expected.size
+    if (!matches) {
+      return { written: false, reason: "conflict", current: currentVersion }
+    }
+    await this.writeFileBytes(target, data, mimeType)
+    const written = await this.statInfo(target)
+    const version = versionOf(written)
+    if (!version) throw new Error("Published Space file could not be verified")
+    return { written: true, version }
+  }
+
+  async editFile(path: string, oldString: string, newString: string): Promise<{ path: string; size: number }> {
+    await this.ensureInit()
+    await this.hydrate(path)
+    const result = await this.stateBackend.replaceInFile(path, oldString, newString)
+    if (result.replaced === 0) {
+      throw new Error(`old_string not found in ${path}`)
+    }
+    // Read back size
+    const content = await this.fs.readFile(path)
+    return { path, size: content.length }
+  }
+
+  async deleteFile(path: string): Promise<void> {
+    await this.ensureInit()
+    // Route through the overlay-aware FS so a base file is tombstoned
+    // (whiteout), not silently resurrected by later hydration.
+    await this.fs.rm(path, { force: true })
+  }
+
+  /**
+   * Matching entries with their metadata.
+   *
+   * Upstream returned bare paths, which forced every caller to `stat` each
+   * match one at a time — a listing of a few hundred files became a few hundred
+   * extra round trips. The metadata is already in hand here, so it is returned.
+   */
+  async glob(pattern: string): Promise<SpaceFileInfo[]> {
+    await this.ensureInit()
+    await this.materializeAll()
+    const files = await globInfos(this.overlay, normalizeSpacePattern(pattern))
+    return files
+      .filter((f: FileInfo) => f.type === "file" && !isReservedPath(f.path))
+      .sort((a: FileInfo, b: FileInfo) => b.updatedAt - a.updatedAt)
+  }
+
+  /** The bare-path form upstream tooling expects. */
+  async globPaths(pattern: string): Promise<string[]> {
+    return (await this.glob(pattern)).map((f) => f.path)
+  }
+
+  async grep(query: string, include?: string): Promise<Array<{ path: string; line: number; content: string }>> {
+    await this.ensureInit()
+    await this.materializeAll()
+    const results = await this.stateBackend.searchFiles(include ?? "**/*", query)
+    const matches: Array<{ path: string; line: number; content: string }> = []
+    for (const file of results) {
+      for (const match of file.matches) {
+        matches.push({
+          path: file.path,
+          line: match.line,
+          content: match.lineText,
+        })
+      }
+    }
+    return matches
+  }
+
+  async list(prefix?: string): Promise<Array<{ path: string; mtime: number }>> {
+    await this.ensureInit()
+    await this.materializeAll()
+    const pattern = prefix ? `${prefix.replace(/^\//, "")}/**/*` : "**/*"
+    const files = await globInfos(this.overlay, pattern)
+    return files
+      .filter((f: FileInfo) => f.type === "file" && !isReservedPath(f.path))
+      .map((f: FileInfo) => ({ path: f.path, mtime: f.updatedAt }))
+  }
+
+  // ── The WorkspacePort surface ──────────────────────────────────
+  // Method for method, this is the file capability `@springbrand/agent-runtime`
+  // consumes. There is deliberately no second set of file methods beside it:
+  // one Space, one way to read and write it.
+
+  async stat(path: string): Promise<SpaceFileInfo | null> {
+    await this.ensureInit()
+    const target = normalizeSpacePath(path)
+    await this.hydrate(target)
+    return this.statInfo(target)
+  }
+
+  /**
+   * The entry itself, without following a final symlink.
+   *
+   * Scope checks need this: resolving the link first is exactly how a link
+   * planted inside a Space becomes a way to read outside it.
+   */
+  async lstat(path: string): Promise<SpaceFileInfo | null> {
+    await this.ensureInit()
+    const target = normalizeSpacePath(path)
+    await this.hydrate(target)
+    try {
+      return toFileInfo(target, await this.overlay.lstat(target))
+    } catch {
+      return null
+    }
+  }
+
+  async readFileBytes(path: string): Promise<Uint8Array | null> {
+    await this.ensureInit()
+    const target = normalizeSpacePath(path)
+    await this.hydrate(target)
+    // Overlay FS hydrates from the base on demand and honours whiteouts; it
+    // throws ENOENT for a missing path, but this RPC's contract returns null.
+    try {
+      return await this.fs.readFileBytes(target)
+    } catch {
+      return null
+    }
+  }
+
+  async readDir(dir?: string, opts?: { limit?: number; offset?: number }): Promise<SpaceFileInfo[]> {
+    await this.ensureInit()
+    await this.materializeAll()
+    const base = dir === undefined ? "/" : normalizeSpacePath(dir)
+    const entries = await readDirInfos(this.overlay, base, opts)
+    return entries.filter((entry) => !isReservedPath(entry.path))
+  }
+
+  async mkdir(path: string, opts?: { recursive?: boolean }): Promise<void> {
+    await this.ensureInit()
+    await this.fs.mkdir(normalizeWritableSpacePath(path), opts)
+  }
+
+  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.
+    await this.fs.rm(normalizeWritableSpacePath(path), opts)
+  }
+
+  async cp(src: string, dest: string, opts?: { recursive?: boolean }): Promise<void> {
+    await this.ensureInit()
+    const from = normalizeSpacePath(src)
+    const to = normalizeWritableSpacePath(dest)
+    await this.hydrate(from)
+    if (opts?.recursive) await this.materializeAll()
+    const source = await this.statInfo(from)
+    await this.assertWritable(to, source?.size ?? 0)
+    await this.ensureParent(to)
+    await this.fs.cp(from, to, opts)
+  }
+
+  async mv(src: string, dest: string, opts?: { recursive?: boolean }): Promise<void> {
+    void opts // `mv` moves whatever the source is; the FS needs no recursion flag.
+    await this.ensureInit()
+    const from = normalizeWritableSpacePath(src)
+    const to = normalizeWritableSpacePath(dest)
+    await this.materializeAll()
+    await this.ensureParent(to)
+    await this.fs.mv(from, to)
+  }
+
+  async symlink(target: string, linkPath: string): Promise<void> {
+    await this.ensureInit()
+    await this.fs.symlink(target, normalizeWritableSpacePath(linkPath))
+  }
+
+  async readlink(path: string): Promise<string> {
+    await this.ensureInit()
+    return this.fs.readlink(normalizeSpacePath(path))
+  }
+
+  async patch(diff: string): Promise<{ applied: string[]; failed: string[] }> {
+    await this.ensureInit()
+    const edits = parseUnifiedDiffToEdits(diff)
+    const applied: string[] = []
+    const failed: string[] = []
+
+    for (const edit of edits) {
+      try {
+        await this.fs.writeFile(edit.path, edit.content)
+        applied.push(edit.path)
+      } catch {
+        failed.push(edit.path)
+      }
+    }
+
+    return { applied, failed }
+  }
+
+  /** Resolve the branch HEAD currently points at (best-effort). */
+  private async currentBranch(): Promise<string | null> {
+    try {
+      const result = await this.git.branch({ list: true })
+      if ("current" in result && result.current) return result.current
+    } catch {
+      // ignore — treat as unknown
+    }
+    return null
+  }
+
+  // ── Git RPC methods ─────────────────────────────────────────────
+
+  async gitCommitLocal(
+    message: string,
+    author?: { name: string; email: string }
+  ): Promise<{ sha: string; message: string }> {
+    await this.ensureInit()
+    // Persist pending overlay writes before the commit captures the tree.
+    await this.flushCheckpoint()
+    // Stage the workdir (incl. deletions) but never reserved bookkeeping
+    // paths — a committed `.afs/state.json` would pollute the Artifacts base.
+    await stageWorkdir(this.fs, isUnversionedSpacePath)
+    const result = await this.git.commit({
+      message,
+      author: author ?? { name: "Agent", email: "agent@vibesdk.local" },
+    })
+    return { sha: result.oid, message: result.message }
+  }
+
+  async gitCommit(
+    message: string,
+    author?: { name: string; email: string }
+  ): Promise<{ sha: string; message: string }> {
+    await this.ensureInit()
+    // Staging walks the whole tree; ensure the Artifacts base is materialized
+    // so the commit captures every file, not just overlay writes. Reserved
+    // bookkeeping paths (`.afs`) are skipped so they never enter a commit.
+    await this.materializeAll()
+    // Persist pending overlay writes before the commit captures the tree.
+    await this.flushCheckpoint()
+    await stageWorkdir(this.fs, isUnversionedSpacePath)
+    const result = await this.git.commit({
+      message,
+      author: author ?? { name: "Agent", email: "agent@vibesdk.local" },
+    })
+
+    this.ctx.waitUntil(
+      (async () => {
+        const branch = await this.currentBranch()
+        if (branch) await this.backend.push(branch)
+      })(),
+    )
+
+    return { sha: result.oid, message: result.message }
+  }
+
+  async gitLog(limit?: number): Promise<GitLogEntry[]> {
+    await this.ensureInit()
+    return this.git.log({ depth: limit })
+  }
+
+  async gitStatus(): Promise<GitStatusEntry[]> {
+    await this.ensureInit()
+    return this.git.status()
+  }
+
+  async gitCheckout(ref: string): Promise<void> {
+    await this.ensureInit()
+    await this.git.checkout({ ref })
+  }
+
+  async gitBranch(opts?: { name?: string; list?: boolean; delete?: string }) {
+    await this.ensureInit()
+    return this.git.branch(opts)
+  }
+
+  async gitDiff(): Promise<Array<{ filepath: string; status: string }>> {
+    await this.ensureInit()
+    return this.git.diff()
+  }
+
+  /**
+   * Roll back `branch` to the tree of `commitHash` and redeploy. This is a
+   * forward restore (not a destructive reset): it captures the file tree at the
+   * target commit, reconciles the branch working tree to match it, then creates
+   * a new commit on `branch` and deploys — so history stays intact and the
+   * preview rebuilds from the restored files.
+   */
+  async rollbackToCommit(branch: string, commitHash: string): Promise<unknown> {
+    await this.ensureInit()
+    // Reads/walks the whole working tree below, so the Artifacts base must be
+    // fully materialized into the overlay first.
+    await this.materializeAll()
+
+    await this.backend.fetch(branch)
+
+    // Verify the target commit exists on this branch's history.
+    const history = await this.git.log({ ref: branch, depth: 1000 })
+    const target = history.find(
+      (entry) => entry.oid === commitHash || entry.oid.startsWith(commitHash),
+    )
+    if (!target) {
+      return { error: `Commit ${commitHash} not found on branch "${branch}"` }
+    }
+
+    // Capture the file tree at the target commit as raw bytes. Reading and
+    // rewriting via bytes (not strings) keeps binary assets — fonts, images,
+    // favicons — byte-for-byte intact. Round-tripping them through UTF-8
+    // corrupts them and inflates each invalid byte into a 3-byte replacement
+    // char, which can push a file past the SQLite inline-value limit and throw
+    // SQLITE_TOOBIG (only reproduced on rollback, since normal deploys never
+    // rewrite these files).
+    await this.git.checkout({ ref: target.oid })
+    const targetFiles = new Map<string, Uint8Array>()
+    for (const info of await globInfos(this.overlay, "**/*")) {
+      if (info.type !== "file") continue
+      if (isReservedPath(info.path)) continue
+      const bytes = await this.overlay.readFileBytes(info.path)
+      if (bytes) targetFiles.set(info.path, bytes)
+    }
+
+    // Return to the branch HEAD and reconcile the working tree: remove files
+    // that are absent from the target, then (over)write the captured files.
+    await this.git.checkout({ ref: branch })
+    for (const info of await globInfos(this.overlay, "**/*")) {
+      if (info.type !== "file") continue
+      if (isReservedPath(info.path)) continue
+      if (!targetFiles.has(info.path)) {
+        await this.overlay.rm(info.path, { force: true })
+      }
+    }
+    for (const [path, bytes] of targetFiles) {
+      await this.overlay.writeFileBytes(path, bytes)
+    }
+
+    // Commit the restored tree (no-op if nothing changed) and redeploy.
+    try {
+      await this.gitCommit(`rollback: restore ${target.oid.slice(0, 8)}`)
+    } catch {
+      // Clean tree (already at target) — proceed to redeploy existing HEAD.
+    }
+    return this.deploy(branch)
+  }
+
+  // ── Deploy RPC methods ──────────────────────────────────────────
+
+  /**
+   * Build and publish `appRoot` as this branch's app.
+   *
+   * `appRoot` is what keeps a Space from being an app by default: a data
+   * analysis Space with a spreadsheet and a script deploys nothing until
+   * someone names the directory that holds a site.
+   */
+  async deploy(branch: string, appRoot?: string): Promise<unknown> {
+    await this.ensureInit()
+    return this.lane(async () => {
+      // The deploy engine reads the full branch tree, so ensure the Artifacts
+      // base is materialized into the overlay first.
+      await this.materializeAll()
+      await this.flushCheckpoint()
+      const fakeRequest = new Request("http://internal/?cmd=deploy", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ branch, ...(appRoot ? { appRoot } : {}) }),
+      })
+      const ctx: DeployContext = {
+        sql: this.ctx.storage.sql,
+        git: this.git,
+        fs: this.fs,
+      }
+      const res = await handleDeployCommand(ctx, "deploy", fakeRequest)
+      const data = await res.json() as Record<string, unknown>
+      data.preview_url = `/space/${this.spaceName}/preview/${encodeURIComponent(branch)}/`
+
+      if (!data.error) await this.backend.push(branch)
+
+      return data
+    })
+  }
+
+  async getDeploymentBundle(
+    branch: string,
+    appRoot?: string,
+  ): Promise<BranchDeploymentBundle> {
+    await this.ensureInit()
+    await this.materializeAll()
+    return buildBranchDeployment(
+      {
+        sql: this.ctx.storage.sql,
+        git: this.git,
+        fs: this.fs,
+      },
+      branch,
+      appRoot,
+    )
+  }
+
+  async undeploy(branch: string): Promise<unknown> {
+    await this.ensureInit()
+    const fakeRequest = new Request("http://internal/?cmd=undeploy", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ branch }),
+    })
+    const ctx: DeployContext = {
+      sql: this.ctx.storage.sql,
+      git: this.git,
+      fs: this.overlay,
+    }
+    const res = await handleDeployCommand(ctx, "undeploy", fakeRequest)
+    return res.json()
+  }
+
+  async listDeployments(): Promise<unknown> {
+    await this.ensureInit()
+    const fakeRequest = new Request("http://internal/?cmd=list_deployments")
+    const ctx: DeployContext = {
+      sql: this.ctx.storage.sql,
+      git: this.git,
+      fs: this.overlay,
+    }
+    const res = await handleDeployCommand(ctx, "list_deployments", fakeRequest)
+    return res.json()
+  }
+
+  async getDeployment(branch: string): Promise<unknown> {
+    await this.ensureInit()
+    const fakeRequest = new Request(`http://internal/?cmd=get_deployment&branch=${encodeURIComponent(branch)}`)
+    const ctx: DeployContext = {
+      sql: this.ctx.storage.sql,
+      git: this.git,
+      fs: this.overlay,
+    }
+    const res = await handleDeployCommand(ctx, "get_deployment", fakeRequest)
+    return res.json()
+  }
+
+  // ── Space info ──────────────────────────────────────────────────
+
+  async getInfo(): Promise<{ fileCount: number; directoryCount: number; totalBytes: number }> {
+    await this.ensureInit()
+    await this.materializeAll()
+    let fileCount = 0
+    let directoryCount = 0
+    let totalBytes = 0
+    for (const info of await globInfos(this.overlay, "**/*")) {
+      if (isReservedPath(info.path)) continue
+      if (info.type === "file") {
+        fileCount++
+        totalBytes += info.size
+      } else if (info.type === "directory") {
+        directoryCount++
+      }
+    }
+    return { fileCount, directoryCount, totalBytes }
+  }
+
+  // ── Deployment row reader (shared by servePreview + DB-viewer) ──
+
+  private readDeployment(branch: string): DeploymentRow | null {
+    const rows = this.ctx.storage.sql
+      .exec(
+        "SELECT branch, commit_hash, main_module, modules, assets, asset_config, compatibility_date FROM deployments WHERE branch = ?",
+        branch,
+      )
+      .toArray()
+    if (rows.length === 0) return null
+    const r = rows[0]
+    return {
+      branch: r.branch as string,
+      commitHash: r.commit_hash as string,
+      mainModule: r.main_module as string,
+      modules: JSON.parse(r.modules as string) as Record<string, string | Record<string, unknown>>,
+      assets: JSON.parse((r.assets as string) || "{}") as Record<string, string>,
+      assetConfig: JSON.parse((r.asset_config as string) || "{}") as AssetConfig,
+      compatibilityDate: (r.compatibility_date as string) || FALLBACK_COMPATIBILITY_DATE,
+    }
+  }
+
+  // ── Preview serving via Dynamic Workers ─────────────────────────
+  //
+  // Architecture (matches Cloudflare's Durable Object Facets docs example):
+  //
+  //   - The LLM exports `class App extends DurableObject` from its main
+  //     module. `App.fetch(request)` is the entire backend (Hono /
+  //     itty-router / vanilla — the LLM decides).
+  //   - SpaceDO acts as the supervisor ("AppRunner" in the docs).
+  //     `servePreview` loads the user's worker via the Worker Loader,
+  //     extracts the App class, and hosts it as a Facet keyed
+  //     `app:<branch>`. Static assets are served host-side; everything
+  //     else (including WebSocket upgrades) is forwarded into the Facet.
+  //   - State is the Facet's own `ctx.storage` (SQLite + KV). No env.DB
+  //     binding is injected.
+  //   - To make the DB-viewer work without forcing the LLM to write
+  //     inspector boilerplate, we don't load the user's main directly.
+  //     We load a wrapper module (`inspector-wrapper.ts`) which imports
+  //     the user's `App`, re-exports everything, and exports a subclass
+  //     `App` that adds `__vibeInspectListTables` / `__vibeInspectRead`
+  //     / `__vibeWipe`. The subclass shares the same `ctx.storage`.
+
+  async servePreview(branch: string, request: Request): Promise<Response> {
+    await this.ensureInit()
+
+    const dep = this.readDeployment(branch)
+    if (!dep) {
+      return new Response(`No deployment found for branch "${branch}"`, { status: 404 })
+    }
+
+    // Serve static assets host-side before forwarding to the Facet. The built
+    // manifest/storage are cached per deployment so repeat asset reads don't
+    // re-spin the build on every request.
+    if (Object.keys(dep.assets).length > 0) {
+      const { manifest, storage } = await this.getCachedAssets(dep)
+      const assetResponse = await handleAssetRequest(request, manifest, storage, dep.assetConfig)
+      if (assetResponse) return assetResponse
+    }
+
+    let appClass: DurableObjectClass
+    try {
+      appClass = this.loadAppClass(dep)
+    } catch (e) {
+      return new Response(
+        `Failed to load App class: ${e instanceof Error ? e.message : String(e)}`,
+        { status: 500 },
+      )
+    }
+
+    const facet = this.ctx.facets.get(facetNameForApp(branch), () => ({ class: appClass }))
+    return facet.fetch(request)
+  }
+
+  /**
+   * Return the built asset manifest + in-memory storage for a deployment,
+   * reusing a cached build when available. Keyed by `branch:commitHash` so a
+   * redeploy (new commit) transparently rebuilds. Bounded by an LRU cap + TTL.
+   */
+  private async getCachedAssets(dep: DeploymentRow): Promise<CachedAssets> {
+    const key = `${dep.branch}:${dep.commitHash}`
+    const now = Date.now()
+
+    const cached = this.assetCache.get(key)
+    if (cached && cached.expiresAt > now) {
+      // Refresh LRU recency.
+      this.assetCache.delete(key)
+      this.assetCache.set(key, cached)
+      return cached
+    }
+
+    const manifest = await buildAssetManifest(dep.assets)
+    const storage = createMemoryStorage(dep.assets)
+    const entry: CachedAssets = { manifest, storage, expiresAt: now + ASSET_CACHE_TTL_MS }
+
+    this.assetCache.set(key, entry)
+
+    // Evict expired / oldest entries to keep the cache bounded.
+    for (const [k, v] of this.assetCache) {
+      if (v.expiresAt <= now) this.assetCache.delete(k)
+    }
+    while (this.assetCache.size > ASSET_CACHE_MAX_ENTRIES) {
+      const oldest = this.assetCache.keys().next().value
+      if (oldest === undefined) break
+      this.assetCache.delete(oldest)
+    }
+
+    return entry
+  }
+
+  // ── App-class loader ────────────────────────────────────────────
+  //
+  // Loads the dynamic worker for `branch`'s latest deployment with the
+  // inspector wrapper as the main module. The wrapper imports the
+  // user's main and exports a subclass of `App` with `__vibeInspect*`
+  // methods (see `inspector-wrapper.ts`).
+  //
+  // `LOADER.get(id, ...)` caches by id. We key on
+  // `<spaceName>-<branch>-<commitHash>` so a redeploy invalidates the
+  // worker (and any Facet still pinned to the old class is aborted
+  // implicitly the next time `ctx.facets.get(...)` runs the callback).
+  private loadAppClass(dep: DeploymentRow): DurableObjectClass {
+    const spaceName = this.ctx.id.name ?? "space"
+    const workerId = `${spaceName}-${dep.branch}-${dep.commitHash}`
+    const wrappedModules: Record<string, string | Record<string, unknown>> = {
+      ...dep.modules,
+      [VIBE_APP_MODULE]: buildInspectorWrapperSource(dep.mainModule),
+    }
+    const worker = this.env.LOADER.get(workerId, async () => ({
+      mainModule: VIBE_APP_MODULE,
+      modules: wrappedModules,
+      // The date the app declared, not a date frozen into this file. A worker
+      // built against one runtime and run under another is a bug the author
+      // cannot see or fix.
+      compatibilityDate: dep.compatibilityDate || FALLBACK_COMPATIBILITY_DATE,
+      // Generated code gets no outbound network. Omitting this inherits the
+      // parent Worker's full internet access, which would let an app the model
+      // wrote reach anything this Worker can — including internal services.
+      globalOutbound: null,
+    }))
+    return (
+      worker as { getDurableObjectClass: (name: string) => DurableObjectClass }
+    ).getDurableObjectClass("App")
+  }
+
+  /**
+   * Returns a Facet stub for the App of `branch`, starting it (loading
+   * the dynamic worker, wrapping the App class) on first call. Used by
+   * the DB-viewer inspector RPCs.
+   *
+   * Returns `null` if there is no deployment yet for the branch.
+   */
+  private getAppFacet(branch: string): Fetcher | null {
+    const dep = this.readDeployment(branch)
+    if (!dep) return null
+    const cls = this.loadAppClass(dep)
+    return this.ctx.facets.get(facetNameForApp(branch), () => ({ class: cls })) as unknown as Fetcher
+  }
+
+  // ── DB-viewer RPC methods ───────────────────────────────────────
+  //
+  // The App's storage lives inside the Facet. The inspector wrapper
+  // (`inspector-wrapper.ts`) extends the user's App class with
+  // `__vibeInspect*` methods, so we just RPC into the Facet stub.
+
+  async listAppTables(branch: string): Promise<AppDatabaseTable[]> {
+    await this.ensureInit()
+    const facet = this.getAppFacet(branch)
+    if (!facet) return []
+    return await (facet as unknown as {
+      __vibeInspectListTables: () => Promise<AppDatabaseTable[]>
+    }).__vibeInspectListTables()
+  }
+
+  async queryAppTable(
+    branch: string,
+    table: string,
+    opts: AppTableQueryOpts = {},
+  ): Promise<AppDatabaseReadResult> {
+    await this.ensureInit()
+    const facet = this.getAppFacet(branch)
+    if (!facet) {
+      return { columns: [], rows: [], totalCount: 0 }
+    }
+    return await (facet as unknown as {
+      __vibeInspectRead: (
+        table: string,
+        opts: AppTableQueryOpts,
+      ) => Promise<AppDatabaseReadResult>
+    }).__vibeInspectRead(table, opts)
+  }
+
+  /**
+   * Drop every user table inside the App Facet's SQLite. We use a
+   * targeted drop rather than `ctx.facets.delete(...)` because the
+   * latter aborts the Facet immediately and breaks any active
+   * WebSocket connections — the user is usually in the middle of
+   * preview-iteration when they hit Reset.
+   */
+  async wipeAppDatabase(branch: string): Promise<{ ok: true }> {
+    await this.ensureInit()
+    const facet = this.getAppFacet(branch)
+    if (!facet) return { ok: true }
+    await (facet as unknown as {
+      __vibeWipe: () => Promise<{ ok: true }>
+    }).__vibeWipe()
+    return { ok: true }
+  }
+
+  // ── HTTP handler: preview serving + internal deploy commands ────
+
+  async fetch(request: Request): Promise<Response> {
+    await this.ensureInit()
+
+    const url = new URL(request.url)
+    const path = url.pathname
+
+    // Preview routes: /space/:name/preview/:branch/*
+    const previewMatch = path.match(/\/preview\/([^/]+)(\/.*)?$/)
+    if (previewMatch) {
+      const branch = decodeURIComponent(previewMatch[1])
+      const spaceName = this.ctx.id.name ?? "space"
+      const basePath = `/space/${spaceName}/preview/${encodeURIComponent(branch)}`
+
+      // Rewrite the URL so the dynamic worker sees a clean path
+      const subPath = previewMatch[2] || "/"
+      const previewUrl = new URL(subPath, url.origin)
+      previewUrl.search = url.search
+      const previewRequest = new Request(previewUrl.toString(), request)
+      const response = await this.servePreview(branch, previewRequest)
+
+      // Strip headers a generated app must not be able to set on the shared
+      // preview origin (e.g. Service-Worker-Allowed scope expansion) before
+      // any further rewriting.
+      const safeResponse = stripPreviewSecurityHeaders(response)
+
+      // Rewrite root-relative paths in HTML responses so they resolve
+      // correctly when the preview is mounted on a sub-path
+      return rewritePreviewResponse(safeResponse, basePath)
+    }
+
+    // Deploy command routes
+    const cmd = url.searchParams.get("cmd")
+    if (cmd && ["deploy", "get_deployment", "list_deployments", "undeploy"].includes(cmd)) {
+      const deployCtx: DeployContext = {
+        sql: this.ctx.storage.sql,
+        git: this.git,
+        fs: this.overlay,
+      }
+      return handleDeployCommand(deployCtx, cmd, request)
+    }
+
+    return new Response("Not Found", { status: 404 })
+  }
+}
+
+// ─── Preview Response Rewriting ──────────────────────────────────────────────
+// When a preview is served on /space/:name/preview/:branch/, root-relative
+// paths like /style.css in HTML would resolve to the domain root instead of
+// the preview path. We rewrite them so the browser fetches the correct URL.
+
+function rewritePreviewResponse(response: Response, basePath: string): Response {
+  // Rewrite Location header on redirects
+  const location = response.headers.get("location")
+  if (location?.startsWith("/")) {
+    const rewritten = new Response(response.body, response)
+    rewritten.headers.set("location", basePath + location)
+    return rewritten
+  }
+
+  // Only rewrite HTML responses
+  const ct = response.headers.get("content-type") ?? ""
+  if (!ct.includes("text/html")) return response
+
+  // Use HTMLRewriter to prefix root-relative src/href/action attributes
+  return new HTMLRewriter()
+    .on("[src],[href],[action]", {
+      element(el) {
+        for (const attr of ["src", "href", "action"] as const) {
+          const val = el.getAttribute(attr)
+          if (val?.startsWith("/") && !val.startsWith("//")) {
+            el.setAttribute(attr, basePath + val)
+          }
+        }
+      },
+    })
+    .transform(response)
+}
+
+// ─── Facet naming ───────────────────────────────────────────────────────────
+
+function facetNameForApp(branch: string): string {
+  return `app:${branch}`
+}
+
+// ─── Space history helpers ──────────────────────────────────────────────────
+
+/** Git's oid for an empty tree — what a repository with no content writes. */
+const EMPTY_TREE_OID = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"
+
+/** Used only for deployments recorded before the date was persisted. */
+const FALLBACK_COMPATIBILITY_DATE = "2025-04-01"
+
+const SPACE_AUTHOR = Object.freeze({
+  name: "Workspace",
+  email: "workspace@springbrand.local",
+})
+
+/** Raised when a caller names a commit this Space does not have. */
+export class SpaceCommitNotFoundError extends Error {
+  constructor() {
+    super("space_commit_not_found")
+    this.name = "SpaceCommitNotFoundError"
+  }
+}
+
+function relativeTo(prefix: string): string {
+  return prefix.split("/").filter(Boolean).join("/")
+}
+
+/**
+ * A path naming one file inside a commit, or nothing.
+ *
+ * Stricter than a live Space path, and deliberately so: this string arrives
+ * from a download URL, so anything but a plain relative POSIX path is a caller
+ * trying to reach past the projection. Rejecting it as "no such file" is the
+ * honest answer and reveals nothing about what else the commit holds.
+ */
+function commitRelativePath(path: string): string {
+  if (typeof path !== "string" || !path || path.startsWith("/") || path.includes("\\")) {
+    throw new SpaceCommitNotFoundError()
+  }
+  const parts = path.split("/")
+  if (parts.some((part) => !part || part === "." || part === ".." || part === ".git")) {
+    throw new SpaceCommitNotFoundError()
+  }
+  return parts.join("/")
+}
+
+function byteLength(content: string): number {
+  return new TextEncoder().encode(content).byteLength
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+interface PatchEdit {
+  path: string
+  content: string
+}
+
+function parseUnifiedDiffToEdits(diff: string): PatchEdit[] {
+  const edits: PatchEdit[] = []
+  const lines = diff.split("\n")
+  let i = 0
+
+  while (i < lines.length) {
+    if (lines[i].startsWith("--- ")) {
+      const oldPath = lines[i].slice(4).replace(/^[ab]\//, "")
+      i++
+      if (i < lines.length && lines[i].startsWith("+++ ")) {
+        const newPath = lines[i].slice(4).replace(/^[ab]\//, "")
+        i++
+        const path = newPath === "/dev/null" ? oldPath : newPath
+        const resultLines: string[] = []
+
+        while (i < lines.length && !lines[i].startsWith("--- ")) {
+          const l = lines[i]
+          if (l.startsWith("@@")) {
+            i++
+            continue
+          }
+          if (l.startsWith("+") && !l.startsWith("+++")) {
+            resultLines.push(l.slice(1))
+          } else if (l.startsWith("-") && !l.startsWith("---")) {
+            // removed line — skip
+          } else if (l.startsWith(" ") || l === "") {
+            resultLines.push(l.slice(1))
+          } else {
+            break
+          }
+          i++
+        }
+
+        edits.push({ path, content: resultLines.join("\n") })
+        continue
+      }
+    }
+    i++
+  }
+
+  return edits
+}