create-windy 0.5.2 → 0.6.0

package/template/docs/architecture/report-staging.md

@@ -0,0 +1,158 @@
+# 受治理的大报告暂存
+
+`ModuleReportStagingPortV1` 用于模块读取体积较大、需要随机访问内部文件的报告。
+模块提交的只能是已注册 Storage Resource File 引用和报告内业务相对路径；Host 独占
+物理目录、归档进程、资源上限、授权重检、保留期与清理状态机。
+
+该能力随 `system.storage` 物理分发。未选择 Storage 的 Starter 不包含 Server 实现、
+数据库表、迁移 DDL、文档或容器内的 libarchive；SDK 中的可选契约可以继续用于跨版本
+编译，`requireModuleReportStagingPortV1()` 会稳定返回
+`REPORT_STAGING_UNAVAILABLE`。
+
+## 模块接入
+
+模块先注册 Resource File 读取策略和报告策略。报告 `purpose` 必须属于模块命名空间，
+每个 `sourcePurpose` 必须已由同一模块注册：
+
+```ts
+host.registerReportStagingPolicy({
+  purpose: "evidence.report-staging",
+  sourcePurposes: ["evidence.original"],
+  retentionMs: 24 * 60 * 60_000,
+  claimTtlMs: 60_000,
+  maxReadLeaseMs: 5 * 60_000,
+  maxProcessMs: 30 * 60_000,
+  maxSources: 16,
+  maxArchiveBytes: 4 * 1024 ** 3,
+  maxExpandedBytes: 16 * 1024 ** 3,
+  maxEntryBytes: 2 * 1024 ** 3,
+  maxEntries: 100_000,
+  maxCompressionRatio: 200,
+  maxPathDepth: 16,
+});
+```
+
+HTTP Route 与 Durable Handler 都从 Context 取得相同的 V1 Port。创建时必须显式选择
+`sourceMode`，Host 不根据扩展名或内容猜测：
+
+- `archive`：`sources` 是单卷或多卷归档，`entrypoint` 必须等于 `sources[0]`。Host
+  将这组路径按调用方给出的顺序交给固定 libarchive helper；preflight 和 extraction
+  使用完全相同的卷集合和顺序，不扫描或猜测相邻卷。
+- `expanded`：每个 `source` 就是一个待封存的普通 entry，`entrypoint` 是主页面或业务
+  manifest。Host 不启动 libarchive；这适用于供应商已经交付展开目录的报告。
+
+两种模式都要求 `entrypoint` 属于显式 `sources`，都不会递归扫描 Storage 目录或猜测
+相邻文件。模块不会得到 Host 文件路径，也不能传入 Actor、Scope、暂存根目录或任意
+进程参数。示例：
+
+```ts
+await context.reportStaging?.createOrResume({
+  purpose: "evidence.report-staging",
+  idempotencyKey: "import-2026-08-01-001",
+  sourceMode: "expanded",
+  entrypoint: "report/index.html",
+  sources: selectedFiles.map(({ file, relativePath }) => ({
+    file,
+    relativePath,
+  })),
+});
+```
+
+V1 Host 还施加与单个模块策略无关的协议硬上限：规范化相对路径最多 4096 UTF-8
+bytes，源文件总数最多 10,000，归档卷最多 256，显式 entry 与隐式目录合计最多
+200,000。模块策略可以进一步收紧这些值，不能放宽 Host 上限。
+
+## 封存流程
+
+1. Host 用 `module + owner + authorization scope + purpose + idempotency`
+   创建或复用持久 group，并取得带过期时间的独占 claim。
+2. 每个源文件都重新经过 Storage Port 授权，随后完整流式复制、计数并计算 SHA-256；
+   声明大小或摘要漂移会立即失败。
+3. `archive` 模式下，Host 用固定 helper 实际读取一个 RAR5 fixture，并核对展开后的文件
+   名、大小与内容。只有 `binary realpath + device + inode + size + mtime + ctime` 相同且
+   真实读取成功时才缓存能力结果；可执行文件存在本身不代表 RAR5 可用。
+4. helper 通过 libarchive 的 callback data/switch API 按序打开显式卷，并用 raw logical
+   position 证明解析位置至少触达每个卷；只输出带固定 magic/version 的二进制 frames：
+   文件/目录元数据、最多 64 KiB 的长度前缀数据块、entry 结束和归档结束。它不经过
+   shell、不写磁盘，并拒绝 link、特殊文件、加密、超长路径及任何 libarchive
+   WARN/error；没有产生任何 entry 的空或截断输入同样 fail closed。
+5. Host 第一遍完整消费 frames 但不写 entry，把显式节点及其隐式目录逐项写入 claim
+   专属 SQLite metadata spool；唯一索引在数据库内 fail closed 地验证 UTF-8、NFC、
+   Unicode casefold、绝对路径、`..`、Windows/UNC 路径、路径深度、重复路径、文件/目录
+   前缀冲突、条目大小、条目数、隐式目录数、实际展开大小和压缩比。第二遍按 ordinal
+   游标逐项核对相同的 path/type/size/order；每个 data frame 在读取 payload 和写盘前先
+   同时检查 entry 与聚合剩余配额，超限时不会写入可接受前缀。普通文件以 `wx`、`0600`
+   打开，partial write 必须循环到完整 chunk，并按实际 `bytesWritten` 扣减。
+6. framing 总字节、元数据、data frame 数、运行时间、claim heartbeat、取消、stderr、
+   SIGTERM grace 和 SIGKILL 均有硬边界。helper failure、截断、尾随数据、两遍元数据漂移
+   或缺少结束标记都会失败。timeout/取消会协作 abort Host consumer、destroy pipe，并
+   有界终止 helper；既有 attempt 清理随后 unlink 工作目录。Node 不能强杀已经进入内核的
+   本地文件 I/O，但该 I/O 返回后会再次检查取消，且未封存 inode 不会被发布。
+7. Host 不递归解包内部归档。顶层解包完成后用 DFS 重新遍历全部节点，拒绝链接和特殊
+   文件，逐文件计算 SHA-256，并在 spool 中标记扫描结果、逐项核对 preflight 的路径、
+   大小、条目数和展开总量；Node heap 不保留全量 `files[]` 或 `directories[]`。
+   `expanded` 模式直接把每个已授权 source 流式写入 entry 路径，再执行同一轮核对；
+   HTML 等普通文件不会进入归档命令。
+8. spool 使用 4096-byte page、关闭 journal/synchronous/mmap、文件型临时存储，并按
+   `min(4 GiB, 16 MiB + maxEntries * (4096 + 768) * 4)` 限制 page count；容量耗尽统一
+   返回 `REPORT_STAGING_LIMIT`。扫描完成后它从 `0600` 收紧为 `0400`，随整个 claim
+   工作目录原子移动到 sealed 目录。PostgreSQL seal 事务以最多 1000 条的 batch 流式
+   写入 entry 和增量 manifest hash，并在开始及最终发布 `ready` 前使用数据库
+   `clock_timestamp()` 复核 group/claim fence。任一后批写入、冲突或最终 fence 失败都会
+   回滚整个事务，过期 attempt 不能发布或删除接管者输出。
+
+seal 提交返回未知时，Host 会读取持久 group 状态：只有同一 seal 已成为 `ready` 才按
+成功恢复，否则只删除本 attempt 的精确目录并走 fenced failure。每次新 claim 会先清理
+该 group 的旧 `.work` 和 seal；成功或恢复后再清理除当前 seal 外的 sibling，避免进程
+崩溃留下的 orphan 无限累积。
+
+Solid RAR 无法安全地从任意条目恢复。取消、timeout、进程故障或 claim 丢失后，Host
+会删除未封存目录并释放 claim；同一幂等请求再次执行时从首卷重新扫描和解包，不复用
+部分输出。
+
+为兼容统一的配额和观测字段，`expanded` 模式的 `archiveByteSize` 表示输入 source
+总字节数，并与 `expandedByteSize` 相等。其 manifest 的 `sources` 为空，调用方应通过
+分页 entry 清单读取文件；归档模式的 manifest 仍提供卷摘要。
+
+## 读取与清理
+
+读取方必须先获取持久 read lease。`inspect`、lease、manifest、分页和打开 entry 每次
+都会重新执行当前 Route/Durable Guard，并核对模块、owner、authorization scope 及
+当前策略摘要。`closeReadLease` 和 `discard` 仍重新执行 Guard 并核对所有权，但刻意不
+要求旧 group 的策略摘要继续存在或相同，使策略收紧后仍能释放读取 fence 和清理数据。
+`openEntry` 以 `O_RDONLY | O_NOFOLLOW` 打开一次文件描述符，并在同一描述符上完成
+`fstat`、完整 SHA-256 和后续 stream，不会按路径重新打开。摘要完成后还会再次执行
+Guard，并复核当前 seal 与 read lease 尚未到期；任一复核失败都先关闭描述符再拒绝。
+
+到期 group 由 Storage cleanup task 分批清理。有效 claim 或 read lease 都是 purge
+fence；清理先持久化 `discarding`，删除文件成功后再写入 `discarded`，进程重启后可安全
+重试。`ready`、失败、lease、claim、entry 和 source 元数据都在 PostgreSQL 中持久化，
+临时或封存内容默认位于 `WINDY_STORAGE_ROOT/report-staging`。如需独立挂载，可显式
+设置 `WINDY_REPORT_STAGING_ROOT`。
+
+审计只记录 opaque group/entry ID、结果、错误码、数量和字节数，不记录 Host 路径、
+文件内容、Storage `fileId` 或 Secret。
+
+生产环境没有 PostgreSQL 时，Host 不装配 `ModuleReportStagingPortV1`，调用方得到稳定的
+unavailable 语义；仅开发和测试环境允许使用进程内 repository 作为短生命周期 fixture，
+不会把它伪装成生产持久能力。
+
+## 容器与运维
+
+Server Alpine 镜像固定安装运行时 `libarchive=3.8.3-r0` 和
+`libarchive-tools=3.8.3-r0`，并用固定
+`libarchive-dev=3.8.3-r0` 与 build toolchain 编译
+`/usr/local/bin/windy-report-archive-stream`；编译后只删除 build 依赖，保留 helper
+所需的共享库。未选择 Storage 的
+Starter 会同时裁剪 helper 源码、编译步骤和依赖。非官方镜像或本地直接运行 Server 时，
+需要自行提供同一 helper；缺失或 RAR5 真实读取失败会返回
+`REPORT_STAGING_UNSUPPORTED_ARCHIVE`，不会回退旧 `bsdtar -x` 或其他外部命令。
+
+相较老 DSP/原先 `bsdtar` 直接解压，当前实现保留已由真实 probe 验证的 RAR5 streaming
+reader，但把落盘所有权和逐 write 配额检查收回 Host，并用可严格解析的 framing 取代
+人类可读 listing。V1 callback 刻意不提供 seek/reopen；需要随机 seek 的 RAR4、ZIP 或
+其他格式会 fail closed，当前不承诺与通用 `archive_read_open_filenames` 格式等价。
+聚焦验收把一个单卷 RAR5 fixture 的字节流拆成两个 synthetic volume，覆盖了正确顺序、
+缺卷、逆序，以及“完整首卷后附无关第二文件”负例；这只验证有序 volume boundary 与
+每个显式 source 至少被解析位置触达，不要求消费最终卷的 padding，也不是供应商生成的
+split-RAR 样本，因此不宣称 RAR 多卷已完成供应商样本验收。

