[Root] Frontstage 代码区块浏览器运行时编排与加载体验

[JAVA-LW]

Issue 元数据

• 计划类型：Issue Tree
• 树角色：Root（唯一计划、进度与用户验收真值）
• 分级：grade:g4
• 任务形态：hybrid-foundation
• 标签：plan:tree、parent-issue、grade:g4、phase:implementation、area:runtime、area:frontend、area:backend、area:api、contract、risk:high
• Delivery issues：[Delivery] 代码区块运行阶段与超时语义真实可区分 #1383、[Delivery] Frontstage 首屏区块按优先级有界加载运行 #1384、[Delivery] 页面短期返回即时恢复并安全释放 Worker 资源 #1385、[Delivery] Root #1382 运行时验收收口与真实多区块场景 #1386（均已集成）；[Delivery] 权威源码身份与同会话内容寻址结果缓存 #1401、[Delivery] 刷新后复用 CompiledBlockArtifact 并安全冷启动 #1402（本次已批准增量）
• 实现输入：[Root] Frontstage TSX 代码区块作者平台：OpenAPI 源码、区块联动与运行工作台 #1393 最终 RouteKey runtime commit 77fa65a4d 已进入 origin/beta@b201cfca4；新 Packet 已获准启动

最终结果

Frontstage 代码区块继续在浏览器 Worker 中编译并受限执行，同时用同一份源码身份消除无意义重复工作：

同会话返回，L1 identity 命中
  → 内存 BlockResult → present
  → 0 block-code request / 0 Worker / 0 platform compile / 0 API effect / 0 main()

刷新或重新打开，L1 丢失、L2 artifact 命中
  → 新 Worker 装载 CompiledBlockArtifact
  → 0 platform transform
  → API effect + main(ctx) + schema_validate + present 仍重新执行

L1/L2 都未命中
  → source_fetch → worker_boot → compile → api_wait/main → schema_validate → present

这里缓存的是两个不同阶段：

• L1 是“本次运行结果”的会话内存缓存，解决 A → B → A 重复执行。
• L2 是“整份源码转换后的程序产物”缓存，解决刷新后重复 TypeScript/TSX transform。
• 不分析哪些源码行静态/动态，不缓存已渲染组件，不改变 BlockModule.main(ctx)。动态数据永远在本次 Worker 运行时重新获取。
• L1 命中仍可能重新挂载 React/Schema DOM；目标是零用户代码执行，不是让路由组件永不 render。
• L2 的 compile = 0 指平台 transform 被跳过；浏览器 JavaScript 引擎仍可能解析/JIT 转换后程序，不承诺引擎字节码复用。

现状、证据与关键决策

已集成基线

• [Delivery] 代码区块运行阶段与超时语义真实可区分 #1383 已集成 Worker init → ready → run 生命周期、预算与阶段失败语义。
• [Delivery] Frontstage 首屏区块按优先级有界加载运行 #1384 已集成可视区优先、有界并发、dormant source、取消与 stale result 隔离。
• [Delivery] 页面短期返回即时恢复并安全释放 Worker 资源 #1385 已集成页面返回 snapshot、Visibility 与 Worker/resource cleanup。
• [Delivery] Root #1382 运行时验收收口与真实多区块场景 #1386 已完成旧 Root 的 QA-only contract/fixture 修复。
• 旧 Root 冻结 assembly 5796a2a7b9527428b5af602daa09a8d6457ede60 已集中 QA 通过并合入 beta@61ed1ef5b；证据见 [Root] Frontstage 代码区块浏览器运行时编排与加载体验 #1382 评论。
• 当前代码的 block-code GET/PUT 位于 api/apps/api-server/src/routes/frontstage/mod.rs，API Client 位于 web/packages/api-client/src/console/frontstage.ts。
• 当前 page-runtime 已能在同一进程复用 compiled source object，但没有持久化 CompiledBlockArtifact contract、runtime_fingerprint 或 IndexedDB artifact cache。
• 当前仓库尚无 source_sha256；页面返回 snapshot 仍沿用后台 revalidate/TTL 内容有效性语义。

2026-07-22 Superseding Delta

