create-windy 0.5.2 → 0.6.0

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

@@ -0,0 +1,498 @@
+# AI Runtime Readiness V1
+
+更新时间：2026-08-01。
+
+状态：公共 V1 合约与共享 fixture 的设计范围已经冻结；Document Runtime 已实现真实
+Adapter probe、producer snapshot 和 Output Artifact Sink lifecycle probe，且既有
+无输出 Document facade 可加法消费 V1 offers。Host 以 Manifest 的 immutable expected
+deployment pin 和真实 `/health/ready` snapshot 投影新版 Operation；未配置、超时、漂移
+或授权失败均 fail closed。Speech、Embedding 和 Agent/VLM 的真实 downstream probe
+仍由各自任务完成。本页定义 Host 应如何解释 readiness，不构成
+任何具体客户 Deployment 已经通过生产探测的声明。
+
+## 目标
+
+AI Runtime Readiness V1 为 Southwind Server、Module Operation Host 和各独立
+Runtime 提供同一套失败关闭契约。它回答的是：
+
+> 当前这个 Operation 能否在一个已经过真实探测、身份和 release 均未漂移的
+> Deployment 上，按完整声明的能力、模态和资源上限执行？
+
+它不把进程存活、环境变量存在、URL 非空或 Adapter 已实例化解释为可执行能力。
+某个可选 Runtime unavailable 只影响依赖它的 Operation，不阻止普通非 AI 功能和其它
+Runtime 启动。
+
+V1 公共类型、`parseAiRuntimeReadinessV1()`、offers digest、Deployment identity
+parser 和 Operation 投影均从 `@southwind-ai/server-sdk` 根入口稳定导出，Schema
+常量为 `AI_RUNTIME_READINESS_SCHEMA_VERSION = 1`。Runtime 间共享的 wire fixture
+位于：
+
+```text
+packages/server-sdk/contracts/ai-runtime-readiness/v1
+```
+
+## 核心术语
+
+**Runtime snapshot**
+: 一次有明确版本和有效期的 readiness 事实。单个 snapshot 只证明一个不可变
+Deployment identity、一个 release digest 和一个 offers digest，不能同时代表多个
+可互换 Deployment。
+
+**Deployment identity**
+: 精确指向一个不可原地改写的部署实例或部署 release。V1 只接受
+`windy-deployment-v1_<canonical lowercase UUIDv4>`；稳定的 Deployment Key、URL、
+route alias、文件路径、Header 或 Secret 都不能替代不可变 identity。
+
+**Release digest**
+: 对 Runtime、Adapter、模型和服务 release 等执行实现形成的 canonical digest。模型
+或服务实现发生语义变化时，不能继续沿用旧证明。
+
+**Offers digest**
+: 对当前 Deployment 完整原子 offers 的 canonical SHA-256 摘要。它同时由 Registry
+pin、snapshot Deployment 和 probe attestation 固定，并由 Host 对收到的 offers
+重算；能力、模态、输入限额或资源容量被改写时不能沿用旧证明。
+
+**Probe attestation**
+: Runtime 对真实 downstream 探测结果签发的短时事实，包含探测状态、观察时间和过期
+时间，以及探测到的 Deployment identity、release digest 和 offers digest。`ready`
+只接受成功、未过期、TTL 不超过 300 秒且与 snapshot Deployment 完全一致的
+attestation。
+
+**Offer**
+: 同一 Deployment 下一个原子的 variant 能力包。每个 offer 独立声明 variant、
+capabilities、输入/输出 modalities、普通 limits 与 resource limits。V1 的明确
+resource limits 是 `maxConcurrentRuns` 与 `maxQueueDepth`；它们描述容量边界，不是
+当前调用的资源预留。
+
+Agent/VLM 的这两个 resource limits 由 Provider 配置同时注入 readiness producer 与
+实际 Run admission。`maxConcurrentRuns` 是硬执行上限，`maxQueueDepth` 是已接受等待
+上限；满载时新请求在持久化前稳定失败，幂等重试仍可读取原 Run。启动恢复只按相同容量
+领取 durable Run，因此 readiness 不会声明一个执行层并未强制的资源边界。
+
+**Operation projection**
+: Host 将一个权威 Operation requirement 和 Deployment Registry pin 投影到一个
+snapshot，得到结构化的 `ready` 或 `unavailable` 结果。
+
+## Snapshot 与 Offer 不变量
+
+一个 V1 snapshot 具有以下语义：
+
+- `schemaVersion` 必须等于 `1`；未知版本、缺失版本和格式错误都失败关闭。
+- 时间统一使用 canonical UTC RFC 3339
+  `YYYY-MM-DDTHH:mm:ss.sssZ`；其它时区、无时区或可被不同语言规范化的写法无效。
+- 一个 snapshot 只能携带一个 immutable Deployment identity、release digest 和
+  offers digest。
+- `configured` 只表示 Host 找到了显式配置，不表示 downstream 已经就绪。
+- `ready` 必须同时包含：
+  - `configured=true`；
+  - 成功且未过期的真实 downstream probe attestation；
+  - 非空的 immutable Deployment identity；
+  - 合法的 release digest；
+  - 与实际 offers 一致且被 probe 和 Registry pin 固定的 offers digest；
+  - 至少一个结构完整的 offer；
+  - 每个 offer 的完整 capability、输入/输出 modality、limits 和 resource limits。
+- 配置、URL、Token、capability 环境变量或本地进程存在，任一项单独或组合出现都不能
+  产生 `ready`。
+- probe 未执行、失败、超时、响应无效或已经过期时，snapshot 必须是
+  `unavailable`。
+- probe 的 `checkedAt` 晚于 Host 判定时间时尚未生效，不能提前形成 `ready`。
+- ready snapshot 的 `observedAt` 必须位于 `checkedAt` 与 Host 判定时间之间。
+- probe 的 `validUntil - checkedAt` 不得超过 V1 固定的 300 秒；Producer 不能签发
+  长期有效的 readiness。
+- probe 有效期采用半开区间 `[checkedAt, validUntil)`：必须满足
+  `checkedAt < validUntil` 且 Host 判定时间 `now < validUntil`。`now` 恰好等于
+  `validUntil` 时已经过期，零 TTL attestation 是无效契约。
+- 成功 probe attestation 中的 `deploymentIdentity`、`releaseDigest`、
+  `offersDigest` 必须与 snapshot `deployment` 完全一致；不一致时必须
+  unavailable。
+- Host 必须用 `computeAiRuntimeOffersDigestV1()` 重算 offers，并同时核对 Registry
+  pin；只相信 Producer 提交的 digest 仍不构成证明。
+- identity、digest、capability、modality、limit 或 resource limit 缺失时，不能用
+  默认值补成 `ready`。
+- snapshot 不包含 Endpoint、Secret、内部 Artifact URL、业务正文、Provider 原始错误
+  或响应 body。
+
+### 不可信输入捕获
+
+`parseAiRuntimeReadinessV1(raw, fallbackObservedAt)` 和
+`projectAiOperationReadinessV1(requirement, snapshot, options)` 把 snapshot 视为
+`unknown`。Host 在读取业务字段前只捕获一次有限的 JSON-like data snapshot：
+
+- 只接受 primitive、标准 plain object 和稠密标准 Array；
+- 只读取 own enumerable data descriptors，不执行 getter、setter 或隐式字符串转换；
+- 拒绝 Proxy（含 revoked Proxy）、accessor、symbol、non-enumerable 字段、自定义或
+  `null` prototype、循环引用、共享对象引用和原型污染 key；
+- 在递归深度、对象/数组节点、属性数、数组长度、key 和字符串长度上设硬预算，超限
+  直接失败关闭。
+
+因此恶意 getter、Proxy trap 或原始异常中的 URL、Bearer Token 和 Provider body 不会
+被执行或进入 Module 输出。parser 对无效输入返回固定 `CONTRACT_INVALID` parse
+result；projector 对任何 unknown snapshot 都返回固定结构化 unavailable，不能抛出
+producer 的原始错误。V1 仍忽略安全预算内的未知普通字段；超出安全捕获边界的扩展不
+属于可兼容输入。
+
+### Deployment identity 格式
+
+Deployment provisioning 必须用密码学安全随机 UUIDv4 生成一次
+`windy-deployment-v1_<uuid>` 并随 Deployment 持久化；probe 只能回报它实际探测到的
+同一 identity，不能在每次探测时重建。固定 prefix 和 canonical lowercase UUIDv4
+同时提供 namespace 与 122 位随机 entropy，并排除 URI、Header、locator 和宽泛任意
+文本。
+
+Runtime、Registry requirement 和 probe 必须复用根入口公开的
+`parseAiRuntimeDeploymentIdentityV1()`。即使三处填入相同 URL、路径或
+`Authorization: Bearer ...`，也必须在比较相等性前判定格式无效，绝不能形成
+`ready`。
+
+### Offer 是原子能力包
+
+Host 必须从单个 offer 验证一个 Operation 的全部 requirement，禁止跨 offer 拼接能力。
+例如下面两个 offer：
+
+```text
+offer A: variant=fast, capabilities=[document.ocr], maxUnits=500
+offer B: variant=accurate, capabilities=[document.layout], maxUnits=100
+```
+
+不能组合成同时支持 `document.ocr`、`document.layout` 且 `maxUnits=500` 的虚构
+Operation。一个 offer 缺少任一所需 capability、modality 或 limit 时，应继续检查其它
+完整 offer；没有单个 offer 全部满足时返回 `unavailable`。
+
+同一 snapshot 下的 offers 可以表示同一不可变 Deployment/release 确实提供的多个
+variant，但不能借此表示不同模型、不同 Adapter release 或不同 Deployment。需要证明
+另一个 Deployment 时必须产生另一个 snapshot。
+
+### Offers digest canonicalization
+
+Runtime、Registry 和 Host 统一复用公共 `computeAiRuntimeOffersDigestV1()`：
+
+- variant、capability 和 Deployment/Operation key 只接受最长 128 字符的 ASCII
+  stable-key：首字符为字母或数字，其余可使用字母、数字、`.`、`_`、`:`、`/`、`-`；
+- offers 按 variant 的 code-unit 顺序排序，capabilities 和 modalities 作为集合按
+  同一顺序排序；
+- 字段顺序由公共函数固定，可选 limit 缺失时不写入；
+- 数值只接受安全整数，使用 UTF-8 compact JSON 后计算 SHA-256。
+
+这些约束避免 JavaScript、Python 等 Runtime 各自的 Unicode 排序、JSON 空白和字段
+顺序产生不同摘要。Integration 不得复制一份近似 canonicalization。Producer 可直接
+把普通 offers 传给公共函数，不需要先复制或自行 canonicalize；公共函数会在任何
+复制、排序和 JSON 序列化前执行同一安全捕获、结构校验和 cardinality 检查。直接调用
+传入无效或超限输入时只抛固定的 `TypeError("AI Runtime offers contract invalid")`，
+不回显原始字段。
+
+V1 同时固定以下公开 cardinality 边界，并在遍历、复制、排序或 digest 前失败关闭：
+
+- 一个 snapshot 最多包含 16 个不同 variant 的 offers；
+- 每个 offer 最多包含 32 个不同 capability stable keys；
+- input/output modality 列表最多包含 V1 公开枚举的 6 个不同值；
+- Operation requirement 最多包含 16 个不同 required capability stable keys。
+
+Host 不截断、静默去重或拼接超限输入。上述常量由 `@southwind-ai/server-sdk` 导出，
+Runtime、Registry 和 Host 应直接复用。
+
+Document Python producer 与 TypeScript 公共 parser 还共同读取
+`document-python-parity.json`，固定 16 offers、32 capabilities、6 modalities、
+`Number.MAX_SAFE_INTEGER` 和第一个不安全整数。Python 在聚合响应 chunk 前检查剩余字节
+预算，并按公共字段顺序 canonicalize limits，避免语言间边界或 digest 漂移。
+
+## Ready 判定
+
+V1 的 `ready` 是严格合取关系：
+
+```text
+ready =
+  configured
+  AND downstream probe attested
+  AND attestation not expired
+  AND immutable deployment identity present
+  AND release digest present
+  AND probe/snapshot/registry pin the same offers digest
+  AND host recomputes the same offers digest
+  AND at least one complete offer present
+```
+
+Host 还要在 Operation 投影时继续验证：
+
+```text
+operation ready =
+  snapshot ready
+  AND registry pin matches identity, release digest and offers digest
+  AND one offer satisfies the whole authoritative requirement
+```
+
+任一事实缺失都产生 `unavailable`，不能从其它 Runtime、其它 offer、Manifest 默认值或
+旧 health payload 猜测。失败结果应携带稳定、结构化且不含敏感信息的 reason；典型原因
+类别包括：
+
+- Runtime 未配置；
+- downstream 未探测、不可达、拒绝、超时或返回无效响应；
+- probe attestation 已过期；
+- probe 尚未生效或签发 TTL 超过 300 秒；
+- readiness contract 不受支持或无效；
+- Deployment identity、release digest 或 offers digest 缺失、被篡改或与 Registry
+  pin 不符；
+- Runtime kind 不匹配；
+- variant、capability、输入/输出 modality 不支持；
+- 普通 limit 或 resource limit 不能满足 Operation requirement；
+- 没有一个原子 offer 能独立满足完整 requirement。
+
+V1 固定的 structured reason code 为：
+
+```text
+RUNTIME_NOT_CONFIGURED
+DOWNSTREAM_NOT_PROBED
+DOWNSTREAM_PROBE_FAILED
+PROBE_STALE
+PROBE_NOT_YET_VALID
+PROBE_TTL_EXCEEDED
+PROBE_ATTESTATION_MISMATCH
+RESOURCE_UNAVAILABLE
+CONTRACT_UNSUPPORTED
+CONTRACT_INVALID
+RUNTIME_KIND_MISMATCH
+DEPLOYMENT_KEY_MISMATCH
+DEPLOYMENT_IDENTITY_MISSING
+DEPLOYMENT_IDENTITY_MISMATCH
+RELEASE_DIGEST_MISSING
+RELEASE_DIGEST_MISMATCH
+OFFERS_DIGEST_MISSING
+OFFERS_DIGEST_MISMATCH
+CAPABILITY_MISSING
+VARIANT_UNSUPPORTED
+INPUT_MODALITY_UNSUPPORTED
+OUTPUT_MODALITY_UNSUPPORTED
+LIMIT_INSUFFICIENT
+RESOURCE_LIMIT_INSUFFICIENT
+```
+
+reason 同时声明 `retryable`，并可携带安全的 `subject`、`expected` 和 `actual`；不能携带
+底层异常、Endpoint、凭据或 Provider body。Downstream probe 自身使用更窄的 failure
+code 区分认证、连接、无效响应、本地依赖、资源、超时和 unhealthy。
+
+Runtime 提交的 unavailable reason 不是可信展示内容。Host 解析时对普通 reason 只保留
+`code` 与 `retryable`；`DOWNSTREAM_PROBE_FAILED` 只额外接受固定 failure-code token
+作为 `subject`，且必须与 probe 的 `failureCode`、`retryable` 精确一致。Runtime 提交
+的 `expected`、`actual`、URL、Header、Token 或 Provider body 一律不能进入
+operation-level 输出；投影器自身生成的比较详情也只能使用 Host 定义的安全字段。
+
+V1 最多接受 16 个 unavailable reasons。普通 reason 的稳定 identity 是 `code`；
+`DOWNSTREAM_PROBE_FAILED` 的 identity 是 `code + 已验证的 failureCode subject`。
+`retryable` 和 Runtime 原始 detail 不参与 identity，因此同一原因提交冲突的 retryable
+也会整体失败关闭。`CAPABILITY_MISSING.subject` 固定为
+`operation.requiredCapabilities`，不拼接 requirement 列表。
+
+## Host 的常见调用
+
+最常见的 Module/Host 调用只提交 Operation Key，不让调用方选择 Runtime、解析 health
+JSON、提供 Registry pin 或自己组合 capability：
+
+```ts
+const projected = await readinessPort.inspect({ operationKey });
+
+if (projected.status !== "ready") {
+  throw new ModuleAiOperationError(
+    "AI_OPERATION_UNAVAILABLE",
+    "AI Operation 当前不可用",
+  );
+}
+```
+
+公共 `ModuleAiOperationReadinessPortV1` 只暴露 `inspect({ operationKey })`。它返回
+版本化的 `ModuleAiOperationReadinessV1` discriminated union；`ready` 分支携带
+`validUntil`、Deployment 和满足要求的原子 offers，`unavailable` 分支携带非空的
+structured reasons。实际 Module Operation Port 接线后，Module 调用方只消费这一
+operation-level projection；Runtime snapshot、Registry pin、版本解析和 offer 选择
+保留在 Host Implementation 内。状态页面可以展示结构化 unavailable reason，执行入口
+则统一映射为稳定的 `AI_OPERATION_UNAVAILABLE` 或 HTTP 503。
+
+Host 健康探测只接受 HTTP `200` 或 `503` 的有界 JSON；`200` 必须投影为
+`ready`，`503` 必须投影为 `unavailable`，状态与正文语义不一致时失败关闭。其它状态、
+重定向、非 JSON 或超过 64 KiB 的 body 统一折叠为
+`DOWNSTREAM_PROBE_FAILED`。一次普通探测只有一个硬 deadline，从调用 producer 的
+`health()` 起覆盖等待 Response 与流式读取 body；即使 producer 忽略
+`AbortSignal`、body 永不完成或在 deadline 后才 reject，也不能悬挂 Host，且迟到的
+settlement 会被安全消费。
+按模块注入的 Port 对“Operation 不存在”与“Operation 属于其它模块”返回
+完全相同的常量结果，只有本模块 Operation 才可投影实际 Runtime kind。
+
+Operation requirement 必须来自 Host 已组合和校验的 Module Manifest 及平台配置，
+Deployment identity、release digest、offers digest 期望值必须来自 Deployment
+Registry pin。浏览器、业务 Module、模型输出和请求 body 都不能提交或扩大这些事实。
+
+### 避免检查与执行漂移
+
+readiness 只是短时执行前证据。后续接线应在创建 Run 时固定 projected Deployment
+identity、release digest 和 offers digest，并在真正调用 Runtime 前再次核对。
+attestation 在两者之间过期、Deployment 漂移或 Runtime 拒绝时，执行仍须失败关闭。
+
+### Screenshot intake composition
+
+VLM 的页面截图使用独立 `ModuleAiScreenshotIntakePortV1`。Module 只能创建短时计划、
+一次性 bind，或 discard/cancel；producer-only 的 Artifact attach 不属于 Module Port，
+业务模块不能提交截图 bytes、ArtifactRef、URL 或 Run ID。Server 只在 AI 开启且
+project-owned factory 存在时注入 Port；默认 factory 为空时 Request Context 不包含该 Port。
+
+Factory 返回的 plan 和 token 不是 Module capability。Host 先确认 Operation 属于当前
+Module，并重新执行 License、Feature 和 Permission Guard；producer 签发的真实 plan
+本身必须在 60 秒内过期，Host 不把更长的 capability 截断伪装成短期 plan。Host 再用
+自有 token 绑定 Module、Operation、Actor、Scope 和同一或更短的 expiry，不向 Module
+暴露 producer token。
+
+plan 保存在 Host 生命周期内按 Module 共享的有界 store，而不是 request-local Map；
+因此新 HTTP request 即使获得新的 producer facade，也能在 Actor/Scope 不变时完成一次
+bind。store 不保存 requestId、GuardContext 或表单/页面敏感内容，过期记录会有界清理。
+默认 store 只属于单个 Server 进程，不在副本间复制；多副本部署必须把同一 plan 的
+create 与终态请求粘性路由到同一进程，否则终态请求会稳定失败关闭。当前实现不声明
+跨进程 HA；若不能保证粘性路由，须先提供具备有界容量、原子 claim 和 TTL 清理语义的
+共享 Host store。进程异常退出后未显式 cancel 的 producer plan 仍受自身最多 60 秒
+expiry 约束，不能因此获得更长 capability。
+`bind/discard/cancel` 共享一次性原子消费，终态操作使用当前 request 重新执行 Guard；
+过期、取消、重用、Scope 漂移或 producer 异常均以稳定错误 fail closed。producer 的
+create/bind/discard/cancel 与清理都有硬 deadline，批量清理使用受限并发而非串行等待
+全部历史 plan。
+
+bind 结果只接受严格 plain-data `ArtifactRef` DTO；opaque token 最多 4096 字符。
+Host 还必须用自己的 Artifact codec 验证签名 claims 中的当前 Module、Actor、expiry
+以及 MIME、字节数、SHA-256 等 metadata，不能只相信 producer 返回的字段。真实
+producer 仍须完成截图大小、MIME、像素、上传清理与审计，再把 opaque Artifact 绑定到
+canonical Run。
+
+### Screenshot intake V2（浏览器受控上传）
+
+V2 不替换 V1 Module Port。它由 `POST /api/agent/screenshots` 创建短时 Host plan，浏览器
+仅可提交 `pageId`、不透明 `contextDigest`、声明的 MIME/bytes/pixels，随后以 `PUT` 上传
+原始 bytes；禁止提交 Actor、tenant、scope、Operation、Run ownership、Artifact URL 或物理
+locator。项目自己的 page Registry producer 由 `pageId` 解析允许的视觉 Operation，Host 再从
+认证 RequestContext 重建 Actor/Scope，并执行 Permission、Feature、License Guard。
+
+当前 V2 只接受 PNG；Host 在上传时验证 PNG 签名、IHDR 宽高、声明像素和精确字节数，且同时
+应用 8 MiB、2,000 万像素、每个 plan 单图和有界总计划数限制。生产 producer 必须将实际
+bytes 写入其受治理 Artifact 存储，并只交回 opaque `ArtifactRef`。`contextDigest` 是摘要，
+Windy DTO 不保存 modal、DOM、form 或输入原文；长文本仍应进入原有 schema-governed input。
+
+创建时固定页面、Operation、context digest、purpose、TTL 和 Manifest deployment/release/offers
+pin。Run admission 在 `remote.start` 前取得新的 VLM readiness pin；只有与计划完全一致时才
+可 reserve Artifact。Remote Runtime 与 Agent Server 创建端各再核对一次 pin；创建成功后 Host
+以真实 canonical Run ID 终结绑定。上传重放、取消、未使用 TTL、scope/Operation/pin 漂移、
+factory 缺失或 producer 异常均会取消并失败关闭。
+
+## 四类 Runtime 的统一投影
+
+### Document
+
+Document offer 可以表达 OCR、版面、表格、手写等 variant 与 capability，并完整声明
+document/image 输入、输出 modality、页数、Artifact 数、输入输出字节、像素、运行时间
+及相应 resource limits。Document Adapter URL 存在不构成 probe。
+
+### Speech
+
+Speech offer 按实际支持情况原子表达 `normalize`、`transcribe`、`translate` 等
+variant，以及 audio/video 输入、时间戳 capability、媒体时长、分段数、字节和资源限制。
+不能把只支持 normalize 的 offer 与只支持 translate 的 offer 拼成一个复合能力。
+FFmpeg/FFprobe 可用也只证明本地前处理条件，不能替代真实 Speech downstream probe。
+
+### Embedding
+
+Embedding offer 分别表达实际支持的 text/image modality、批量、Artifact、像素、输入
+输出大小和资源限制。Deployment identity、release digest、维度和归一化等会影响索引
+可重现性的事实必须由可信 Runtime/Registry 固定，不能只信 Adapter 响应或配置 URL。
+
+### Agent/VLM
+
+VLM 不新增 `vision` Runtime kind，也不新增业务可选的 `vision` Operation kind。
+VLM 继续使用 `kind=agent`，由 offer 中的 `vision` capability、image modality、
+Artifact/字节/像素上限以及对应 resource limits进行投影。普通文本 Agent offer 不能与
+另一个只提供图片能力的 offer 拼成虚构的 VLM offer。
+
+## 向后兼容
+
+V1 保持新公共类型和导出为 additive change，不要求已有业务 Module 自行实现 Runtime
+readiness。现有 `ModuleAiOperationPort` 若要暴露新能力，应采用新的组合 Interface 或
+向后兼容的可选入口，不能直接增加所有旧 Adapter 都必须实现的 required method。
+
+公共 readiness Port 不把旧 `/health/ready` payload 投影为 V1 ready：即使它包含
+`status=ready`、capabilities、limits 或 deployment alias，也不能补写缺失的 probe、
+identity 或 digest。唯一的过渡例外是已发布 0.5.2 的无 Output Artifact Document
+facade：它继续接受原有 `status/capabilities` 检查，同时在 payload 明确声明
+`schemaVersion=1` 时改用公共 parser/projector 消费完整 offer。这个 legacy 分支不产生
+operation-level readiness、不能服务 Output Artifact binding，也不能被状态页解释为
+V1 ready；未知 schema version 仍失败关闭。
+
+未来 V1 只允许不改变既有语义且位于安全捕获预算内的可选扩展。新增必要字段、扩大
+安全输入预算、改变 ready 判定、改变 offer 原子性或 reason 语义时必须审查兼容性，
+必要时提升 schema version。未知新版本在旧 Host 上继续失败关闭。
+
+## 与授权和资源调度的关系
+
+Readiness 不替代以下权威检查：
+
+- License；
+- Feature Flag；
+- RBAC Permission；
+- Actor 与数据 Scope；
+- Artifact 当前授权、MIME、哈希与业务对象绑定；
+- Provider egress、DLP 和 Tool network policy；
+- Run 幂等、取消、审计和输出校验。
+
+这些 Guard 仍由 Southwind Server 在每次执行的相应阶段重新检查。对未授权调用方，
+Host 不应通过 readiness 暴露跨模块或跨租户的 Deployment 细节。
+
+Readiness 也不是 GPU、CPU、显存、队列或并发槽位的资源预留。resource limits 描述该
+offer 可接受的硬边界；Operation 的 `minConcurrentRuns` 与 `minQueueDepth` 只过滤不
+满足最低部署容量的 offer。投影成功不保证未来瞬时容量。创建 Run 时仍可能因限流、
+预算、队列饱和或现场资源变化返回稳定错误。
+
+## 共享 Fixture 与 Contract Tests
+
+`packages/server-sdk/contracts/ai-runtime-readiness/v1` 是 V1 wire contract 的共享
+fixture 事实源。Document、Speech、Embedding 和 Agent/VLM 使用同一套断言，至少覆盖：
+
+- 真实、未过期 probe attestation 可以参与 ready 投影；
+- 配置存在但未 probe 必须 unavailable；
+- probe 失败、无效或过期必须 unavailable；
+- identity、release/offers digest 缺失、篡改或 Registry pin 漂移必须 unavailable；
+- 单个 offer 完整满足 requirement 时 ready；
+- capability、variant、modality、limit 或 resource limit 不足时 unavailable；
+- 两个不完整 offer 不能跨 offer 拼接；
+- legacy payload 和未知 schema version 失败关闭；
+- getter、Proxy、循环、原型污染和其它非 JSON snapshot 不执行、不抛且不泄漏原始
+  detail；
+- direct offers digest 在 MAX 接受，在 MAX+1、巨大稀疏数组、accessor 和 Proxy 输入
+  上于 canonicalization 前失败关闭；
+- `now === validUntil` 已过期，`checkedAt === validUntil` 的零 TTL attestation
+  无效；
+- VLM 仍按 Agent Runtime 与 Agent Operation 投影。
+- Document Python 与 TypeScript 从同一 parity fixture 验证 cardinality 和安全整数
+  临界值。
+
+Fixture 只证明 DTO、解析和投影规则一致，不证明真实模型、OCR、ASR 或 Embedding
+downstream 已经部署或可达。
+
+## 后续 Integration 接线
+
+本任务不实现真实 probe Adapter，也不把现有 Runtime 宣称为 ready。后续
+`WINDY-RUNTIME-READINESS-INTEGRATION-1` 至少需要完成：
+
+1. **Document Host 接线**：Document Runtime 已对实际 OCR/Document Adapter 执行
+   有界、认证的 downstream probe，并签发 V1 attestation、producer identity、
+   release/offers digest 和完整 offers；Output Artifact Sink 私有 route 也会执行真实
+   upload/seal/authorized-read/cleanup，且缺少 Composition 注入的 Sink
+   `identity/releaseDigest/protocolVersion` 时固定 `503`。统一 Host 已把 raw snapshot 接入
+   Manifest Registry expected pin 与 operation projector，生产 bootstrap、生成器/env
+   也已提供不可变 producer/Sink facts 接缝；具体项目仍须 provisioning 真实 facts、
+   持久 Repository 与 project-owned Operation binding 后才能标记 ready。
+2. **Speech**：分别核对 FFmpeg/FFprobe 前处理条件与真实 Speech Adapter，报告实际
+   variant、媒体模态、输入和资源限制。
+3. **Embedding**：探测实际 Embedding downstream，并核对 Deployment、模型 release、
+   modalities、输入和资源限制；dimensions、normalized 等语义变化必须反映在新的
+   release digest 中。
+4. **Agent/VLM**：复用 Agent Runtime 的真实 Provider probe，补齐文本与 VLM 的原子
+   offers、Deployment identity、release digest、模态和资源限制。
+5. **Module Operation Port**：在 Host 中接入统一 parser/projector，替换各 facade
+   分散的裸 health/capability 判断，对 Module 只暴露 operation-level 结果，并在 Run
+   创建和执行时固定、复核 identity、release digest 和 offers digest。
+6. **聚合与恢复**：验证单 Runtime unavailable 不影响其它 Runtime，覆盖 probe
+   过期、Deployment/release 漂移、恢复和旧生成项目的失败关闭行为。
+
+只有这些真实 Adapter 和 Host 接线通过对应合约、集成与业务样本验收后，才能把具体
+Operation 标记为已就绪。

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

