create-windy 0.6.12 → 0.6.14

package/template/docs/architecture/ai-runtime.md

@@ -1,14 +1,14 @@
 # Windy AI Runtime 架构
 
-更新时间：2026-07-31。
+更新时间：2026-08-27。
 
 状态：架构已确认，文本 Agent、Document AI、批量 Speech/ASR 与受控 Vision Artifact
 切片已实现。当前包含 Module AI Operation
 注册、Guarded Run facade、短时 Execution Grant、受限 Tool Host、OpenAI-compatible
 Provider、canonical HTTP/SSE、取消、cursor 重放和单副本有界 SQLite Store。未配置
-Provider 时仍安全拒绝。真实业务 Run 已在内部使用 ADK 2.5 Runner、Session、LlmAgent
-和 Event，并把事件转换为既有 canonical signal。ADK Workflow、LiteLLM 多 Provider
-路由和 PostgreSQL 多副本 Store 尚未实现。Document AI 已提供独立
+Provider 时仍安全拒绝。真实业务 Run 由 Windy Direct OpenAI-compatible Engine 执行，
+并直接产生 canonical signal。持久 Session/Workflow、LiteLLM 多 Provider 路由和
+PostgreSQL 多副本 Store 尚未实现。Document AI 已提供独立
 Server、授权 ArtifactRef、结构化页级结果、本地/内网 Adapter 契约，以及搜索型 PDF
 等派生文件的受治理 Output Artifact producer 协议；项目 composition 尚未接线，不能
 视为生产可用。Speech 已提供批量转写、归一化、VAD/时间戳契约、稳定分段和结果
@@ -22,20 +22,21 @@ Windy 为生成项目提供可选的 AI Runtime。它统一治理模型 Deployme
 
 首期目标：
 
-- 使用 Google ADK 承载 Agent、Workflow、Session、Eval 和开发调试；
+- 使用 Windy Agent Harness 承载受治理的 Agent Loop，并逐步增加持久 Session、Workflow
+  与 Eval；
 - 使用自托管 LiteLLM Proxy 管理多个 LLM/VLM Provider；
 - 支持 DeepSeek、GLM、Kimi、Qwen 及本地或内网 OpenAI-compatible 模型；
 - 支持文本 LLM/VLM 的 canonical SSE 流式传输；
 - 支持本地或云端 OCR、文档解析、ASR、TTS 和 AI Dictation；
 - 支持完全离线、内网私有化和受控公网三种部署环境；
-- 业务 Module 只依赖稳定 Operation，不依赖 ADK、LiteLLM、模型名或 Provider SDK。
+- 业务 Module 只依赖稳定 Operation，不依赖 Engine、LiteLLM、模型名或 Provider SDK。
 
 首期不包含腾讯混元。未列出的 Provider 通过 Deployment Registry 和 Adapter 扩展，不扩充业务 Interface。
 
 ## 核心决策
 
 1. Agent Runtime 是 Windy 的官方可选底座能力，不是每个业务 Module 自行实现的功能。
-2. Agent Server 独立部署，首期使用 Python ADK；ADK 只属于内部 Implementation。
+2. Agent Server 独立部署，使用 Windy Direct Engine；Engine 只属于内部 Implementation。
 3. 首个文本切片由 Agent Server 内置 OpenAI-compatible Adapter；需要多 Provider
    路由、fallback 与集中限流时，再引入独立自托管 LiteLLM Proxy。
 4. OCR 和文档解析由独立 Document AI Server 执行，不放入 Agent Server 或 LiteLLM。
@@ -57,9 +58,9 @@ Windy Server
         ├── Agent Tool Host
         └── 短时 Execution Grant
               │
-              ├── Agent Server（Python + ADK）
-              │       ├── Prompt / Workflow / Session / Eval
-              │       └── canonical SSE / Live WebSocket
+              ├── Agent Server（Python + Windy Direct Engine）
+              │       ├── Model / Tool Loop / Usage / Cancel
+              │       └── canonical SSE
               │                │
               │                ▼
               │          LiteLLM Proxy
@@ -96,7 +97,7 @@ Windy Server
 
 不拥有：
 
-- ADK Session 或 Workflow 实现；
+- Agent Session 或 Workflow 实现；
 - Provider API Key 明文；
 - LiteLLM 路由内部状态；
 - OCR、ASR、TTS 模型进程；
@@ -106,12 +107,11 @@ Windy Server
 
 拥有：
 