• 原 AC-011“返回后后台 revalidate”被替换：同 identity 且无显式 dependency event 时不请求源码、不重跑；源码保存、Signal/input、手动重试或 LRU miss 才运行受影响实例。
• 原 AC-013 中“TTL 表示内容失效”被删除；资源 dispose/crash/监听器无泄漏仍保留为回归。容量与保洁由 byte-weighted LRU 管理，时间经过本身不改变内容身份。
• 原“IndexedDB 编译产物缓存”和“后端 hash contract”为非目标的限制已由用户明确解除。
• 新增后端派生 source_sha256 contract，但不新增数据库列；持久化源码仍是唯一真值。
• L2 默认不加密，前提是只写源码派生 artifact 和管理 metadata。它不是源码 at-rest secrecy 边界；运行时 token、headers、API 数据和用户状态绝不进入。
• Compiler/Executor Worker 拆分没有当前证据支持；先记录各阶段，再决定是否需要重新 problem-framing。

总范围、权限与非目标

范围内

• 保留已集成的 Worker 生命周期、调度、Visibility、取消、错误与资源回收行为。
• GET/PUT block-code 返回后端对实际持久化源码计算的 source_sha256；DTO/API Client 字段保持同名。
• L1 以内存中的最近成功 BlockResult 为值，以区块实例、runtime_fingerprint、source_sha256 与显式 dependency_generation 为身份。
• 源码保存、显式 Signal/input、手动重试、LRU 淘汰/缺失的定向失效和旧结果隔离。
• L2 以 actor/workspace namespace + runtime_fingerprint + source_sha256 持久化可序列化 CompiledBlockArtifact。
• actor/workspace 隔离、登出清理、认证启动清理、byte-weighted LRU、损坏/quota/IndexedDB 不可用时冷路径恢复。
• 分阶段记录 source_fetch / worker_boot / compile / api_wait / main / schema_validate / present，区分 L1 hit、L2 hit 与 miss。
• 桌面端与 390px 真实浏览器验收；性能报告阶段实测，不预先承诺固定倍数。

已授权动作

• Root 的本次确认覆盖 [Delivery] 权威源码身份与同会话内容寻址结果缓存 #1401、[Delivery] 刷新后复用 CompiledBlockArtifact 并安全冷启动 #1402 与正文 P8～P13；Delivery 不逐个重复请求批准。
• 可修改 Frontstage block-code 后端 route/DTO、API Client、web/packages/page-runtime、Frontstage runtime/cache/auth 最近边界与测试。
• 已从 origin/beta@b201cfca4 创建隔离 assembly；主工作树现有 JSX Studio 未提交修改不得作为输入。
• 全部产品与 fixture Packet 装配完成后冻结一次 assembly，只启动一个 fresh QA 集中验证。

非目标

• 持久化 token、请求头、API Response、BlockResult、context、outputs、logs、effects、interface calls、Signal 值或用户运行状态。
• 源码静态/动态行分析、静态组件产物、DOM/React tree 持久化，或新增 load/render/loading / StaticBlockModule contract。
• 数据库 hash 列、服务端编译/执行、后端 artifact storage、跨设备同步。
• Service Worker、SharedWorker、跨标签页运行状态共享或无事件的外部写入侦测。
• 浏览器原生 closure/JIT bytecode 持久化。
• 默认加密、密钥管理；如果源码派生产物需要 at-rest secrecy，必须重新决策。
• Compiler/Executor Worker 拆分；只有阶段证据证明必要时才重新进入 problem-framing。
• 修改 [Root] Frontstage TSX 代码区块作者平台：OpenAPI 源码、区块联动与运行工作台 #1393 的接口调用、Signal、Draft Run 或作者编程 contract。
• 页面布局算法与 建立 Frontstage 可演进区块布局内核与连续碰撞交互 #1376。

Root 验收点账本

已集成回归与被取代语义

