@springbrand/space 0.1.0-alpha.9 → 0.2.0-alpha.1

package/README.md

@@ -1,7 +1,7 @@
 # @springbrand/space
 
-SpaceDO — a git-backed Durable Object workspace with deploy, preview and App
-Facet database inspection.
+SpaceDO — a git-backed Durable Object workspace with target-neutral deployment
+bundles, CDN-backed Preview assets, App Facet execution and database inspection.
 
 ## Provenance
 
@@ -11,14 +11,18 @@ This package is a tracked fork of the VibeSDK `space/` package.
 - Frozen at: `main@a318f08625db`
 - Licence: MIT (see `LICENSE`)
 
-Files under `src/space/` are the upstream implementation. Local additions are
-confined to the `WorkspacePort` compatibility surface on `SpaceDO`
-(`durable-object.ts`), which Agent Runtime hosts require: binary
-writes, append, conditional write, quota, full file operations, R2 spill,
-path-level restore and `destroySpace`.
+The fork retains VibeSDK's Workspace and App Facet model while replacing its
+single-row Preview assets with per-file R2 objects. One `DeploymentBundle`
+separates Worker modules, static asset metadata and deployment-level runtime
+configuration so Preview and production publishers can consume the same build.
 
 ## Boundary
 
 SpaceDO is infrastructure. It knows nothing about users, Chats or
 authorisation — the host Worker decides which Space a request belongs to and
 whether the caller may reach it.