package/template/docs/architecture/server-module-interface.md

@@ -84,6 +84,11 @@ Feature 与 Permission 执行请求时 Guard。只有显式 `immutableCoreAccess
 - **持久任务每次领取都重新授权**：Host 冻结注册时通过校验的 Durable Handler
   能力绑定；首次执行、重试和进程恢复后的领取都重新解析当前 Actor，并按当前
   License、Feature 与 RBAC 状态执行 Guard。提交时曾获授权不能成为永久通行证。
+- **Secret 逻辑声明与物理绑定分离**：业务 Manifest 只声明稳定三元组，project-owned
+  Composition 绑定 `SecretRef` / `SecretResolver`。Request 与 Durable Port 每次调用
+  重新解析，Tool Context 默认没有 Secret Port。公开 Context 为旧 object literal
+  保留 optional 字段；需要该能力的模块调用 `requireModuleSecretPort()`，缺失时稳定
+  fail closed，Windy Host 在实际 Request 和每个 Durable attempt 始终注入 Port。
 - **审计白名单**：模块只能 emit 自己 Manifest 注册的审计动作；Guard 拒绝（`security.denied`）由宿主统一记录，模块无法关闭。
 - **存储最小授权**：上传 purpose 强制属于本模块已注册 Upload Policy，Owner 由宿主
   以当前 Actor 补齐。Owner 读取保持用途约束；跨上传者读取的 purpose 只可来自当前
@@ -91,6 +96,30 @@ Feature 与 Permission 执行请求时 Guard。只有显式 `immutableCoreAccess
   Actor/Scope、消费者 Manifest Feature/Permission 和 project-owned 资源绑定
   Resolver。返回值移除 Owner 与 ArtifactRef，模块接触不到 `BlobStore`、Upload
   Repository 或任意 manage 能力。