编号	可观察结果	证据 / 负责 Delivery	状态
AC-001	简单 Demo 冷/热启动不误超时	#1383 + Root QA	已集成回归
AC-002	用户运行预算只在 Worker ready 后开始	#1383 + controlled timer	已集成回归
AC-003	启动、编译、执行、effect、schema、crash 可区分	#1383	已集成回归
AC-004	明确无界循环预拒绝；未结算运行由 runtime timeout 终止	#1383/#1386 + browser fixture	已集成回归
AC-005	10 个区块最多同时执行 2 个 Worker	#1384	已集成回归
AC-006	可视区优先于临近和离屏区块	#1384	已集成回归
AC-007	离屏区块进入范围前不请求源码、不创建 Worker	#1384	已集成回归
AC-008	页面/源码/Props/context 变化取消旧任务，旧结果不回写	#1384	已集成回归
AC-009	多区块加载期间页面交互可用	#1384 + browser	已集成回归
AC-010	短期离开再返回立即展示上次成功结果	#1385	已集成回归，身份语义由 AC-018 收紧
AC-011	原“返回后后台 revalidate”	#1385	被 AC-018/019 取代：同 identity 不重跑
AC-012	hidden 暂停新任务，visible 恢复	#1385	已集成回归
AC-013	原“TTL、dispose、异常后无 Worker 泄漏”	#1385	资源无泄漏保留；TTL 内容有效性被 AC-020 取代
AC-014	缓存丢失或 Worker 回收后正确冷启动	#1385	已集成回归，并扩展为 AC-023
AC-015	紧凑 Loading/Error 在桌面与 390px 稳定	Root QA	已集成回归
AC-016	前端仍是静态产物，源码仍在浏览器 Worker 执行	Root QA	已集成回归

本次增量

编号	可观察结果	证据	负责 Delivery	状态
AC-017	GET/PUT 返回实际持久化源码的 source_sha256；持久化字节变化进入新身份	后端 route/DTO + API Client contract fixture	#1401	green
AC-018	同实例、runtime、hash、dependency generation 的 A → B → A：block-code 请求 0、Worker 0、platform compile 0、API effect 0、main() 0	route-return counters + Playwright	#1401	green
AC-019	源码保存、显式 Signal/input、手动重试或 L1 miss 只执行受影响实例一次，旧 request/run 不回写	generation/stale/LRU fixture	#1401	green
AC-020	L1 无 TTL 内容失效；actor/workspace/page/tab/block 不串结果；登出清理原 actor namespace	fake timer + namespace/logout fixture	#1401	green
AC-021	刷新后同 fingerprint/hash 的 L2 命中使平台 transform 为 0，但新 Worker、动态 API 与 main() 重新执行	reload + changing API fixture	#1402	green
AC-022	IndexedDB 只含源码派生 artifact 与管理 metadata；不含任何运行数据、凭证或 sensitive canary	storage inspection/canary scan	#1402	green
AC-023	fingerprint/hash mismatch、artifact 损坏、quota、浏览器淘汰或 IndexedDB 不可用均能冷编译恢复，不阻断页面	recovery controlled negative	#1402	green
AC-024	L1/L2/miss 均记录七阶段；数据足以判断 compile 占比，未重新批准前不拆 Compiler/Executor Worker	instrumentation matrix + browser timing	#1401/#1402	green

Delivery Map

Delivery	纵向结果	结算 Root AC	依赖	状态 / 集成证据
#1383	运行阶段、预算和失败语义真实可区分	AC-001～004	无	integrated；beta@61ed1ef5b
#1384	首屏按优先级有界加载运行	AC-005～009	#1383	integrated；beta@61ed1ef5b
#1385	页面返回 snapshot、Visibility 与资源安全释放	AC-010～014	#1383/#1384	integrated；SWR/TTL 内容语义被本次 delta 取代
#1386	旧 Root QA contract/浏览器 fixture 修复	历史 AC-004/Root QA	#1383～1385	integrated；历史验收证据
#1401	权威源码 identity + 同会话 L1 零执行	AC-017～020、024	#1393 stable baseline	integrated；betaa6d76
#1402	IndexedDB artifact + Worker 直接装载执行	AC-021～024	#1401	integrated；betaa6d76

新增执行顺序固定：#1393 stable baseline → #1401（P8 → P9 → P10）→ #1402（P11 → P12 → P13）。既有 #1383～#1386 不 reopen、不重复实现。

Control Ledger