-- ADK Runner、Workflow、Session、Checkpoint、Eval；
+- Direct Model/Tool Loop 与 Engine Signal；
 - Agent、Workflow 和 Prompt Release；
 - Run 生命周期、取消、恢复和 canonical event；
-- ADK Event 到 Windy Event 的转换；
 - Agent Step、Prompt Version、Tool Call 和模型 attempt 的关联；
-- 开发环境 ADK Web；
+- 主站 Runtime Report 与 Trajectory 所需的安全投影；
 - 实时 Agent 会话编排。
 
 Agent Server 不直接访问业务 Repository。模型产生 Tool Call 只表示执行意图；每次真实 Tool 执行都必须回到 Windy Tool Host，重新检查当前 Feature、License、Permission 和数据范围。
@@ -137,7 +137,8 @@ agent.vision
 speech.dictation.polish
 ```
 
-ADK 和 LiteLLM 不同时维护两套路由或 fallback。ADK 决定运行哪个 Agent 或 Step，LiteLLM 决定该 Step 落到哪个模型 Deployment。
+Windy Harness 和 LiteLLM 不同时维护两套路由或 fallback。Harness 决定运行哪个 Operation
+或 Step，LiteLLM 只在启用后决定该 Step 落到哪个模型 Deployment。
 
 ### Document AI Server
 
@@ -190,7 +191,7 @@ Document、Speech 与 Embedding Interface 已分别由 `./document`、`./speech`
 npm Module 数量与部署进程数量是两个不同维度。Windy Server、Agent Server、
 Document AI Server 和 Speech Server 仍独立部署：它们具有不同的协议、资源和故障域；
 业务侧则只学习一个稳定入口。`ai-client` 内部通过 Agent、Document、Speech Adapter
-隔离远端 Implementation，不能把 ADK、LiteLLM、PaddleOCR 或 Provider SDK 类型暴露给业务。
+隔离远端 Implementation，不能把 Engine、LiteLLM、PaddleOCR 或 Provider SDK 类型暴露给业务。
 
 ### Agent Interface
 
@@ -214,7 +215,8 @@ interface AgentRun<Output> {
 }
 ```
 
-业务只知道 Operation Key、类型化输入输出、幂等键、canonical event 和终态结果，不知道 Provider、模型名、Prompt 明文、ADK Agent 或 LiteLLM 参数。
+业务只知道 Operation Key、类型化输入输出、幂等键、canonical event 和终态结果，不知道
+Provider、模型名、Prompt 明文、Engine 私有状态或 LiteLLM 参数。
 
 ### Document Interface
 
@@ -464,6 +466,15 @@ canonical event：
 ```ts
 type AgentEvent =
   | { type: "run.started"; runId: string; sequence: number }
+  | {
+      type: "input.prepared";
+      runId: string;
+      sequence: number;
+      artifactCount: number;
+      inputModalities: readonly (
+        "text" | "image" | "audio" | "video" | "document"
+      )[];
+    }
   | { type: "output.delta"; runId: string; sequence: number; text: string }
   | {
       type: "tool.requested";
@@ -500,7 +511,12 @@ type AgentEvent =
   | { type: "run.cancelled"; runId: string; sequence: number };
 ```
 
-ADK Event、LiteLLM chunk、OpenAI response event、Provider reasoning delta 和 partial JSON 不直接向业务透传。
+`input.prepared` 是正常 Run 完成受治理输入准备后公开发送的 canonical event，不是 Agent
+Server 内部信号。SDK 必须严格校验非负 `artifactCount` 和非空、已登记的
+`inputModalities`，再按 SSE cursor 顺序交付给业务调用方。
+
+Engine Signal、LiteLLM chunk、OpenAI response event、Provider reasoning delta 和 partial
+JSON 不直接向业务透传。
 
 ### SSE 不变量
 
@@ -665,7 +681,7 @@ type DictationEvent =
 
 实时对话支持两种 Adapter：
 
-- 级联：ASR → ADK Agent/LLM → TTS；
+- 级联：ASR → Windy Agent/LLM → TTS；
 - 原生双向模型：音频/视频 ⇄ Realtime Model。
 
 客户端先向 Windy Server 创建 Live Session 并通过 Guard，再使用短时、绑定 Session 和 audience 的凭证连接 Agent Server WebSocket。Tool Call 仍回到 Windy Tool Host 二次授权。
@@ -674,23 +690,14 @@ type DictationEvent =
 
 ## Prompt、Debug 与 Trace
 