+- **流式写入最小 DTO**：`ModuleStorageWritePortV1` 只接受 purpose、文件业务元数据、
+  声明大小/SHA-256、opaque session ID 和分片流，不接受 tenant、Actor、Owner、Scope、
+  Permission、ArtifactRef、bucket/key、路径、URL 或其它物理 locator。Request 使用
+  Writer 通过 Context 的可选 `storageWriter` 独立注入；既有 `storage` 保持 0.5.2
+  源码兼容。Durable Storage 只保留 `openResourceFile()`。
+- **HTTP 流显式选择**：Module Route 仅可在 `POST` / `PUT` 上声明
+  `bodyMode: "stream"`，声明后才获得 `ModuleRequestContext.bodyStream`；同 Context 的
+  `signal` 同时绑定 Writer。普通 JSON Route 不提供原始 body stream。Host 不缓冲完整
+  请求，`appendUploadPart` 复用底层 `ReadableStream` 背压和 SHA/大小校验。
+- **恢复不等于授权继承**：业务只能持久化 opaque session ID。HTTP 的每个请求与
+  Durable 的每个 attempt 都以当前 Actor、License、Feature、Permission、Scope 和 Host
+  purpose 重新授权，再允许 `getUploadSession`、`appendUploadPart`、`completeUpload`
+  或 `abortUpload`。会话还持久化 creation-time module/canonical Scope hash，任一漂移
+  或历史 binding 缺失都 fail closed；重复 `completeUpload` 只返回首次发布文件。
+- **稳定错误投影**：Writer 只抛 SDK 的 `ModuleStorageError`。调用方可按稳定 code
+  处理取消、校验、偏移、过期和并发；未知 Blob/文件系统失败统一为
+  `STORAGE_WRITE_FAILED`，不暴露主机路径、物理 locator 或底层异常正文。
+- **取消保留可恢复事实**：取消只清当前尚未提交的临时 Blob，已提交分片继续保留；业务
+  明确放弃时必须由后续重新 Guard 的 Request/attempt 调用 `abortUpload`；已取消的旧
+  Context 连 abort 也 fail closed。进程退出后的遗留会话由平台 TTL 和 orphan grace
+  清理，模块不能取得 Repository 后自行清理。
+- **Tool 不继承 Writer**：`ModuleToolContext.storage` 保持既有 create/read Port，不因
+  Request / Durable 新增 Writer 而获得 append/complete/abort。Agent 或 MCP 写入能力
+  必须另行完成 Manifest、审批、幂等和可追踪结果契约。
 - **角色预设非破坏性合并**：预设随内置角色同步，手工追加的授权保留；与既有角色 Code 冲突直接启动失败，不做静默覆盖。
 
 ## 当前边界

package/template/docs/architecture/speech-variants.md