@@ -1,6 +1,6 @@
 # Southwind AI Runtime 架构
 
-更新时间：2026-07-26。
+更新时间：2026-07-31。
 
 状态：架构已确认，文本 Agent、Document AI、批量 Speech/ASR 与受控 Vision Artifact
 切片已实现。当前包含 Module AI Operation
@@ -9,8 +9,9 @@ Provider、canonical HTTP/SSE、取消、cursor 重放和单副本有界 SQLite
 Provider 时仍安全拒绝。真实业务 Run 已在内部使用 ADK 2.5 Runner、Session、LlmAgent
 和 Event，并把事件转换为既有 canonical signal。ADK Workflow、LiteLLM 多 Provider
 路由和 PostgreSQL 多副本 Store 尚未实现。Document AI 已提供独立
-Server、授权 ArtifactRef、结构化页级结果和本地/内网 Adapter 契约，但未提供搜索型
-PDF 输出 Artifact；Speech 已提供批量转写、归一化、VAD/时间戳契约、稳定分段和结果
+Server、授权 ArtifactRef、结构化页级结果、本地/内网 Adapter 契约，以及搜索型 PDF
+等派生文件的受治理 Output Artifact producer 协议；项目 composition 尚未接线，不能
+视为生产可用。Speech 已提供批量转写、归一化、VAD/时间戳契约、稳定分段和结果
 Artifact，但未提供实时 ASR、TTS 或 Dictation。不能据此宣称完整 AI Runtime 已交付。
 Vision 已提供 `agent.vision` 的多图片受控输入、像素限制、逐次发送审计和 JSON Schema
 终态校验；视频帧输入与实时视觉不在当前切片。