-ADK Web 只在 developer profile 启动，绑定 localhost 或受控开发网络。它不是生产
-Prompt 管理或生产 Debug 控制面。
-
-当前 Compose 使用独立 `agent-debug` profile，宿主机只发布
-`127.0.0.1:8000`。Windy 的 `canonical_debug` 是确定性 Adapter：它把用户文本交给
-project-owned 配置选择的真实文本 Operation，并通过 canonical HTTP/SSE 读取 Run、
-Tool 和终态摘要。业务 Permission、Scope、Execution Grant、Provider 与 Tool Host
-继续由正式 Server/Agent Server 管理，ADK Web 不获得 Repository、Provider Key 或内部
-Token。项目配置只包含 Operation Key 与当前启用的真实开发数据用户 ID，不能重复或扩大
-Manifest 的权限、Scope 与 Tool 列表。数据用户用于复用其成员关系和当前 Scope。开发 Wrapper
-创建的核心主体仍是 `service_adk_debug`，权限只取该用户已有权限与 Operation/allowed
-Tools 闭包的精确交集，并且只能调用 canonical Run API 与只读 debug-session GET；
-审计不会把它记录成普通用户会话。
+开发与生产观察统一使用 Windy 主站。`/admin/system/ai-runtime` 通过当前登录身份、
+`system.ai-runtime.read` 和数据范围展示 Runtime Report、Provider Attempt 与脱敏
+Trajectory；业务历史会话由 `registerAgentSessionProviders()` 提供只读投影。不存在独立
+调试站点、专用身份或第二种 Token。
 
-该 Adapter 证明真实业务执行链，不等于把另一进程内的完整 ADK Agent/Workflow 图装入
-原生 ADK Web。内部节点、Prompt 版本和 replay 若要可视化，必须通过另一个版本化协议
-显式暴露。不得把开发调试会话解释为生产授权或业务执行证据。
+Trajectory 只投影 canonical Run 的 Tool Key、审批、Usage、输入模态、Artifact 数量、失败、
+取消和终态，不展示 Prompt、chain-of-thought、完整 Tool 参数或 Provider body。完整节点图、
+Prompt 版本和 replay 必须建立在后续版本化 Session/Trace 协议上，不从当前摘要反向推断。
 
 Prompt 和 Workflow 使用：
 
@@ -708,7 +715,8 @@ published version 不可原地修改。每次 Run 固定：
 
 首期优先使用代码或 YAML、Git、Eval 和不可变 Release。只有出现非开发人员在线编辑的真实需求后，再扩展 diff、审批、回滚、fixture、route 对比和发布管理。
 
-生产 Trace 优先输出到客户本地 OTel Collector 与 Jaeger/Tempo。Windy 控制面提供脱敏 Run 摘要和受权限保护的 Trace 入口，不复制 ADK Web。
+生产 Trace 优先输出到客户本地 OTel Collector 与 Jaeger/Tempo。Windy 控制面提供脱敏 Run
+摘要和受权限保护的 Trace 入口，不复制第二套调试站点。
 
 生产默认不持久化完整 Prompt、响应、音频、图片或 Tool 参数。明文诊断需要专门 Feature、Permission、加密、脱敏、TTL 和访问审计。
 
@@ -776,13 +784,13 @@ LiteLLM 版本必须固定并通过供应链审查，客户现场禁止动态安
 ## 首期交付切片
 
 当前已完成第 1、2、4、7、8 项的批量 ASR 子集和第 5 项的受限 Tool Host 基础闭环，并交付可直接连接
-OpenAI-compatible Provider 的文本 Agent Adapter。SQLite Store 提供单副本有界持久化，
+OpenAI-compatible Provider 的 Direct Agent Engine。SQLite Store 提供单副本有界持久化，
 重启后保留终态和 cursor，但不替代后续 PostgreSQL 多副本 Store。配置 Provider 后，
-文本与 Tool Run 由 ADK Runner/Session/Event 执行；未配置 Provider 时同一 Adapter
-fail closed。开发 ADK Web 已作为 localhost-only 的受控调试入口交付，不是业务入口。
+文本与 Tool Run 由 Windy Direct Loop 执行；未配置 Provider 时
+`UnavailableEngineAdapter` fail closed。开发与运维观察统一进入主站 Trajectory。
 
 1. 定义 Agent、Document、Speech Operation 与 Module Manifest 组合校验；
-2. 建立 Python Agent Server、ADK Adapter 和 deterministic test Adapter；
+2. 建立 Python Agent Server、Direct Engine 和 deterministic test Adapter；
 3. 部署 LiteLLM Proxy，接入 DeepSeek、GLM、Kimi、Qwen 和一个本地 OpenAI-compatible Endpoint；
 4. 完成 Agent Run 创建、canonical SSE、断线恢复、取消和稳定错误；
 5. 接入一个真实 Agent Tool，验证 Feature、Permission、License、数据范围和 Audit；