@@ -0,0 +1,45 @@
+# Speech V2 variants
+
+Speech 的旧请求没有 `contractVersion` 时保持 V1 语义：只执行 `transcribe`。V2
+请求必须同时带 `contractVersion: 2` 与固定 `variant`，取值只能是
+`normalize`、`transcribe` 或 `translate`；两字段任一缺失或时间戳使用布尔值均返回
+`INVALID_INPUT`。
+
+`timestamps` 只接受 `segment` 或 `word`。`translate` 额外要求
+`targetLanguage`，输出每个 segment 的 `source`、`translation`、`startMs`、`endMs`；
+词级时间戳只属于原文。运行时以 canonical JSON 计算幂等指纹，包含版本、variant、
+输入 Artifact 元数据、options、能力、完整 limits 和 provider 治理策略，因此不同语义
+不能重放到同一 Run。
+
+## 归一化与限额
+
+运行时先以 `ffprobe` 读取真实时长，拒绝超过 `maxMediaDurationSeconds` 的输入，再以
+`ffmpeg` 生成 `pcm_s16le`、16 kHz、单声道 WAV。`maxOutputBytes` 限制 inline JSON；
+派生 WAV 必须由 Host 预分配 Output Artifact Sink，并使用 Sink 自己的 artifact/total
+limits。当前未配置该 Sink 的项目会让 `normalize` fail closed，不会把音频塞进 JSON 或
+未受治理的本地存储。
+
+项目必须在 project-owned 的
+`apps/server/src/app/speech-output-artifact-bindings.ts` 显式绑定允许派生
+`normalized-audio` 的 Operation。Server 在调用 Speech Runtime 前先按 Actor、模块、
+Operation、planned Run、授权范围和幂等语义创建短时 scope，并只通过内部 Header 交接
+一次性 grant；Runtime 必须在接受任务前同步确认 grant。调用失败会回滚 pending grant，
+失败或取消终态只撤销仍 open 的 scope，和并发 seal 竞态时保留已封存成品。
+
+Runtime 返回的 Artifact ref 不作为平台事实源。`result` 与 canonical JSON `artifact`
+响应会丢弃远端引用，重新从 Host claim sealed scope，并再次校验当前 Actor、Feature、
+Permission、授权范围、模块、Operation、Run、purpose、媒体类型和限额。scope 未封存、
+引用过期或任一治理事实漂移时均失败关闭。
+
+## Readiness
+
+`/health/ready` 是受内部 token 保护的 V1 readiness snapshot。它不会把 URL 可达当作
+ready：除本地 `ffmpeg`/`ffprobe` 外，还会探测下游 `/health/ready` 并采纳下游明确声明
+的 capabilities。只有配置 deployment key、identity、release digest 与 offers digest 时才
+发布 ready snapshot；Host 通过 operation readiness Port 比对固定 variant、模态、limits
+与 deployment pin。Host 的 Speech source 位于 runtime composition 中，不使用统一
+跨 Runtime aggregator。
+
+当前 Host 只接受包含 `speech.output-artifact.v1` 的单一 `normalize` 原子 offer；在
+Speech producer 完成 Output Sink 真实探测、digest attestation 与 FFmpeg 实执行探测前，
+该 offer 必须保持 unavailable，不能用已配置 URL、二进制路径存在或环境变量冒充 ready。

package/template/docs/platform/agent-tools.md

@@ -22,6 +22,22 @@ Composition 在 Server 监听前失败。
 Handler。Handler 的 `scopeMode` 必须与 Manifest 相同，并收到宿主提供的 Actor、
 Request ID 和超时 AbortSignal，不能接收客户端提交的权限或数据范围。
 
+普通 `ModuleToolContext` 不提供模块 Secret Port；模块即使在 Manifest 声明并由项目
+绑定 Secret，Tool 也不能取得原始值。外部连接能力应由可信服务端业务操作封装，并只向
+Tool 返回脱敏结果。完整边界见[模块 Secret 解析 Port](../architecture/module-secret-resolution.md)。
+
+`ModuleToolContext.storage` 保持既有 create/read Port：可以创建 Host 限定 purpose 的
+上传会话，以及执行既有 Owner/公开/资源绑定读取，但不会因为 Request 与 Durable
+Context 新增可选 `storageWriter: ModuleStorageWritePortV1` 而自动获得 `getUploadSession`、
+`appendUploadPart`、`completeUpload` 或 `abortUpload`。Tool JSON Schema 也不能声明
+`bodyMode: "stream"`、取得 HTTP `bodyStream`，或把 tenant、Actor、Owner、Scope、
+ArtifactRef 和物理 locator 当作 Storage 授权输入。
+
+这条边界避免普通 Agent Tool、Runtime Tool Host 或 MCP Adapter 因 SDK 接口扩展而获得
+新的字节写入能力。未来若要让模型发起写入，必须单独设计 Manifest 声明、写操作审批、
+强制幂等键、Durable 结果追踪、取消/补偿和专用审计，再由 Host 显式提供新的受治理
+Adapter；不能把 `ModuleStorageWritePortV1` 直接加入现有 Tool Context。
+
 纯计算 Tool 可通过 `InstallableServerModule.setupSandbox()` 注册到独立 Tool Worker。
 该入口只提供 Tool Key、输入、幂等键与取消信号，不提供 Actor、Repository、Secret、
 Storage 或平台 Runtime。完整隔离模型见

package/template/docs/platform/document-ai-runtime.md

@@ -1,6 +1,6 @@
 # Document AI Runtime
 
-更新时间：2026-07-27。
+更新时间：2026-08-01。
 
 Windy 的 Document AI 是可选的独立故障域。业务模块声明稳定的
 `kind=document` Operation，并先把当前 Actor 有权读取的业务资源换成短时
@@ -8,9 +8,12 @@ Windy 的 Document AI 是可选的独立故障域。业务模块声明稳定的
 和审计后，才把任务交给 Document Server。未安装或未配置 Document Server 时，对应
 Operation 稳定返回 `CAPABILITY_UNAVAILABLE`，普通业务和文本 Agent 仍可启动。
 
-首个实现返回受输出 Schema 约束的结构化 JSON：页级文本、坐标、Block、版面树、表格和
-标量元数据。搜索型 PDF 等二进制派生物必须等平台输出 Artifact Sink 签发后再作为
-`ArtifactRef` 返回；Document Adapter 不得自行返回文件 URL、主机路径或伪造引用。
+Document Runtime 支持受输出 Schema 约束的结构化 JSON：页级文本、坐标、Block、
+版面树、表格和标量元数据；也已实现搜索型 PDF 等二进制派生物的 Output Artifact
+producer 协议。派生物只能经平台 Sink 密封后作为 `ArtifactRef` 返回，Document
+Adapter 不得自行返回文件 URL、主机路径或伪造引用。协议、Runtime producer、Host、
+生产 bootstrap 与生成器 composition 接缝已经交付；默认 project-owned binding 为空，
+具体项目完成真实 binding 与 provisioning 前仍不能宣称生产链路接通。
 
 ## 责任边界
 