+
+Preview publication writes static assets below one immutable R2 deployment
+prefix and returns that prefix to the host. Static requests can therefore go
+straight to a Workspace CDN; `serveApp()` is the dynamic-only path into the App
+Facet. SpaceDO never reads static assets for browser requests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/space",
-  "version": "0.1.0-alpha.9",
+  "version": "0.2.0-alpha.1",
   "type": "module",
   "files": [
     "src",

package/src/index.ts

@@ -18,7 +18,17 @@ export type {
   SpaceWorkspacePort,
 } from "./space/durable-object";
 export { SPACE_RESERVED_PREFIXES } from "./space/durable-object";
-export type { BranchDeploymentBundle } from "./space/deploy-engine";
+export {
+  deploymentRuntimeConfigSource,
+  RUNTIME_CONFIG_ASSET_PATH,
+} from "./space/deploy-engine";
+export type {
+  BranchDeploymentBundle,
+  DeploymentAsset,
+  DeploymentBundle,
+  DeploymentRuntimeConfig,
+  SpaceDeploymentResult,
+} from "./space/deploy-engine";
 
 // ── Preview hardening ─────────────────────────────────────────────
 export { stripPreviewSecurityHeaders, STRIPPED_PREVIEW_HEADERS } from "./space/preview-headers";

package/src/space/deploy-engine.ts

@@ -32,18 +32,40 @@ export interface DeployContext {
   assetPrefix?: string
 }
 
-export interface BranchDeploymentBundle {
+export interface DeploymentBundle {
   branch: string
   commitHash: string
-  mainModule: string
-  modules: Record<string, string | Record<string, unknown>>
-  assets: DeploymentAsset[]
+  workerModules: {
+    mainModule: string
+    modules: Record<string, string | Record<string, unknown>>
+    compatibilityDate: string
+  }
+  staticAssets: DeploymentAsset[]
   assetConfig: AssetConfig | undefined
-  compatibilityDate: string
+  runtimeConfig: DeploymentRuntimeConfig | undefined
+}
+
+export type BranchDeploymentBundle = DeploymentBundle
+
+export interface DeploymentRuntimeConfig {
+  apiBaseUrl: string
+}
+
+export interface SpaceDeploymentResult {
+  branch: string
+  commit_hash: string
+  main_module: string
+  has_assets: boolean
+  compatibility_date: string
+  deployed_at: string
+  asset_root: string | null
 }
 
+export const RUNTIME_CONFIG_ASSET_PATH = "/.springbrand/runtime-config.js"
+
 export interface DeploymentAsset {
   path: string
+  sourcePath: string | null
   contentType: string | undefined
   etag: string
   size: number
@@ -173,6 +195,7 @@ async function readBranchFiles(
         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,
         }
@@ -219,6 +242,7 @@ async function deployBranch(
     branch: string
     appRoot?: string
     revision?: string
+    runtimeConfig?: DeploymentRuntimeConfig
   }
   const branch = body.branch
   if (!branch) {
@@ -257,6 +281,7 @@ async function deployBranch(
         )
         return uploaded.etag
       },
+      body.runtimeConfig,
     )
   } catch (e) {
     await discardAssetDeployment(ctx, assetDeploymentId, assetRoot).catch((cleanupError) => {
@@ -273,11 +298,12 @@ async function deployBranch(
   const {
     branch: deploymentId,
     commitHash,
-    mainModule,
-    modules: serializedModules,
-    assets,
-    assetConfig,
-    compatibilityDate: compatDate,
+    workerModules: {
+      mainModule,
+      modules: serializedModules,
+      compatibilityDate: compatDate,
+    },
+    staticAssets: assets,
   } = bundle
 
   const now = Date.now()
@@ -291,16 +317,14 @@ async function deployBranch(
   try {
     ctx.sql.exec(
       `INSERT OR REPLACE INTO deployments
-       (branch, commit_hash, main_module, modules, assets, asset_deployment_id, asset_count,
-        asset_config, compatibility_date, deployed_at)
-       VALUES (?, ?, ?, ?, '{}', ?, ?, ?, ?, ?)`,
+       (branch, commit_hash, main_module, modules, asset_deployment_id,
+        compatibility_date, deployed_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
       deploymentId,
       commitHash,
       mainModule,
       JSON.stringify(serializedModules),
       assets.length > 0 ? assetDeploymentId : "",
-      assets.length,
-      assetConfig ? JSON.stringify(assetConfig) : "{}",
       compatDate,
       now
     )
@@ -333,6 +357,7 @@ async function deployBranch(
     has_assets: assets.length > 0,
     compatibility_date: compatDate,
     deployed_at: new Date(now).toISOString(),
+    asset_root: assets.length > 0 ? assetRoot : null,
   })
 }
 
@@ -342,6 +367,7 @@ export async function buildBranchDeployment(
   appRoot?: string | null,
   revision?: string,
   writeAsset?: AssetWriter,
+  runtimeConfig?: DeploymentRuntimeConfig,
 ): Promise<BranchDeploymentBundle> {
   const root = normalizeAppRoot(appRoot)
   const { commitHash, files, assets, config } = await readBranchFiles(
@@ -351,6 +377,22 @@ export async function buildBranchDeployment(
     revision,
     writeAsset,
   )
+  const normalizedRuntimeConfig = normalizeRuntimeConfig(runtimeConfig)
+  if (normalizedRuntimeConfig) {
+    const bytes = new TextEncoder().encode(
+      deploymentRuntimeConfigSource(normalizedRuntimeConfig),
+    )
+    const asset: Omit<DeploymentAsset, "etag"> = {
+      path: RUNTIME_CONFIG_ASSET_PATH,
+      sourcePath: null,
+      contentType: "application/javascript; charset=utf-8",
+      size: bytes.byteLength,
+    }
+    const etag = writeAsset
+      ? await writeAsset(asset, bytes)
+      : await computeAssetEtag(bytes)
+    assets.push({ ...asset, etag })
+  }
   if (Object.keys(files).length === 0) {
     throw new Error(
       root
@@ -364,17 +406,40 @@ export async function buildBranchDeployment(
     return {
       branch: revision ?? branch,
       commitHash,
-      mainModule: result.mainModule,
-      modules: result.modules,
-      assets,
+      workerModules: {
+        mainModule: result.mainModule,
+        modules: result.modules,
+        compatibilityDate: result.compatibilityDate,
+      },
+      staticAssets: assets,
       assetConfig: result.assetConfig,
-      compatibilityDate: result.compatibilityDate,
+      runtimeConfig: normalizedRuntimeConfig,
     }
   } catch (e) {
     throw new Error(`Build failed: ${e instanceof Error ? e.message : String(e)}`)
   }
 }
 
+function normalizeRuntimeConfig(
+  config: DeploymentRuntimeConfig | undefined,
+): DeploymentRuntimeConfig | undefined {
+  if (!config) return undefined
+  let url: URL
+  try {
+    url = new URL(config.apiBaseUrl)
+  } catch {
+    throw new Error("runtimeConfig.apiBaseUrl must be an absolute HTTP(S) URL ending in /")
+  }
+  if (!["http:", "https:"].includes(url.protocol) || !url.pathname.endsWith("/")) {
+    throw new Error("runtimeConfig.apiBaseUrl must be an absolute HTTP(S) URL ending in /")
+  }
+  return { apiBaseUrl: url.toString() }
+}
+
+export function deploymentRuntimeConfigSource(config: DeploymentRuntimeConfig): string {
+  return `globalThis.__APP_CONFIG__=Object.freeze(${JSON.stringify(config)});`
+}
+
 async function buildWebsite(
   sourceFiles: Record<string, string>,
   config: ParsedWranglerConfig,
@@ -463,7 +528,7 @@ function toAssetPath(path: string, directory: string): string {
 
 async function computeAssetEtag(bytes: Uint8Array): Promise<string> {
   const digest = await crypto.subtle.digest("SHA-256", exactBuffer(bytes))
-  return [...new Uint8Array(digest).slice(0, 8)]
+  return [...new Uint8Array(digest).slice(0, 16)]
     .map((byte) => byte.toString(16).padStart(2, "0"))
     .join("")
 }
@@ -490,8 +555,7 @@ async function getDeployment(
 
   const row = ctx.sql
     .exec(
-      `SELECT branch, commit_hash, main_module, modules, assets, asset_count,
-              asset_config, deployed_at
+      `SELECT branch, commit_hash, main_module, modules, asset_deployment_id, deployed_at
        FROM deployments WHERE branch = ?`,
       branch
     )
@@ -502,14 +566,17 @@ async function getDeployment(
   }
 
   const r = row[0]
-  const legacyAssets = JSON.parse((r.assets as string) || "{}")
+  const assetDeploymentId = (r.asset_deployment_id as string) || ""
   return jsonResponse({
     branch: r.branch as string,
     commit_hash: r.commit_hash as string,
     main_module: r.main_module as string,
     modules: JSON.parse(r.modules as string),
-    has_assets: Number(r.asset_count ?? 0) > 0 || Object.keys(legacyAssets).length > 0,
+    has_assets: Boolean(assetDeploymentId),
     deployed_at: new Date(r.deployed_at as number).toISOString(),
+    asset_root: assetDeploymentId && ctx.assetPrefix
+      ? `${ctx.assetPrefix}/deployments/${assetDeploymentId}`
+      : null,
   })
 }
 
@@ -518,21 +585,17 @@ async function getDeployment(
 async function listDeployments(ctx: DeployContext): Promise<Response> {
   const rows = ctx.sql
     .exec(
-      `SELECT branch, commit_hash, main_module, assets, asset_count, deployed_at
+      `SELECT branch, commit_hash, main_module, asset_deployment_id, deployed_at
        FROM deployments ORDER BY deployed_at DESC`,
     )
     .toArray()
-
-  const deployments = rows.map((r) => {
-    const legacyAssets = JSON.parse((r.assets as string) || "{}")
-    return {
-      branch: r.branch as string,
-      commit_hash: r.commit_hash as string,
-      main_module: r.main_module as string,
-      has_assets: Number(r.asset_count ?? 0) > 0 || Object.keys(legacyAssets).length > 0,
-      deployed_at: new Date(r.deployed_at as number).toISOString(),
-    }
-  })
+  const deployments = rows.map((r) => ({
+    branch: r.branch as string,
+    commit_hash: r.commit_hash as string,
+    main_module: r.main_module as string,
+    has_assets: Boolean(r.asset_deployment_id),
+    deployed_at: new Date(r.deployed_at as number).toISOString(),
+  }))
 
   return jsonResponse(deployments)
 }

package/src/space/durable-object.ts

@@ -6,24 +6,17 @@ import {
   buildBranchDeployment,
   handleDeployCommand,
   type BranchDeploymentBundle,
+  type DeploymentRuntimeConfig,
   type DeployContext,
+  type SpaceDeploymentResult,
 } from "./deploy-engine"
 import { globInfos, readDirInfos, toFileInfo } from "./fileinfo"
-import {
-  handleAssetRequest,
-  buildAssetManifest,
-  createMemoryStorage,
-  type AssetConfig,
-  type AssetManifest,
-  type AssetStorage,
-} 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,
@@ -100,41 +93,9 @@ interface DeploymentRow {
   commitHash: string
   mainModule: string
   modules: Record<string, string | Record<string, unknown>>
-  legacyAssets: Record<string, string | ArrayBuffer>
-  assetDeploymentId: string
-  assetCount: number
-  assetConfig: AssetConfig
   compatibilityDate: string
 }
 
-type SerializedAsset = string | { base64: string }
-
-function deserializeAssets(
-  assets: Record<string, SerializedAsset>,
-): Record<string, string | ArrayBuffer> {
-  return Object.fromEntries(
-    Object.entries(assets).map(([path, content]) => [
-      path,
-      typeof content === "string"
-        ? content
-        : exactArrayBuffer(base64ToBytes(content.base64)),
-    ]),
-  )
-}
-
-function exactArrayBuffer(bytes: Uint8Array): ArrayBuffer {
-  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer
-}
-
-function base64ToBytes(value: string): Uint8Array {
-  const binary = atob(value)
-  const bytes = new Uint8Array(binary.length)
-  for (let index = 0; index < binary.length; index++) {
-    bytes[index] = binary.charCodeAt(index)
-  }
-  return bytes
-}
-
 // 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
@@ -147,22 +108,10 @@ const isReservedPath = isReservedSpacePath
 // 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: AssetManifest
-  storage: AssetStorage
-  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.
    *
@@ -218,11 +167,8 @@ export class SpaceDO extends DurableObject<Env>
         commit_hash TEXT NOT NULL,
         main_module TEXT NOT NULL,
         modules TEXT NOT NULL,
-        assets TEXT NOT NULL DEFAULT '{}',
         asset_deployment_id TEXT NOT NULL DEFAULT '',
-        asset_count INTEGER NOT NULL DEFAULT 0,
-        asset_config TEXT NOT NULL DEFAULT '{}',
-        compatibility_date TEXT NOT NULL DEFAULT '',
+        compatibility_date TEXT NOT NULL,
         deployed_at INTEGER NOT NULL
       );
       CREATE TABLE IF NOT EXISTS deployment_assets (
@@ -236,13 +182,6 @@ export class SpaceDO extends DurableObject<Env>
       );
     `)
 
-    // 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_deployment_id TEXT NOT NULL DEFAULT ''`) } catch {}
-    try { this.ctx.storage.sql.exec(`ALTER TABLE deployments ADD COLUMN asset_count INTEGER NOT NULL DEFAULT 0`) } 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" })
@@ -634,7 +573,6 @@ export class SpaceDO extends DurableObject<Env>
         }
       }
       await this.deleteSpilledObjects()
-      this.assetCache.clear()
       await this.ctx.storage.deleteAll()
       this.initializationPromise = null
     })
@@ -1109,7 +1047,12 @@ export class SpaceDO extends DurableObject<Env>
    * 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, revision?: string): Promise<unknown> {
+  async deploy(
+    branch: string,
+    appRoot?: string,
+    revision?: string,
+    runtimeConfig?: DeploymentRuntimeConfig,
+  ): Promise<SpaceDeploymentResult> {
     await this.ensureInit()
     return this.lane(async () => {
       // The deploy engine reads the full branch tree, so ensure the Artifacts
@@ -1123,6 +1066,7 @@ export class SpaceDO extends DurableObject<Env>
           branch,
           ...(appRoot ? { appRoot } : {}),
           ...(revision ? { revision } : {}),
+          ...(runtimeConfig ? { runtimeConfig } : {}),
         }),
       })
       const ctx: DeployContext = {
@@ -1135,14 +1079,10 @@ export class SpaceDO extends DurableObject<Env>
       const res = await handleDeployCommand(ctx, "deploy", fakeRequest)
       const data = await res.json() as Record<string, unknown>
       if (typeof data.error === "string") throw new Error(data.error)
-      this.assetCache.clear()
-      const deploymentId = data.branch as string
-      data.preview_url =
-        `/space/${this.spaceName}/preview/${encodeURIComponent(deploymentId)}/`
 
       if (!revision) await this.backend.push(branch)
 
-      return data
+      return spaceDeploymentResult(data)
     })
   }
 
@@ -1150,6 +1090,7 @@ export class SpaceDO extends DurableObject<Env>
     branch: string,
     appRoot?: string,
     revision?: string,
+    runtimeConfig?: DeploymentRuntimeConfig,
   ): Promise<BranchDeploymentBundle> {
     await this.ensureInit()
     await this.materializeAll()
@@ -1162,6 +1103,8 @@ export class SpaceDO extends DurableObject<Env>
       branch,
       appRoot,
       revision,
+      undefined,
+      runtimeConfig,
     )
   }
 