• 最终结果、硬约束与未结算 Root AC：保持浏览器 Worker 与 BlockModule.main(ctx)；AC-017～024 已由 cycle 2 QA 全部结算 green；运行数据永不持久化；L1 同身份零执行，L2 只跳过平台 transform。
• 历史 integrated baseline：beta@61ed1ef5b，旧 Root QA 已 PASS。
• frozen input / protected baseline：origin/beta@b201cfca49adbcb0b1728ff2c4d398a5c83ba27e。
• [Root] Frontstage TSX 代码区块作者平台：OpenAPI 源码、区块联动与运行工作台 #1393 gate evidence：RouteKey runtime commit 77fa65a4d 是 frozen input 的祖先；当前脏改仅位于 JSX Studio codegen/UI，未进入 assembly。
• local assembly baseline：codex/issue-1382-content-cache-assembly@b201cfca4；worktree /home/taichuy/git/1flowbase_git_workspace/root-1382-content-cache。
• Scout evidence：
  • backend owner：api/apps/api-server/src/routes/frontstage/mod.rs 的 block-code GET/PUT；
  • API contract owner：web/packages/api-client/src/console/frontstage.ts；
  • runtime owner：page-runtime source transform/evaluator 与 Worker host/runtime/executor；
  • Frontstage owner：runtime source/session、PageCanvas/preview、auth logout 最近边界；
  • 当前缺口：无 source_sha256、runtime_fingerprint、内容寻址 L1 或 IndexedDB artifact cache；
  • 唯一只读 Scout 超过有限 inventory 时间且未返回报告，已中止；Root 用上述有界代码证据完成 baseline/path/Input SHA 核验，owner 与既定 Packet 不变。
• Work Packet Ledger：
  • P8 / committed 0fddbb5a3 / [Delivery] 权威源码身份与同会话内容寻址结果缓存 #1401：后端 source_sha256 + API Client contract；owned block-code route/DTO/最近后端测试与 api-client frontstage contract/测试；AC-017。
  • P9 / committed 009f36908 / [Delivery] 权威源码身份与同会话内容寻址结果缓存 #1401：L1 内容寻址 BlockResult cache，取消返回时 SWR/TTL 自动重跑；owned Frontstage runtime source/session/coordinator、PageCanvas/preview 最近边界与测试；AC-018～020。
  • P10 / committed c2a1a0121 / [Delivery] 权威源码身份与同会话内容寻址结果缓存 #1401：auth/query namespace、logout cleanup、七阶段观测；owned auth-store 最近入口、cache provider/query integration、instrumentation 与测试；AC-020、024。
  • P11 / committed 70d177405 + identity correction 6761a4e80 / [Delivery] 刷新后复用 CompiledBlockArtifact 并安全冷启动 #1402：可序列化 CompiledBlockArtifact、runtime_fingerprint、Worker cached-execution protocol；owned page-runtime transform/evaluator、Worker contract/host/executor、公开类型与测试；AC-021、023～024。
  • P12 / committed 1cc7bcd49 + transaction correction d94bc01a4 / [Delivery] 刷新后复用 CompiledBlockArtifact 并安全冷启动 #1402：actor/workspace IndexedDB namespace + byte-weighted LRU；owned Frontstage artifact persistence adapter、auth cleanup integration、fake IDB tests；AC-022～023。
  • P13 / committed 73f45c685 + fingerprint correction c95965b0c + QA fix c4ed23dbd / [Delivery] 刷新后复用 CompiledBlockArtifact 并安全冷启动 #1402：L2 页面运行整合、恢复与性能 fixture；owned Frontstage runtime host/factory/session、browser fixtures 与 instrumentation；AC-021～024。
• 写集合与执行顺序：P8 → P9 → P10 → P11 → P12 → P13；共享 contract、runtime source/session 与 Worker protocol 串行装配。
• assembled commits 与冲突：0fddbb5a3（P8）、009f36908（P9）、c2a1a0121（P10）、70d177405 + 6761a4e80（P11）、1cc7bcd49 + d94bc01a4（P12）；P11 hash owner 与 P12 transaction completion review findings 均已修正；无冲突、73f45c685 + c95965b0c + c4ed23dbd（P13/QA fix）；无冲突；assembly re-frozen。
• Test Batch：
  • authenticity/controlled negative：源码字节变化、旧 request 晚到、Signal/input 连续变化、跨 namespace、LRU 淘汰、旧 fingerprint、artifact 篡改、quota/IDB failure、浏览器清空、登出/重登。
  • sensitive canary：token、Authorization/CSRF header、API response、BlockResult、logs/effects/interface payload 注入唯一 canary，运行后扫描当前 IndexedDB namespace 全部 key/value。
  • targeted：后端 block-code contract、api-client、page-runtime transform/evaluator/Worker protocol、Frontstage runtime/cache/auth/IndexedDB。
  • source integration：相关 Rust fmt/targeted Cargo；page-runtime/Frontstage targeted tests；前端 build。重型后端门禁延后 GitHub Actions。
  • browser：冻结 assembly 独立端口；桌面与 390px 验证 A → B → A、冷运行 → 刷新 L2 hit → API 新值、multi-block 定向失效与所有 recovery 场景。
  • 执行时机：全部产品与 fixture Packet 装配后冻结 SHA，只由一个 fresh QA 执行一次集中 Test Batch；产物落到 tmp/test-governance/。