@@ -38,7 +41,13 @@ Document Server 负责：
 - 持久化 Run、事件 cursor、幂等指纹和终态结果；
 - 调用已配置的本地/内网 Document Adapter；
 - 校验页级结构、坐标、版面树、表格、输出大小和页数；
-- 重启时把未完成任务稳定终止，防止把半成品误报为成功。
+- 对 accepted/running/terminal 状态和事件执行单调事务写入；
+- 重启时把没有 Output Sink 的遗留非终态 Run 事务性终结为
+  `RUNTIME_UNAVAILABLE`；有 Sink 的 Run 冻结一次恢复期限，只允许同一语义、同一
+  Run、同一 scope 且严格更高 grant generation 的内部创建请求恢复；
+- ACK 传输结果不确定时，只允许当前进程用同 generation、同 raw grant 精确重试；
+  重启后的同/低 generation、语义或 scope 漂移一律失败关闭，恢复期限不会因重试或
+  再次启动而顺延。
 
 业务不得导入 OCR SDK、启动模型进程、传 Base64、Blob Key、宿主绝对路径或任意公网
 URL，也不得把文本 Agent 或浏览器文本提取宣称为 OCR。
@@ -120,9 +129,115 @@ fail closed；Adapter 的单源 multipart 字段为 `file`，多源字段为重
 每个事件都有单调 `sequence`。客户端断线后使用最后确认的 sequence 恢复，不重新提交
 任务。取消会记录终态并取消当前 Adapter 协程；已进入终态的 Run 不会再次完成。
 
+### Output Artifact 握手
+
+Output Sink 启用时，Southwind Host 在调用 Runtime 前冻结：
+
+- 预分配的 `runId`；
+- 不含 credential 的 Sink Descriptor，包括 scope、output kind、部署/Release/Offer/
+  Policy 摘要、MIME allowlist、limits、expiry 和 `grantGeneration`；
+- 只经内部 Header `x-ai-output-artifact-grant` 发送的 raw grant。
+
+Runtime 先在一个 SQLite 事务中写入 accepted Run、完整语义指纹、scope 和固定恢复
+deadline，再把 raw grant 安装到进程内 generation CAS，并在 ACK 前持久化已消费的
+generation。generation 持久化异常会立即丢弃该 exact credential，Run 仍由既有固定
+deadline 收口。它随后调用 Host 的 grant accept endpoint；只有 Host 返回真正空正文的
+`204` ACK，Runtime 才会先调度 Adapter、再同步清除恢复状态，创建请求随后返回 `202`；
+带任何正文的 `204` 也按明确拒绝处理，且不会创建 Adapter task。raw grant 不进入
+请求 JSON、SQLite、事件、结果、日志或错误，也不传给 Adapter。进程重启后不会从磁盘
+恢复 credential；恢复请求必须带严格更高 generation，Host 每次 Sink 请求仍按当前
+进程内 token 校验。
+
+恢复状态、固定 deadline 和 cleanup 状态只保存在 Runtime 内部 SQLite，不进入公开
+DTO、事件、结果或指纹。`GET events/result` 仍是 cursor/read-only 接口，不触发恢复；
+Host 使用原内部创建命令携带完整相同语义与新 generation 重新派发。后台 reconciler
+在期限到达时以单个事务写入一次 `run.failed`；若当前进程仍持有精确 generation 的
+credential，则执行授权 `DELETE scope`，否则只记录 `pending-host-ttl`，不伪装删除
+成功并依赖 Host TTL。应用退出会取消并等待该 reconciler。
+
+幂等指纹覆盖 Run、Operation、选项、有序输入的 MIME/字节/hash、capability、数据分类、
+Runtime limits、Provider egress/data policy，以及 Sink 的稳定 output kind、部署、
+Release、Offer、Policy、MIME 和 limits。输入 ref、scope、raw grant、临时 URL/路径、
+expiry 和 generation 不进入指纹，允许 credential 正常轮换但不允许治理语义漂移。
+TypeScript 与 Python 使用同一固定向量验证该契约；非有限数、超过安全整数范围的
+integer-valued number（包括浮点表示）和孤立 Unicode surrogate 均在指纹前拒绝，并
+映射为 `INVALID_INPUT`。
+
 ## Document Adapter 契约
 
 `DOCUMENT_ADAPTER_URL` 只允许 localhost、私网 IP 或 `.internal` 主机。Document Server