@@ -144,10 +145,18 @@ ADK 和 LiteLLM 不同时维护两套路由或 fallback。ADK 决定运行哪个
 
 - OCR、版面分析、表格识别和长文档解析 Adapter；
 - 文档处理 Run、页级进度和结果 Artifact；
+- Output Artifact 的 generation ACK、manifest-first 流式校验和 Sink 补偿；
 - PaddleOCR、Unlimited OCR、本地/内网/云端 OCR 的能力归一化；
 - 页数、图像、像素、处理时长和 GPU 时间等用量事实。
 
 即使底层 Unlimited OCR 或其他 OCR 使用视觉语言模型，业务 Interface 仍是 Document Operation，不暴露 Chat Completion。
+raw Output Grant 只存在于专用内部 Header 和 Runtime 进程内 CAS；不得进入 JSON、
+持久化、事件、日志、错误或 Provider 请求。重启恢复要求同一幂等语义和严格更高
+generation，终态和事件必须单调。没有 Output Sink 的遗留非终态 Run 在启动事务中
+稳定失败；有 Sink 的 Run 从创建事务起就使用不会因重试或重启而顺延的固定恢复期限，
+只有 ACK 成功并调度任务后才清除恢复状态。只有 ACK 传输不确定时，当前进程才可用同
+generation 和 exact token 重试；后台到期事务只写入一个失败事件，并以精确 generation
+credential 删除 scope，缺少 credential 时如实保留 Host TTL cleanup pending 事实。
 
 ### Speech Server
 