@@ -793,20 +801,21 @@ fail closed。开发 ADK Web 已作为 localhost-only 的受控调试入口交
 9. 增加 VLM Artifact 输入和 `agent.vision` route（已完成图片输入；视频后续）；
 10. 验证受控公网、内网私有化和完全断网三种 profile。
 
-首期不同时实现 LangGraph Adapter、完整在线 Visual Builder、生产 ADK Web、腾讯混元或通用 GPU 调度平台。
+首期不同时实现 LangGraph Adapter、完整在线 Visual Builder、独立 Agent 调试站点、腾讯混元
+或通用 GPU 调度平台。
 
 ## 验收标准
 
-- 业务代码不导入 ADK、LiteLLM 或 Provider SDK；
+- 业务代码不导入 Agent Engine、LiteLLM 或 Provider SDK；
 - 业务不传 Provider、模型名、Endpoint 或 API Key；
 - 文本 LLM、VLM 和 Agent 输出统一通过 canonical SSE；
 - SSE 断线后使用 cursor 恢复，不重新执行模型调用；
 - Feature、Permission、License 任一拒绝都会 fail-closed；
 - 模型 Tool Call 不能绕过 Windy Tool Host；
-- 同一 Run 能关联 Audit、ADK Trace、LiteLLM attempt 和 Usage；
+- 同一 Run 能关联 Audit、canonical Trajectory、Provider attempt 和 Usage；
 - 本地/内网模型可配置协议、主机、端口和 Base Path；
 - 完全断网环境仍可运行已配置的本地 LLM、OCR 和 Speech Operation；
-- ADK Web 不出现在生产 profile；
+- 独立 Agent 调试站点不出现在任何 profile；
 - 非 AI 业务在任一可选 AI Runtime 不可用时仍可运行。
 
 ## 相关文档与资料
@@ -819,9 +828,8 @@ fail closed。开发 ADK Web 已作为 localhost-only 的受控调试入口交
 - [Agent Runtime 接入与运行](../platform/agent-runtime.md)
 - [通用文件与对象存储](./object-storage.md)
 - [运行时可观测性](../operations/observability.md)