+先使用与执行相同的可选内部 Bearer Token，有界调用：
+
+```text
+GET <DOCUMENT_ADAPTER_URL>/v1/document/readiness
+```
+
+响应最多 64 KiB，禁止重定向、重复 JSON key、非有限数、未知字段和超过公共 V1
+cardinality 的集合。Adapter 必须返回独立于 Windy Host Registry 的真实 downstream
+事实：
+
+```json
+{
+  "contractVersion": 1,
+  "status": "ready",
+  "runtimeKind": "document",
+  "deployment": {
+    "identity": "windy-deployment-v1_8c98de28-5af2-44ae-9d37-2a54173284bf",
+    "releaseDigest": "sha256:<adapter-and-model-release>"
+  },
+  "offers": [
+    {
+      "variant": "ocr",
+      "capabilityVersion": "intranet-ocr-2026-07",
+      "capabilities": ["document.ocr", "document.layout", "document.table"],
+      "inputModalities": ["document", "image"],
+      "outputModalities": ["document", "text"],
+      "limits": {
+        "maxDurationSeconds": 1200,
+        "maxInputBytes": 134217728,
+        "maxOutputBytes": 33554432,
+        "maxUnits": 500,
+        "maxArtifacts": 16,
+        "maxConcurrentRuns": 4,
+        "maxQueueDepth": 32
+      },
+      "outputArtifactContractVersion": 1
+    }
+  ]
+}
+```
+
+`capabilityVersion` 是影响 OCR、版面、表格或模型语义的稳定版本；Adapter/模型变化必须
+同时改变 downstream `releaseDigest` 或该版本。Document Runtime 把自身 readiness
+release、downstream identity/release、每个 `variant → capabilityVersion` 映射，以及
+实际 Sink 的 immutable identity、release digest 和 protocol version 组成 canonical
+release digest；只交换两个 variant 的 capability version，或替换任一 Sink fact，都会
+使旧 producer digest 失效。最终原子 offers 交给公共 V1 同构算法计算 offers digest。
+两者必须与部署时写入 Runtime 的 producer facts 完全一致，否则 snapshot unavailable。
+Host 的 project-owned expected pin 是另一份独立事实，仍由公共 projector 比较，不能从
+Runtime 环境变量反向生成。
+
+`outputArtifactContractVersion=1` 只是 Adapter 声明它会产生受管派生文件。Runtime 只有
+在内部认证的
+`GET /api/internal/ai/output-artifacts/health/ready` 使用专用
+`ai-runtime-output-readiness` purpose 实际完成 scope/grant、upload session、流式写入、
+complete、seal、授权 open/read、hash 校验和清理；只有 Repository、Storage writer、
+Blob open/read 与清理链全部成功且没有留下 scope、artifact、session、file 或 blob，才
+返回 Sink 的 immutable identity、release digest、protocol version，并向最终 offer 添加
+`document.output-artifact.v1`。探测失败时整个原子 Deployment snapshot unavailable；
+未声明派生文件的 offer 不探测 Sink，也不获得该 capability。Output Artifact Host
+还会再次要求被选择的唯一 offer 包含该 capability。
+
+探测响应正文最多 64 KiB；每个响应 chunk 在复制进聚合 buffer 前先按剩余预算拒绝。
+Probe 的完成时间和 Run 执行前复核都采用半开有效期：完成或执行时
+`now >= validUntil` 立即返回 stale/unavailable，不能消费临界点上的旧证明。
+
+Document Server 在每次 Run 执行前重复同一探测，并要求单个 offer 独立满足全部
+capability、输入/输出 modality 和 limit。带 Output Sink 的请求还必须与当前 snapshot
+的 producer identity、release digest 和 offers digest 完全相同，避免 readiness 与
+执行之间使用漂移后的派生文件协议。
+
+探测通过后，Document Server
 以 `multipart/form-data` 调用：
 
 ```text
@@ -130,7 +245,10 @@ POST <DOCUMENT_ADAPTER_URL>/v1/document/process
 ```
 
 请求包含单个 `file` 以及 `operationKey`、`options`、`dataClassification`、
-`providerEgress`、`providerDataPolicy` 和 `limits`。Adapter 返回 JSON：
+`providerEgress`、`providerDataPolicy` 和 `limits`。文件使用 Runtime 生成的通用名称；
+Adapter 看不到输入 ArtifactRef、Host URL、路径、Sink Descriptor 或 raw grant。
+
+不产生派生文件时，Adapter 返回 JSON：
 
 ```json
 {
@@ -162,8 +280,28 @@ POST <DOCUMENT_ADAPTER_URL>/v1/document/process
 ```
 
 页码必须唯一且不超过 `maxUnits`；坐标非负，置信度在 0–1，版面树深度最多 32。表格只能
-引用已存在页码，单元格必须是字符串。当前 `artifacts` 必须为空，防止 Adapter 绕过
-平台签发链。
+引用已存在页码，单元格必须是字符串。`application/json` 是兼容格式，其中
+`artifacts` 必须为空。
+
+需要派生文件时，Adapter 返回有界 `multipart/related`：第一 part 必须是带明确
+`Content-Length` 的 JSON manifest，后续 part 必须严格按 manifest 声明顺序提供
+`Content-ID`、MIME、字节数与 SHA-256。Runtime 边读边写临时文件并同时执行单文件、
+总字节、数量、MIME、Header、framing 和 hash 校验；公开 `maxOutputBytes` 是 manifest
+JSON 字节与全部 Artifact 字节共享的单一业务内容预算，协议 framing 只有独立的小型
+固定余量，不能把可用业务内容放大到两倍。Runtime 在落盘前先校验声明总量，拒绝重复
+Header、内容编码、尾随 part、路径字段和非有限数值。输入下载或任一输出 part 在截断、
+hash/I/O 失败、超时或协程取消时都会删除当前及先前临时文件，并原样继续传播取消。
+校验成功后才按 `begin → part → complete → seal` 写入 Host Sink，最终用 Host 返回的
+opaque refs 替换 manifest 声明。
+
+每个 Sink 请求都读取当前 generation token。begin/part/complete/seal 均按稳定标识幂等，
+允许 Runtime 在响应丢失后安全重试一次。失败、超时或取消会用当前授权执行
+`DELETE scope`；若 seal 已成功但终态持久化失败，也执行同一补偿删除。DELETE 与本地
+credential 清理都绑定精确 generation，避免并发轮换时误删新授权。成功路径只有在
+completed 终态持久化后才清除 grant；失败或取消路径只有在授权删除成功后才标记
+`deleted`，否则保留 `pending-host-ttl`。`deleted` 是吸收态，不会因迟到 ACK 或重复
+补偿倒退为 pending；同 generation 的并发 exact retry 若已完成，只共享该 completed
+结果，不再次删除 scope。
 
 ## 配置与启动
 
@@ -176,29 +314,73 @@ AGENT_SERVER_INTERNAL_TOKEN=<随机内部令牌>
 AI_ARTIFACT_ENCRYPTION_SECRET=<至少 32 字符的随机值>
 DOCUMENT_SERVER_URL=http://document-server:8090
 DOCUMENT_ARTIFACT_URL=http://server:9747/api/internal/ai/artifacts