• Observation counters：packets=6、needs_split=0、assembly_conflicts=0、agent_contexts=4（Root + aborted Scout + D4 dev + D5 dev）、validation_runs=4、duplicate_evidence_runs=0、qa_cycles=2。
• 剩余验收风险：零请求 L1 无法发现未接入 invalidation 的外部写入；源码硬编码字面量会进入未加密 artifact；浏览器 JS 引擎 parse/JIT 成本不会被 L2 消除；IndexedDB quota/eviction 只能 best-effort。
• 活动 agent、worktree、进程与端口：开发尚未分发；唯一 assembly worktree 如上；无新增服务/端口；当前主工作树用户 JSX Studio 未提交修改不进入输入。
• 已知阻塞 / 外部依赖：无；[Root] Frontstage TSX 代码区块作者平台：OpenAPI 源码、区块联动与运行工作台 #1393 runtime gate 已由 frozen beta ancestry 证据满足。
• frozen assembly：c4ed23dbd841ff5ad6b9871ed58521f941649df6；QA PASS；protected baseline：betaa6d765c5bba5bfa8ee3565cc39c41e748364；下一可控结果：用户最终验收 Root。

验证、回滚与资源边界

• Done 只由 AC-017～024 的集中证据结算；Issue、Packet、commit 数或主观“变快”不算完成。
• 性能报告必须分别给出 L1 hit、L2 hit、miss 的阶段计数与耗时；不预设固定加速倍数。
• 同一时刻最多一个 Cargo/frontend build/重型测试进程；完整后端重型门禁按项目规则进入 GitHub Actions。
• 页面结论使用 Playwright，在 assembly 独立端口验证桌面与 390px。
• 回滚优先关闭 L1/L2 消费并恢复已验证冷路径；source_sha256 是无数据库迁移的派生响应字段；L2 IndexedDB schema/namespace 可整库删除，不影响源码与用户数据。
• 默认不加密已获批准，但缓存不是安全边界；如果威胁模型要求源码派生产物 at-rest secrecy，停止而非临时加密。
• byte budget 的具体默认值属于实现内可逆参数；必须有 hard cap、按序列化字节计量与 deterministic LRU fixture，不把 TTL 当正确性机制。

停止与重构条件

• [Root] Frontstage TSX 代码区块作者平台：OpenAPI 源码、区块联动与运行工作台 #1393 最终 contract 改变 block source identity、BlockModule.main(ctx)、Signal/interface ownership 或使当前 Packet owner/写集合失效。
• source_sha256 无法由后端实际持久化源码派生，或必须新增数据库真值/migration。
• 零请求命中被要求兼容无 invalidation contract 的外部写入。
• artifact 无法在不携带 token、headers、API 数据、BlockResult 或用户运行状态的前提下序列化执行。
• 正确性需要源码静态/动态分析、持久化组件/数据结果、加密/密钥 contract 或 Compiler/Executor Worker 拆分。
• 任一 Packet 无法收敛到单一结果与明确写集合，出现未批准 Delivery，或同一根因集中 QA 第二次失败。
• 资源接近项目红线、外部状态不安全，或完成需要新的授权。

生命周期

• 当前阶段：phase:user-acceptance。
• 实现状态：P8～P13 全部装配，第一轮 QA FAIL 后的单批 fix 已装配，assembly 重新冻结为 c4ed23dbd841ff5ad6b9871ed58521f941649df6，等待新的唯一 fresh QA。
• 执行顺序：Baseline Verify → Build P8～P13 → Freeze Assembly → One Fresh QA → User Acceptance。
• Root 关闭条件：AC-001～016 保持回归，AC-017～024 全部有证据，最终 QA 通过，结果合入 protected baseline，并由用户完成最终验收。