-- [ADK Web](https://adk.dev/runtime/web-interface/)
-- [ADK Streaming](https://adk.dev/streaming/)
-- [ADK Audio、Image 与 Video](https://adk.dev/streaming/dev-guide/part5/)
+- [Agent Harness：移除 ADK 与可插拔演进](./agent-harness.md)
+- [ADK 退役与 Direct Engine 恢复](../operations/adk-retirement.md)
 - [LiteLLM](https://docs.litellm.ai/)
 - [PaddleOCR Serving](https://www.paddleocr.ai/main/en/version3.x/inference_deployment/serving/serving.html)
 - [Unlimited OCR](https://github.com/baidu/Unlimited-OCR)

package/template/docs/architecture/module-host.md

@@ -15,9 +15,10 @@
 - `registerToolHandlers()`：为 Manifest `tools` 已声明的 Agent Tool 注册类型化 JSON 执行体，输入输出 Schema、`scopeMode` 与 Handler 均接入双向校验；
 - `registerRolePresets()`：注册角色预设，`permissionKeys` 必须属于本模块 Manifest 权限声明；预设并入内置角色同步（不存在则创建、漂移则非破坏性合并），不改变 4 个内置角色语义；
 - `registerSearchProviders()`：注册 Manifest `providers` 已声明的搜索 Provider；
-- `registerDebugSessionProviders()`：为 developer-only ADK Web 注册业务会话的只读
-  V1 投影；Provider 必须绑定本模块 Agent Operation，并复用该 Operation 的 Feature
-  与 Permission，业务 `sourceId` 不会越过 Host；
+- `registerAgentSessionProviders()`：为 Windy 主站注册业务会话的只读 V1 投影；Provider
+  必须绑定本模块 Agent Operation，并复用该 Operation 的 Feature、Permission 与当前
+  Actor 数据范围，业务 `sourceId` 不会越过 Host；旧
+  `registerDebugSessionProviders()` 只保留一个兼容发布周期的 deprecated alias；
 - `registerUploadPolicy()`：按业务用途注册大小、分片、MIME、扩展名和签名策略；
 - `registerResourceFileAccessPolicies()`：注册本模块业务资源到平台文件的受限读取
   Resolver；purpose 必须来自当前模块或 Manifest 显式依赖模块，resourceType、

package/template/docs/operations/adk-retirement.md

@@ -0,0 +1,98 @@
+# ADK 退役与 Direct Engine 恢复
+
+## 适用范围
+
+本说明用于从 `create-windy@0.6.13` 更新到 `0.6.14`，以及排查
+`windy.direct.openai-compatible.v1` 的启动、运行和历史兼容问题。该迁移不发布新能力，
+不启用 AH-1 Session/Context 或 AH-2 Workflow/Delegation。
+
+## 更新行为
+
+`windy update` 按文件所有权执行：
+
+| 遗留项                                                                       | 自动行为                       | 原因                               |
+| ---------------------------------------------------------------------------- | ------------------------------ | ---------------------------------- |
+| 未漂移的 `docker-compose.agent-debug.yml`、启动脚本和其它 Windy-managed 文件 | 删除                           | 内容仍等于上一版本清单，可安全迁移 |
+| 客户修改过的 Windy-managed 文件                                              | 产生 conflict 并停止事务       | 不能猜测客户改动是否仍有用途       |
+| `apps/agent-server/project/adk-web-debug.json`                               | 保留并报告路径                 | project-owned，Windy 不拥有删除权  |
+| 普通 `.env` 中已弃用的 Debug Key                                             | 保留并只报告 Key 名            | 不能读取到报告或猜删客户 Secret    |
+| 指向外部文件的 `.env` symlink                                                | 不跟随、不读取，只报告人工检查 | 外部托管配置不属于 updater 事务    |
+
+更新报告不会记录 Token 值、Provider Key 或其它 dotenv 正文。原 `dev:adk-web` 被明确移除，
+不会静默改成另一条命令；替代入口是主站 `/admin/system/ai-runtime`。
+
+建议流程：
+
+```bash
+bun run windy update --dry-run
+bun run windy update
+bun run windy doctor
+```
+
+先处理 conflict，再重试同一更新。不要手工删除 `.windy/update-state.json`；事务中断后使用：
+
+```bash
+bun run windy doctor --repair
+```
+
+`doctor --repair` 只恢复 updater 事务和当前版本仍管理的本地 Secret，不会删除 project-owned
+JSON，也不会改写已弃用的普通 `.env` Key。
+
+## 重复故障与快速恢复
+
+### `RUNTIME_UNAVAILABLE`
+
+连续出现 unavailable 时，依次核对 Agent Server 内的 `QWEN_API_URL`、`QWEN_API_KEY`、
+`QWEN_MODEL`、HTTPS Host allowlist、Provider capability 和 readiness。不要向 Web 注入这些值，
+也不要通过恢复旧 Engine 绕过治理。修复配置后重启 Agent Server，再从主站检查 readiness 和
+新的 Run。
+
+### 历史 Run 显示 `google.adk.v2`
+
+这是兼容事实，不是当前 Engine 回退。迁移追加 `engine_id`，旧行保留历史 ID；新 Run 必须是
+`windy.direct.openai-compatible.v1`。不要批量回填旧记录，否则会伪造 attestation。
+
+### 旧 Engine 的 Run 在迁移时仍为运行中
+
+Direct Engine 不读取旧 Engine 的进程内状态，也不跨实现恢复 Tool 循环。读取历史 Event 和
+Report 仍可用；尝试继续时稳定失败。确认旧 Run 没有外部副作用正在执行后，使用相同业务输入
+创建新 Run，并依赖业务幂等键/command receipt 防止重复副作用。
+
+### 主站没有 Trajectory
+
+先确认 Run 详情可读、Feature `system.ai-runtime` 和 Permission
+`system.ai-runtime.read` 已授权，再检查 Agent Server 与 Server 的 Runtime Report 版本是否
+来自同一候选。历史记录没有 canonical event projection 时会明确显示 unavailable，不伪造
+轨迹。
+
+### 历史业务会话为空或 404
+
+确认业务模块已改用 `registerAgentSessionProviders()`，Provider 绑定的 Operation、Feature、
+Permission 与当前 Actor 数据范围仍有效。旧注册名称只是 deprecated alias。Opaque Session
+ID 在 Provider/Host 绑定变化后可能失效；重新从列表进入，不要持久化或解析该 ID。
+
+### updater 反复报告遗留配置
+
+报告只会在遗留仍存在时重复出现。由项目所有者确认无客户用途后，人工删除 project-owned
+debug JSON；普通 `.env` 只移除报告列出的旧 Key，保留其它 Token、注释和客户配置。外部托管
+`.env` 应在其配置系统中完成清理，不要用 updater 跟随 symlink 修改。
+
+## 取消、审批和 Usage 核对
+
+迁移后出现行为差异时，从主站 Run 详情按以下事实核对：
+
+- 取消后不应再出现新的模型轮次、Tool 副作用或成功终态；
+- 审批等待保持非终态，批准/拒绝后只能沿原 Run 恢复一次；
+- Provider Attempt 和 Usage 按实际 HTTP attempt 记录，缺失为“未上报”，不能当作零；
+- Citation、Vision Artifact 与最终结构化输出从 canonical Result 读取，不从 Trajectory 反推；
+- Client Agent Session/PageAgent 走独立受治理端点，不应因服务端 Engine 迁移改变。
+
+## 回滚边界
+
+迁移只追加或保留数据库事实，不做删除式 migration。若候选验证失败，回滚整个应用候选和镜像，
+保持数据库备份；不要在生产增加动态开关重新装载已删除 Engine。回滚后由旧版本读取原有数据，
+但新 Engine 已创建的中断 Run 也不能跨实现续跑。
+
+正式发布前必须完成 Python 静态检查与测试、受影响 TypeScript 测试、PostgreSQL 历史读取、
+OpenAI-compatible 文本/Tool/Vision/审批/取消集成、Starter 生成/升级矩阵、pack consumer、联网与
+离线镜像、wheel/SBOM 比较，以及 Client Agent Session/PageAgent 下游回归。

package/template/docs/operations/agent-session-memory.md

@@ -0,0 +1,162 @@
+# Agent Session、Context 与 Memory 运维
+
+本页描述 AH-1 的持久化、恢复和失效传播边界。它不把仓库检查结果写成生产验收。
+
+## 启动条件
+
+长期 Session 只在 Server 配置 PostgreSQL 且 `system.agent-session` Feature、License 与 Permission
+Guard 通过时可用。绑定 `/agent/runs` 还要求 `system.agent-session.manage`；普通未绑定 Session 的
+Run 保持原授权行为。Event 与 Memory payload
+使用 `AI_ARTIFACT_ENCRYPTION_SECRET` 派生独立 AAD 的 AES-256-GCM 密钥；Secret 不得写入日志、
+数据库或客户端。缺少数据库时相关 API 保持注册但返回
+`SESSION_PERSISTENCE_UNAVAILABLE`，不得退回内存 Session。
+
+AH-1 Session/Context/Memory 是本版本的 fresh-deploy baseline。首次部署从已清空旧开发 Docker 容器
+及其数据卷的空 PostgreSQL 开始，不支持迁移或读取开发期 Agent 聊天历史与其派生日志。不得把这项
+部署前清理扩大到正式 Agent Runtime Run 审计、Client Agent Session、Artifact、审批、上传或业务数据。
+
+Migration `0058_agent_session_memory.sql` 创建以下事实与投影：
+
+- `agent_sessions`、`agent_session_events`、`agent_session_checkpoints`；
+- `agent_context_versions`、`agent_context_sources`；
+- `agent_memory_projections`、`agent_memory_sources`；
+- `agent_source_invalidations`、`agent_source_invalidation_deliveries`。
+
+Migration `0059_agent_source_module_key.sql` 为 Context/Memory 来源补齐 `source_module_key` 与
+`source_sequence`，并把失效投影唯一键扩展为 Module Key + kind + ID。0058—0060 只描述空库建表
+和约束，不包含旧 AH-1 投影的兼容回填或批量失效 DML；空、未知或未注册 Module Key 一律 fail closed。
+
+Migration `0060_slimy_rocket_raccoon.sql` 增加最终受治理消息投影、Run 的 Session 绑定和 Memory
+派生坐标，并创建 `agent_session_run_projection_receipts`。启动后应存在
+`agent_context_messages`，且新建 Memory 必须同时保存 `derived_from_session_id` 与
+`derived_through_sequence`；Turn Event、Context Version 和 Memory 投影还应保存同一个规范化案件
+坐标。后续 `0061_agent_workflow.sql` 只增加 AH-2 Workflow 的结构性 DDL；0058—0061
+共同属于空库 fresh-deploy 基线，不提供旧开发期 Agent 数据迁移、回填或清理脚本。开发期数据由
+部署边界外的容器/数据卷清理处理，运行时仍对任何无法核验的新记录 fail closed。
+
+Compose 会给 Agent Server 注入 `AGENT_CONTEXT_HOST_URL=http://server:9747`。非 Compose 部署必须
+指向可访问的 Windy Server；未配置或回调不可用时，绑定长期 Session 的 Model attempt 会稳定
+fail closed，普通 Run 不受影响。
+
+## 恢复与一致性
+
+Session 恢复以 `head_sequence` 和连续 Event sequence 为准。Checkpoint 保存覆盖序列的事实 digest；
+replay 只读取已记录事实，默认策略固定为 `recorded-only`。Fork 必须引用同一 Session 已提交的
+Checkpoint，并保存父 Session、Checkpoint 与父序列。写 Tool 只有显式 `reexecute-write` 才可
+执行，且必须重新通过当前授权、审批、幂等键和 command receipt。
+
+`turn.started` 与 `run.linked` 间出现 CAS 冲突时，Server 使用同一幂等坐标重读并补链；启动失败会
+关闭未完成 Step 与 Turn。补偿失败与原始错误一起上抛，不能留下被静默吞掉的永久开放 Turn。
+
+长期 Session 的 Run 幂等坐标包含 Session 绑定，并由持久 `run.linked` 固定唯一 Turn。若相同
+Actor、Operation、客户端 key 和输入
+用于另一个 Session，Server 必须创建不同 Remote Run 或返回绑定冲突，不能复用旧 Run。查询结果、
+取消和附件等终态路径在写 Session 前再次执行 `system.agent-session` Feature、License 与
+`system.agent-session.manage` Guard，并核对请求 `sessionId` 与已持久的 `run.linked` 一致；普通未
+绑定 Session 的 Run 继续保持原行为。
+
+每个绑定长期 Session 的 Model attempt 使用 prepare/commit 两阶段写 Context：prepare 只返回当前
+可授权的候选来源，不产生 active 版本；DLP 和 Provider policy 完成后，commit 在 Provider 调用前
+原子写入最终消息、来源和请求 digest。下列任一现象都应停止流量并按契约缺陷处理：治理拒绝后仍
+存在 active Context Version、Context digest 与实际 Provider request 不一致、版本只有
+`turn.started` 元数据，或 Provider 已收到输入但 commit 尚未成功。
+
+Run 授权绑定将业务 `prepare` 的规范化 `caseId` 作为 Memory Scope 持久化，并纳入幂等一致性。
+prepare、commit、abort 回调的案件坐标必须与绑定相同；Turn 与 Context Version 也保存该坐标。
+历史恢复只选择完全相同坐标的版本；缺失或不同的案件坐标不会退化成 Session 级历史。V1 未提供
+显式跨案 grant，因此不得通过重复 `caseId`、Session 血缘或客户端参数完成跨案合并。
+
+工作线恢复必须能从持久 Context 消息、已完成 Run 最终结果、Session Summary、可用 Memory、
+ArtifactRef 和 Tool receipt 重建；不得解密或回填原始推理链。五类 Memory 的 Projector append
+入口和每次 attempt 的 Retriever 都必须在生产 Composition Root 中存在。可用表或已有 projection
+不代表闭环成立；若 Retriever 未在 attempt 中产生带来源的消息，应视为不可用而非静默忽略。
+
+业务模块的三类显式触发入口由 `ModuleRequestContext.sessionMemory` 提供。Host 固定来源
+`moduleKey`、当前 Actor/Scope 与取消信号；User Preference、Case Candidate、Verified Fact 的
+来源和对象仍须由模块权威 Adapter 复核。SSE 断开不会成为最终结果丢失条件：下一次 prepare 会对
+未关闭的 `run.linked` 做终态补偿，先追加幂等 Memory，再收敛 Turn。
+
+完成 Run 必须依次写入 Working Context、Session Summary 和持久 Terminal Projection Receipt，最后
+才能追加 `turn.completed`。Reconciler 也检查 closed-but-unprojected：缺 Receipt 时按固定终态序列和
+结果 digest 幂等补投；坐标漂移则拒绝，不能覆盖。Receipt 不拥有 Memory，单项投影删除后不会因此
+自动重建。纯 `/events` 读取只要求 Run read 权限与持久 binding 校验；result、cancel、attach 等会
+写长期 Session 的路径才额外执行 Feature、License、manage Guard。
+
+Working Context 默认最长 24 小时，调用方只能设置更短 TTL。Host 配置大于 24 小时会在装配时拒绝。
+Context 来源同时记录 Memory 投影自身坐标及其底层权威来源；派生 Memory 继续保存直接 Memory
+依赖，因而 TTL 以 `memoryId` 发出的失效会收敛消费它的 Context 和后续 Memory。过期扫描以条件
+更新领取 active 投影，并在同一事务追加由 `system.agent` 绑定的 `source-expired` Outbox；失败回滚
+后由下一轮重试。Case
+Memory 只在业务 Operation 显式提供当前 `caseId` 且所属模块对象授权复核通过时进入 Context，禁止
+使用 `derived_from_session_id` 推断当前案件。
+
+权威业务模块通过 Host 绑定的 `ModuleRequestContext.sourceInvalidation` 发布 deleted、expired、
+superseded 和 authorization-revoked。调用方不能提供 Module Key、Actor 或 Scope；Producer 的
+append seam 可绑定业务来源事务。平台用户、角色与数据范围变更在身份事务内追加撤权事件，并按
+Actor 派生 Session 收敛 Context、Memory、Search、Embedding 和 UI；读取端不等待 Worker 即复核
+当前 Actor/Scope。
+
+Session 归档在同一 PostgreSQL 事务中写入 `session-derived` 失效 Outbox。消费者按
+Context 按 `session_id`、Memory 按 `derived_from_session_id` 匹配该 Session 的全部派生投影；即使
+Memory 使用范围是 user 或 case，也必须收敛。只按 `scope_kind=session` 匹配属于缺陷。删除单个 Memory 只删除该
+projection，不发布来源删除，也不清除同源其它 Memory/Search/Embedding。只有权威来源模块的
+生命周期事件可以发布 `source-deleted`。五个 Delivery 各自完成，不能因一个目标成功就将整条
+失效标为完成。Server Composition Root 启动 Worker；进程崩溃后其它实例可领取过期 Lease，协议
+错误进入 rejected，临时目标不可用进入 pending 并延迟重试。
+
+建议监控：
+
+```sql
+select status, count(*)
+from agent_source_invalidation_deliveries
+group by status;
+
+select sink_key, count(*), max(attempt_count)
+from agent_source_invalidation_deliveries
+where status in ('pending', 'processing', 'rejected')
+group by sink_key;
+```
+
+AH-1 的 Search/Embedding Adapter 与 canonical Memory 投影共享状态；若目标部署启用独立索引，
+必须替换为该索引的真实删除 Adapter。只看到 Context/Memory 数据库状态变化，不能证明独立索引
+已经收敛。即使队列积压，读取路径也必须按 moduleKey/kind/ID/version/sequence 查询权威对象，
+并在撤权、删除、归档、版本或授权 generation 漂移时立即拒绝。
+
+## 主站与数据披露
+
+`/admin/system/agent-sessions` 受 `system.agent-session` Feature、
+`system.agent-session.read` Permission 和现有 License Guard 控制。读取时再次比较当前 Actor 与
+Scope digest。页面只显示服务端白名单摘要和来源坐标；排障时也不得直接解密 payload 回传给
+浏览器或写入工单。Session 列表与详情均按 Actor + 当前 Scope digest 隔离；Context/Memory 任一
+来源无法完成权威复核时，整个投影端点返回稳定不可用，不泄露来源坐标或摘要。
+
+## 备份与恢复演练
+
+本版本首次验收不是历史恢复演练：先停止并删除旧开发 Docker 容器与数据卷，再从空库启动并顺序
+应用 0058—0060。确认 fresh baseline 可启动后，后续备份与恢复才覆盖下列项目。
+
+备份必须同时覆盖上述 AH-1 表、业务权威对象、Search/Embedding 索引重建来源和当前加密 Secret。
+恢复演练至少验证：
+
+1. 进程和容器重启后 Session head、Checkpoint 与 Fork 血缘不变；
+2. Checkpoint digest 可复算，损坏密文或 digest 会 fail closed；
+3. replay 不产生 Tool 副作用；
+4. 撤权、删除和归档在 UI、Context、Memory、Search、Embedding 全部收敛；
+5. Secret 缺失或错误时返回不可用，不生成新事实覆盖旧数据。
+
+## 候选验证命令
+
+本次实现阶段不执行下列命令。形成合并候选后集中运行：
+
+```bash
+bun run test:merge
+```
+
+只有正式发版候选才运行：
+
+```bash
+CI=true WINDY_RELEASE_PHASE=candidate bun run release:verify
+```
+
+还需在真实 PostgreSQL 与真实 Provider 环境完成 attempt Context 录入、容器重启、并发 CAS、Lease
+恢复、Search/Embedding 删除和对象撤权评测；这些不是本地单元测试或 build 的替代项。