@@ -570,7 +579,13 @@ document.extract.table
 document.extract.handwriting
 ```
 
-长文档采用异步 Run。输入和结果通过 `ArtifactRef` 关联，页级进度可以使用状态查询或独立 SSE；文档内容本身不以 token delta 形式传输。
+长文档采用异步 Run。输入和结果通过 `ArtifactRef` 关联，页级进度可以使用状态查询或独立 SSE；文档内容本身不以 token delta 形式传输。Adapter 的无文件结果继续使用
+`application/json` 且 `artifacts` 必须为空；派生文件使用 manifest-first
+`multipart/related`，由 Runtime 校验 MIME、大小与 SHA-256 后通过 Host Sink 的
+begin/part/complete/seal 生命周期密封。`maxOutputBytes` 同时约束 manifest JSON 与
+Artifact 的业务内容总和，framing 余量不能转化为额外业务预算；截断、校验失败、超时
+和取消都会清理当前及先前临时文件。只有真正空正文的 `204` 才算 ACK。任何失败或取消
+都按精确 generation 执行授权删除补偿；没有当前 credential 时不伪装清理成功。
 
 路由考虑文档类型、页数、文件大小、语言、表格/版面需求、GPU、数据分类、成本和时限。敏感文档默认只允许 localhost 或 intranet Deployment，除非 Operation 明确允许出网。
 
@@ -791,6 +806,7 @@ fail closed。开发 ADK Web 已作为 localhost-only 的受控调试入口交
 
 ## 相关文档与资料
 
+- [AI Runtime Readiness V1](./ai-runtime-readiness.md)
 - [平台基础设施](./foundation-infrastructure.md)
 - [Module Manifest 组合契约](./module-manifest-composition.md)
 - [模块初始化 Host](./module-host.md)

package/template/docs/architecture/durable-jobs.md

@@ -56,11 +56,60 @@ Actor、租户、部门、Scope Grant 和 Role ID，不含 Permission、凭据
 
 模块 Durable Handler 每次执行、自动重试和进程重启恢复时都重新从系统身份仓储解析当前
 Actor；用户停用、Scope 变化或缺少提交快照时以稳定错误 fail-closed。范围稳定后，Worker
-才创建 `ModuleDurableHandlerContext`，其中只额外开放当前 Actor、request ID 和受限
-`storage.openResourceFile()`。每次文件读取仍重新执行当前 License、Feature、Permission、
-nominal Scope、资源与 fileId 绑定以及业务对象授权；成功与拒绝都走资源策略声明的审计
-动作。Handler 不获得 Upload Repository、BlobStore、对象存储 Key、ArtifactRef 或主机
-路径。
+才创建 `ModuleDurableHandlerContext`，其中开放当前 Actor、request ID、signal、
+`storage.openResourceFile()` 和可选 `storageWriter: ModuleStorageWritePortV1`。每次文件读取仍重新执行当前
+License、Feature、Permission、nominal Scope、资源与 fileId 绑定以及业务对象授权；
+成功与拒绝都走资源策略声明的审计动作。Writer 的五个方法为
+`createUploadSession/getUploadSession/appendUploadPart/completeUpload/abortUpload`，
+Owner 与可用 purpose 均来自本次 attempt 的 Host Context。Handler 不获得 Upload
+Repository、BlobStore、对象存储 Key、ArtifactRef、tenant/Actor/Owner 输入或主机路径。
+
+### Durable 流式写入恢复
+
+Upload session、已提交分片、服务端下一分片号和偏移属于 Storage Repository 的持久
+事实。需要跨 attempt 写入时，Handler 必须把 opaque session ID 保存到 payload 所引用的
+业务持久事实；也可以由提交 Route 先创建会话，再把 session ID 固化进 Job payload。不得
+把 session、Writer 或流 Reader 只保存在闭包、模块单例或 Worker 内存中。
+
+每个 attempt 的恢复顺序固定为：
+
+1. Worker 重新解析 `requestedBy`，比较提交时 Scope snapshot，并按当前 License、
+   Feature 与 Permission 重新授权；
+2. 业务从持久事实取得 opaque session ID，调用 `getUploadSession` 获取服务端
+   `nextPartNumber` 与 `receivedByteSize`；
+3. 按该位置继续 `appendUploadPart`，全部写入后调用 `completeUpload`；
+4. 完成结果写回业务持久事实；同一会话重复 `completeUpload` 返回首次发布的同一文件。
+
+Host 在每个 Writer 调用上再次确认 session Owner 与当前模块注册 purpose。用户、Scope
+或 purpose 在 attempt 间漂移时立即 fail closed；Upload Repository 还保存创建时的
+module 与 canonical Scope hash，当前 binding 必须完全匹配。不允许历史或无 binding 的
+session ID 恢复旧授权，也不把底层存在性返回给业务。
+
+attempt 的 `AbortSignal` 会中止当前流和本次尚未提交的临时 Blob，但已通过 CAS 提交的
+分片继续保留，下一 attempt 可以恢复。取消不等于业务放弃：只有显式
+`abortUpload` 才删除该 session 的全部已提交分片；进程直接退出或来不及 abort 时，由
+`system.storage.cleanup` 按 session TTL 清理，未引用 Blob 继续受 orphan grace period
+保护和回收。abort intent CAS 前已观察到取消或 lease 丢失的旧 attempt 不能改变会话；
+若 CAS 已先提交为 `aborting`，该会话不再恢复上传，后续 attempt 或 TTL 只负责重放清理。
+确认放弃通常应由后续重新授权的 attempt 执行；进程内 Signal 不是数据库 lease fence。
+业务 Handler 不注册自己的上传清理 timer。终止本身按
+`uploading -> aborting -> aborted` 持久推进；只有 Blob 与 part 行清理完成才提交终态，
+失败或重启后的 attempt 可安全重放。
+
+Writer 统一记录 `file.upload.create`、`file.upload.part.write`、
+`file.upload.complete`、`file.upload.abort`。审计 target 只使用不透明 session/file
+ID，metadata 只按动作从 purpose、分片位置、大小、SHA-256 和幂等重放白名单取值；
+Module、Actor 与 request ID 来自本次 attempt，不能由 payload 覆盖，metadata 不包含
+文件内容或物理 locator。失败事件可额外记录稳定 `errorCode`，所有 Durable Writer
+事件还由 Host 加入 `jobId/attemptNumber`；这三项同样不能由 payload 覆盖。
+
+Handler 需要外部系统凭据时只能通过
+`requireModuleSecretPort(ModuleDurableHandlerContext)` 取得受治理 Port，并按 Manifest
+已声明的逻辑 handle/connection/purpose 请求。SDK 为旧 Context 测试桩保留 optional
+字段，但 Windy Host 每个 attempt 都注入新 Port；缺字段只返回稳定 unavailable，不存在
+env/file fallback。每次 resolve 都重新执行当前 License、Feature、Permission、binding
+状态和 SecretResolver；Job payload、进度、Failure 和 Artifact 元数据不保存 Secret
+或 locator。
 
 任务产物读取统一经过 `DurableArtifactService`：先按 `jobId + kind` 回读持久化元数据，再校验 Owner 或显式 manage 能力、留存时间、Blob 大小和 SHA-256。调用方不能凭 `ArtifactRef` 猜测下载；API 层仍需执行对应 RBAC Guard 并记录下载审计。