+DOCUMENT_OUTPUT_ARTIFACT_URL=http://server:9747/api/internal/ai/output-artifacts
 DOCUMENT_ADAPTER_URL=http://ocr.internal:9000
 DOCUMENT_ADAPTER_TOKEN=<可选内部令牌>
 DOCUMENT_ADAPTER_CAPABILITIES=document.ocr,document.layout,document.table
 DOCUMENT_MAX_UNITS=500
+DOCUMENT_DEPLOYMENT_KEY=document.intranet-ocr
+DOCUMENT_DEPLOYMENT_IDENTITY=windy-deployment-v1_<immutable-uuidv4>
+DOCUMENT_RELEASE_DIGEST=sha256:<runtime-adapter-model-sink-release>
+DOCUMENT_OFFERS_DIGEST=sha256:<canonical-final-offers>
+# DOCUMENT_READINESS_TIMEOUT_SECONDS=2
+# DOCUMENT_READINESS_TTL_SECONDS=60
 ```
 
-受控 Provider Deployment 还要设置 `DOCUMENT_DEPLOYMENT_KEY`，并与 Manifest 的稳定
-Key 完全一致。启动：
+四项 `DOCUMENT_DEPLOYMENT_*` / digest 都是 Runtime 自身报告的 producer facts；缺少
+任一项时，即使 URL 存在也只返回 `RUNTIME_NOT_CONFIGURED`。Provisioning 必须一次生成
+immutable UUIDv4 identity，并使用实际 Adapter/model/Sink release 与最终 offers
+计算两个 digest。Host Registry 另行保存 expected pin。受控 Provider Deployment 还
+要求 `DOCUMENT_DEPLOYMENT_KEY` 与 Manifest 的稳定 Key 完全一致。启动：
 
 ```bash
 bun run dev:document
 ```
 
-Document Server 的 `/health/ready` 需要内部 Bearer Token，只返回 ready/unavailable、
-capability 和非敏感 limits。没有 Adapter 时返回 unavailable；不会回显 Token、内部
-文件 URL、业务正文或底层异常。
+Document Server 的 `/health/ready` 需要内部 Bearer Token，返回完整 AI Runtime
+Readiness V1 snapshot。每次请求都执行真实 downstream probe，不缓存旧 ready；
+未配置、认证失败、不可达、超时、Sink 不可用、未知字段、contract/digest 漂移分别
+收敛为稳定且不含原始 detail 的 structured unavailable。响应不会回显 Token、内部
+文件 URL、业务正文、Adapter body 或底层异常。
+
+### 当前 Composition 接缝
+
+Server 私有组合入口只接受已 provisioning 的不可变 Sink facts：
+
+```ts
+createDocumentOutputArtifactRuntime({
+  // 其它既有依赖省略
+  readinessIdentity: {
+    identity: "windy-deployment-v1_<immutable-uuidv4>",
+    releaseDigest: "sha256:<sink-service-release>",
+    protocolVersion: 1,
+  },
+});
+```
+
+显式创建了 Output Runtime 但未注入 `readinessIdentity` 时，其 Sink readiness 固定
+`503`，不会用进程存活或 Repository 查询伪装 ready。统一生产 Composition 的边界更
+严格：只有非空 project-owned binding、持久 Repository、Artifact reference secret、
+Sink immutable identity 和 release digest 同时存在，才创建 Output Runtime 并注册
+内部 Sink readiness route。任一前置事实缺失时，两者都不安装，而不是额外暴露一个
+无实现的 `503` endpoint。生产缺少持久 Repository 时不得回退到 InMemory，也不得给
+带 Output Artifact binding 的 Operation 标记生产就绪。
+
+不带 Output Artifact binding 的既有 Document Operation 保持兼容：Host capability
+检查可消费 0.5.2 legacy `status/capabilities`，也可对 `schemaVersion=1` snapshot 使用
+公共 parser/projector 验证完整原子 offer；出现未知 `schemaVersion` 时失败关闭。legacy
+路径只维持既有无输出执行，不产生 operation-level Registry pin，也不能证明 Sink 或新
+Runtime 已生产就绪。
 
 ## 运维与取舍
 
-- Run 与事件当前使用 Document Server 自有 SQLite，适合单副本；多副本持久化与平台侧
-  Run 授权恢复由统一 Agent 持久化能力继续收敛。
+- Run 与事件当前使用 Document Server 自有 SQLite，适合单副本。它持久化语义指纹、
+  scope、最后接受的 generation、单调状态/事件和密封后的 refs，不持久化 raw grant；
+  多副本协调仍由统一 Agent 持久化能力继续收敛。
 - Artifact 默认短时有效，并在每次读取时重算授权；任务时长不能超过 3600 秒。
 - Adapter 地址被限制为本地/内网。需要云 Provider 时由受审计的内网 Adapter 承接，
   不允许业务直接配置公网 URL。
-- 当前选择结构化 JSON 作为首个稳定结果，不伪造搜索型 PDF Artifact。后续输出文件必须
-  通过平台 Artifact Sink、TTL、下载权限和审计后再开放。
+- Output Artifact producer、真实 Sink lifecycle probe、生产 bootstrap、Starter/env 与
+  统一 Host Composition 接缝已实现。默认 project-owned binding 为空；项目完成真实
+  binding、持久 Repository 和 producer/Sink facts provisioning 前仍只能使用空
+  `artifacts` 的结构化 JSON，不得绕过 Sink、TTL、下载权限和审计自行返回文件。

package/template/docs/platform/module-configuration.md

@@ -35,6 +35,11 @@ Secret 配置分成引用和运行时值两层：
 - Registry 的公开描述只返回逻辑字段路径、是否 Secret、是否必填，不返回 env key、文件路径、引用 locator 或有效值；
 - 解析后的 Secret 只能进入进程内的 typed runtime config，禁止交给普通 API、结构化日志、审计 metadata 或配置 diff。
 
+业务模块运行时连接凭据不通过配置 Registry 增加任意字段。模块使用 Manifest 声明驱动
+的 [Secret 解析 Port](../architecture/module-secret-resolution.md)：project-owned
+Composition 才能把本节的 `SecretRef` / `SecretResolver` 绑定到逻辑
+handle/connection/purpose，业务模块看不到物理 locator。
+
 平台 Server 在创建数据库连接、初始化审计恢复和监听端口前加载 `platform.runtime`。数据库、平台 Redis、RuoYi 连接和机器码通过 env Resolver 解析；Server 的 foundation 快照只投影名称、Feature 等非敏感字段。独立签名服务在连接 Vault 和监听端口前加载 `license.signing-service`，Bearer/Vault Token 只经受保护文件 Resolver 进入对应客户端。
 
 ## 新模块接入规则

package/template/docs/platform/speech-ai-runtime.md

@@ -127,6 +127,13 @@ canonical JSON 字节流，包含 `content-length` 与 `x-content-sha256`。Arti
 业务可以在通过输出 Schema 后把结果导入自己的事实表、保存来源回链并进入人工校正；
 平台不会替业务保存消息关系或翻译状态。
 
+`normalize` 的 WAV 不进入 Speech Runtime 的 SQLite 结果库。项目在
+`apps/server/src/app/speech-output-artifact-bindings.ts` 显式选择 Operation 后，Host
+在 create 前预分配 operation-bound Output Artifact scope、grant 与 TTL；Runtime 同步
+ACK grant 后才能接受任务。失败/取消只清理 open scope，sealed 成品由 Host 在每次结果
+读取时按当前 Actor、模块、Operation、Run、purpose、限额、Feature、Permission 和数据
+范围重新 claim。远端响应中的引用会被丢弃，不能绕过 Host claim。
+
 ## 部署
 
 选择 `system.agent` 的 Starter 会分发独立 Speech Server。配置：
@@ -137,20 +144,42 @@ AGENT_SERVER_INTERNAL_TOKEN=<随机内部令牌>
 AI_ARTIFACT_ENCRYPTION_SECRET=<至少 32 字符>
 SPEECH_SERVER_URL=http://speech-server:8091
 SPEECH_ARTIFACT_URL=http://server:9747/api/internal/ai/artifacts
+SPEECH_OUTPUT_ARTIFACT_URL=http://server:9747/api/internal/ai/output-artifacts
 SPEECH_ADAPTER_URL=http://asr.internal:9001
 SPEECH_ADAPTER_TOKEN=<可选内部令牌>
-SPEECH_ADAPTER_CAPABILITIES=speech.transcribe.batch,speech.normalize,speech.vad,speech.timestamps
+SPEECH_DEPLOYMENT_KEY=speech.primary
+SPEECH_DEPLOYMENT_IDENTITY=windy-deployment-v1_<uuid-v4>
+SPEECH_RELEASE_DIGEST=sha256:<由实际探针事实计算>
+SPEECH_OFFERS_DIGEST=sha256:<由原子 offers 计算>
+SPEECH_ADAPTER_CAPABILITIES=speech.transcribe.batch,speech.translate,speech.vad,speech.timestamps
 SPEECH_MAX_UNITS=100000
 SPEECH_MAX_MEDIA_DURATION_SECONDS=86400
+SPEECH_MAX_INPUT_ARTIFACT_BYTES=2147483648
+SPEECH_MAX_INLINE_OUTPUT_BYTES=67108864
+SPEECH_MAX_OUTPUT_ARTIFACT_BYTES=536870912
 ```
 