@@ -1180,7 +1123,6 @@ export class SpaceDO extends DurableObject<Env>
       assetPrefix: spaceR2Prefix(this.spaceName),
     }
     const res = await handleDeployCommand(ctx, "undeploy", fakeRequest)
-    this.assetCache.clear()
     return res.json()
   }
 
@@ -1203,6 +1145,7 @@ export class SpaceDO extends DurableObject<Env>
       sql: this.ctx.storage.sql,
       git: this.git,
       fs: this.overlay,
+      assetPrefix: spaceR2Prefix(this.spaceName),
     }
     const res = await handleDeployCommand(ctx, "get_deployment", fakeRequest)
     return res.json()
@@ -1228,13 +1171,12 @@ export class SpaceDO extends DurableObject<Env>
     return { fileCount, directoryCount, totalBytes }
   }
 
-  // ── Deployment row reader (shared by servePreview + DB-viewer) ──
+  // ── Deployment row reader ──
 
   private readDeployment(branch: string): DeploymentRow | null {
     const rows = this.ctx.storage.sql
       .exec(
-        `SELECT branch, commit_hash, main_module, modules, assets,
-                asset_deployment_id, asset_count, asset_config, compatibility_date
+        `SELECT branch, commit_hash, main_module, modules, compatibility_date
          FROM deployments WHERE branch = ?`,
         branch,
       )
@@ -1246,17 +1188,11 @@ export class SpaceDO extends DurableObject<Env>
       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>>,
-      legacyAssets: deserializeAssets(
-        JSON.parse((r.assets as string) || "{}") as Record<string, SerializedAsset>,
-      ),
-      assetDeploymentId: (r.asset_deployment_id as string) || "",
-      assetCount: Number(r.asset_count ?? 0),
-      assetConfig: JSON.parse((r.asset_config as string) || "{}") as AssetConfig,
-      compatibilityDate: (r.compatibility_date as string) || FALLBACK_COMPATIBILITY_DATE,
+      compatibilityDate: r.compatibility_date as string,
     }
   }
 
-  // ── Preview serving via Dynamic Workers ─────────────────────────
+  // ── App serving via Dynamic Workers ─────────────────────────────
   //
   // Architecture (matches Cloudflare's Durable Object Facets docs example):
   //
@@ -1264,10 +1200,8 @@ export class SpaceDO extends DurableObject<Env>
   //     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.
+  //     `serveApp` loads the user's worker via the Worker Loader, extracts the
+  //     App class, and hosts it as a Facet keyed `app:<branch>`.
   //   - 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
@@ -1277,23 +1211,12 @@ export class SpaceDO extends DurableObject<Env>
   //     `App` that adds `__vibeInspectListTables` / `__vibeInspectRead`
   //     / `__vibeWipe`. The subclass shares the same `ctx.storage`.
 
-  async servePreview(branch: string, request: Request): Promise<Response> {
+  async serveApp(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 (dep.assetCount > 0 || Object.keys(dep.legacyAssets).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)
@@ -1308,73 +1231,6 @@ export class SpaceDO extends DurableObject<Env>
     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.assetDeploymentId || 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
-    }
-
-    let manifest: AssetManifest
-    let storage: AssetStorage
-    if (dep.assetDeploymentId) {
-      const bucket = this.env.WORKSPACE_R2
-      if (!bucket) throw new Error("Static preview requires the WORKSPACE_R2 binding")
-      const rows = this.ctx.storage.sql
-        .exec(
-          `SELECT path, r2_key, content_type, etag
-           FROM deployment_assets WHERE deployment_id = ?`,
-          dep.assetDeploymentId,
-        )
-        .toArray()
-      const keys = new Map<string, string>()
-      manifest = new Map()
-      for (const row of rows) {
-        const path = row.path as string
-        keys.set(path, row.r2_key as string)
-        manifest.set(path, {
-          contentType: (row.content_type as string | null) ?? undefined,
-          etag: row.etag as string,
-        })
-      }
-      storage = {
-        async get(pathname) {
-          const r2Key = keys.get(pathname)
-          if (!r2Key) return null
-          return (await bucket.get(r2Key))?.body ?? null
-        },
-      }
-    } else {
-      manifest = await buildAssetManifest(dep.legacyAssets)
-      storage = createMemoryStorage(dep.legacyAssets)
-    }
-    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
@@ -1399,7 +1255,7 @@ export class SpaceDO extends DurableObject<Env>
       // 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,
+      compatibilityDate: dep.compatibilityDate,
       // 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.
@@ -1474,40 +1330,12 @@ export class SpaceDO extends DurableObject<Env>
     return { ok: true }
   }
 
-  // ── HTTP handler: preview serving + internal deploy commands ────
+  // ── 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")
+    const cmd = new URL(request.url).searchParams.get("cmd")
     if (cmd && ["deploy", "get_deployment", "list_deployments", "undeploy"].includes(cmd)) {
       const deployCtx: DeployContext = {
         sql: this.ctx.storage.sql,
@@ -1523,39 +1351,6 @@ export class SpaceDO extends DurableObject<Env>
   }
 }
 
-// ─── 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 {
@@ -1567,9 +1362,6 @@ function facetNameForApp(branch: string): string {
 /** 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",
@@ -1610,6 +1402,29 @@ function byteLength(content: string): number {
   return new TextEncoder().encode(content).byteLength
 }
 
+function spaceDeploymentResult(data: Record<string, unknown>): SpaceDeploymentResult {
+  if (
+    typeof data.branch !== "string" ||
+    typeof data.commit_hash !== "string" ||
+    typeof data.main_module !== "string" ||
+    typeof data.has_assets !== "boolean" ||
+    typeof data.compatibility_date !== "string" ||
+    typeof data.deployed_at !== "string" ||
+    !(typeof data.asset_root === "string" || data.asset_root === null)
+  ) {
+    throw new Error("Invalid deployment result")
+  }
+  return {
+    branch: data.branch,
+    commit_hash: data.commit_hash,
+    main_module: data.main_module,
+    has_assets: data.has_assets,
+    compatibility_date: data.compatibility_date,
+    deployed_at: data.deployed_at,
+    asset_root: data.asset_root,
+  }
+}
+
 // ─── Helpers ────────────────────────────────────────────────────────────────
 
 interface PatchEdit {

package/src/space/workspace-port.ts

@@ -1,3 +1,9 @@
+import type {
+  BranchDeploymentBundle,
+  DeploymentRuntimeConfig,
+  SpaceDeploymentResult,
+} from "./deploy-engine";
+
 /**
  * The production Workspace contract a Space must satisfy.
  *
@@ -234,11 +240,22 @@ export interface SpaceControlPort {
  * and only an explicit deploy brings an app into existence.
  */
 export interface SpaceAppPort {
-  deploy(branch: string, appRoot?: string, revision?: string): Promise<unknown>;
+  deploy(
+    branch: string,
+    appRoot?: string,
+    revision?: string,
+    runtimeConfig?: DeploymentRuntimeConfig,
+  ): Promise<SpaceDeploymentResult>;
   undeploy(branch: string): Promise<unknown>;
   listDeployments(): Promise<unknown>;
   getDeployment(branch: string): Promise<unknown>;
-  servePreview(branch: string, request: Request): Promise<Response>;
+  getDeploymentBundle(
+    branch: string,
+    appRoot?: string,
+    revision?: string,
+    runtimeConfig?: DeploymentRuntimeConfig,
+  ): Promise<BranchDeploymentBundle>;
+  serveApp(branch: string, request: Request): Promise<Response>;
   listAppTables(branch: string): Promise<unknown>;
   queryAppTable(branch: string, table: string, opts?: unknown): Promise<unknown>;
   wipeAppDatabase(branch: string): Promise<{ ok: true }>;