-受控 Provider 还需配置 `SPEECH_DEPLOYMENT_KEY`，且必须与 Manifest 完全一致。启动：
+`maxInputArtifactBytes` 约束输入 Artifact，`maxInlineOutputBytes` 只约束 Adapter
+返回的 JSON，`maxOutputArtifactBytes` 只约束 normalize WAV；三者不可互相替代。
+受控 Provider 的 `SPEECH_DEPLOYMENT_KEY` 必须与 Manifest 完全一致。启动：
 
 ```bash
+bun run speech:pins
 bun run dev:speech
 ```
 
+`speech:pins` 会在 Speech 镜像内执行真实 synthetic WAV 转换、ffprobe、Adapter 和
+Output Sink full probe，只在全部通过后原子更新本机 `.env` 中的 deployment identity、
+release digest 与完整 offers digest，并保持文件权限 `0600`。不得手工猜测 digest。
+
 Speech Server 自有 SQLite 保存 Run、cursor、终态转写和结果 Artifact，适合单副本。
-健康检查需要内部 Bearer Token，只返回 capability 与非敏感 limits。Adapter、FFmpeg
-或 FFprobe 不可用时返回 unavailable；完全断网 profile 使用已包含 FFmpeg 的镜像和
-本地/内网 ASR Adapter，运行时不需要公网。
+健康检查需要内部 Bearer Token，只返回 capability 与非敏感 limits。它会真实执行
+受限 synthetic PCM 转 WAV，再让 ffprobe 读取实际输出，并分别严格探测 Adapter 的
+`/v1/speech/readiness` 与 Output Sink；响应必须是状态 200、有界 JSON 且满足 V1
+契约。normalize 只在本地工具与 Sink 都通过时出现，transcribe/translate 只按 Adapter
+逐项证明的原子 offer 出现。Runtime 从这些事实重算 release/offers digest，与部署 pin
+不一致即 fail closed。进程必须先完成一次与 full pin 一致的全量探针；Server Host 也
+必须亲自看到这次完整证明并独立保存完整 offers，之后 Adapter 或 Sink 短时单点故障时，
+只允许当前实测 offers 相对 Host 历史只减不增，因此 normalize 与 transcribe/translate
+不互相拖垮。Runtime payload 自报历史 pin 不构成证明；任一进程重启后都不会沿用旧证明。
+完全断网 profile 使用已包含 FFmpeg 的镜像和本地/内网 Adapter。