create-windy 0.5.1 → 0.6.0

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

@@ -6,7 +6,11 @@
 
 初始化器在 Storage 和 Durable Job Worker 创建前顺序执行，只允许登记定义，不启动监听、Worker 或后台循环。Host 扩展点：
 
-- `registerRoutes()`：注册 Guarded API 路由；`method + path` 与权限必须与 Manifest `apiPermissions` 声明一致，Guard（权限 / Feature / License）与 `security.denied` 审计由 `evaluateRouteGuards` 统一执行。声明 `auditAction` 时宿主在 Handler 成功后自动写审计；
+- `registerRoutes()`：注册 Guarded API 路由；`method + path` 与权限必须与 Manifest
+  `apiPermissions` 声明一致，Guard（权限 / Feature / License）与 `security.denied`
+  审计由 `evaluateRouteGuards` 统一执行。声明 `auditAction` 时宿主在 Handler 成功后
+  自动写审计；流式请求体必须显式声明 `bodyMode: "stream"`，由 Host 下发
+  `bodyStream` 与同请求 `signal`；
 - `registerTaskHandlers()`：为 Manifest `tasks` 已声明的定时任务注册执行体，调度元数据一律以 Manifest 为准；
 - `registerToolHandlers()`：为 Manifest `tools` 已声明的 Agent Tool 注册类型化 JSON 执行体，输入输出 Schema、`scopeMode` 与 Handler 均接入双向校验；
 - `registerRolePresets()`：注册角色预设，`permissionKeys` 必须属于本模块 Manifest 权限声明；预设并入内置角色同步（不存在则创建、漂移则非破坏性合并），不改变 4 个内置角色语义；
@@ -18,8 +22,17 @@
 - `registerResourceFileAccessPolicies()`：注册本模块业务资源到平台文件的受限读取
   Resolver；purpose 必须来自当前模块或 Manifest 显式依赖模块，resourceType、
   Feature、Permission 和 Audit Action 必须来自当前消费者模块；
+
+<!-- @windy-module system.storage begin -->
+
+- `registerReportStagingPolicy()`：注册本模块命名空间内的大报告暂存用途、允许的
+  Resource File purpose、保留期及 Host 资源上限；
+
+<!-- @windy-module system.storage end -->
+
 - `registerDurableHandler()`：注册强类型 payload parser 与模块 Durable Handler；执行时
-  由宿主重建当前 Actor 与提交时授权范围，并只额外提供受限资源文件读取 Port。
+  由宿主重建当前 Actor 与提交时授权范围，并提供模块作用域 Storage Writer 与受限资源
+  文件读取 Port。
 - `registerGovernedResources()`：为 Manifest `dataPolicies` 注册对象授权 Resolver、
   去除治理字段后的普通投影、受控字段值读取、可选 cursor 分页导出 Source，以及
   可选服务端 Renderer 和 Manifest 已声明的 masked/reveal/export Route；宿主负责
@@ -37,10 +50,23 @@
 - `jobs`：受限 Durable Job 控制 Port。提交只能使用本模块命名空间 Handler，Queue 与
   Actor 由宿主固定；读取、取消和人工恢复只返回最小投影，并在每次操作时重新执行当前
   路由的 Feature、Permission、License 与 Scope Guard；
+- `secrets`：只按本模块 Manifest 已声明的 handle/connection/purpose 短暂解析 Secret，
+  每次调用重做 License、Feature、Permission 与审计；不接受 locator，详见
+  [模块 Secret 解析 Port](./module-secret-resolution.md)；
+
+SDK 为旧 Context object literal 保留 optional `secrets` 字段；Windy Host 实际请求始终
+注入 Port，需要该能力的模块调用 `requireModuleSecretPort()`，缺失时稳定 fail closed。
 
 <!-- @windy-module system.storage begin -->
 
-- `storage`：受限 Upload/BlobRead Port（详见[对象存储](./object-storage.md)）；宿主未挂载时任何访问都以明确错误失败。
+- `storage`：保持 0.5.2 的 `ModuleStoragePort` create/read 契约；
+- `storageWriter?`：版本化 `ModuleStorageWritePortV1` additive seam，提供 `createUploadSession`、
+  `getUploadSession`、`appendUploadPart`、`completeUpload`、`abortUpload`，Owner、
+  Actor 和 Scope 均由 Host 固定；宿主未挂载时任何访问都以明确错误失败。完整生命周期
+  见[对象存储](./object-storage.md)。
+- `reportStaging?`：版本化 `ModuleReportStagingPortV1` additive seam；Host 负责
+  多卷源读取、真实 RAR5 能力探测、解压前预检、完整索引、read lease、逐次授权和
+  TTL purge，详见[受治理的大报告暂存](./report-staging.md)。
 
 <!-- @windy-module system.storage end -->
 
@@ -48,16 +74,49 @@
   启用用户只读最小投影；不暴露 Admin Repository，详见
   [业务模块只读用户目录](../platform/business-user-directory.md)。
 
-Agent Tool 也获得同一个 `storage` Interface，但 Port 在每次 Tool Invocation 内根据
-当前 Execution Grant 恢复的 Actor 与服务端 ScopeContext 重新构造；不会复用 Run
-创建时的权限快照。`scopeMode: "request"`、Tool 自身 Feature/Permission Guard、资源
-策略 Feature/Permission Guard 与业务 Resolver 必须全部通过。
+Agent Tool 保持既有 create/read `storage` Interface，不自动获得
+`ModuleStorageWritePortV1`。该既有 Port 在每次 Tool Invocation 内根据当前 Execution
+Grant 恢复的 Actor 与服务端 ScopeContext 重新构造；不会复用 Run 创建时的权限快照。
+`scopeMode: "request"`、Tool 自身 Feature/Permission Guard、资源策略
+Feature/Permission Guard 与业务 Resolver 必须全部通过。这样新增 Request / Durable
+Writer 不会把 append/complete/abort 或原始字节流扩散到 Agent 与 MCP。
+
+Agent Tool 不获得 `secrets` Interface。声明并绑定模块 Secret 不会把原始值下发给普通
+Tool 或 Sandbox Tool。
 
 Module Durable Handler 获得独立的 `ModuleDurableHandlerContext`。它不复用提交 HTTP
 请求对象，也不保存进程内闭包：宿主从持久化 Job 读取 `requestedBy` 与提交 Scope，
 每次执行重新解析当前用户与授权，Scope 漂移即拒绝。其 `storage` 只包含
 `openResourceFile()`，因此后台 Parser 可以按稳定业务资源绑定读取同案其他上传者的原件，
-但不能创建上传、按 Owner 任意读取或接触平台存储实现。
+但不能创建上传、按 Owner 任意读取或接触平台存储实现。可选 `storageWriter` 独立提供
+`ModuleStorageWritePortV1`，让后台 Handler 用 Host Actor 和当前模块 purpose 流式写入
+派生产物，不改变既有 `storage` Interface。
+其 `secrets` 每个 attempt 重新构造，每次 resolve 再读取当前 binding；轮换、停用和
+Guard 变化不会复用上一次 attempt 的解析结果。
+
+<!-- @windy-module system.storage begin -->
+
+可选 `reportStaging` 同样在每次 manifest、分页和 entry 读取前重新解析 Actor、提交时
+Scope 快照与 Durable Handler Guard；Solid RAR 重试从首卷重新扫描，不复用 attempt
+留下的部分解压目录。
+
+<!-- @windy-module system.storage end -->
+
+Writer 会话本身持久化在平台 Upload Repository。Durable Handler 必须把 opaque session
+ID 写入 payload 所引用的业务持久事实，或在提交 Job 前把它放入 payload；不能只保存在
+attempt 闭包。每次 attempt 先按当前 License、Feature、Permission 和 nominal Scope
+重建 Context，再允许 `getUploadSession/appendUploadPart/completeUpload/abortUpload`。
+Host 在创建时把 module 与 canonical Scope hash 作为不可伪造 binding 写入会话；当前
+Actor、Scope、module 或 Host 注册 purpose 与该 creation-time binding 不再匹配时
+fail closed，历史或无 binding 的 session ID 不能恢复旧授权。重复 `completeUpload`
+返回同一已发布文件，不产生第二份 Blob。
+
+HTTP `bodyMode: "stream"` Route 的 `ModuleRequestContext` 同时提供 `bodyStream` 与
+`signal`。`bodyStream` 不经过 JSON 解析或完整缓冲，Writer 等待底层当前写入后才继续
+拉取，形成端到端背压；请求取消会取消当前尚未提交的临时 Blob，但保留已提交分片供
+后续请求恢复。Durable attempt 的 `signal` 遵循相同语义。只有显式 `abortUpload` 或
+平台 session TTL 才终结整个未完成会话；orphan grace period 负责回收未被元数据引用的
+Blob。
 
 `ModuleRequestContext.jobs` 提供 `submit/get/cancel/recover`，但不下发 Repository、
 Worker 或 Queue 选择权。控制操作同时要求任务 Queue/Handler 属于当前模块、任务提交人
@@ -105,7 +164,11 @@ MIME、扩展名和 records/bytes/timeout 上限；请求固化选择，恢复
 
 - Host Interface 只承载跨模块稳定能力，不暴露数据库连接或业务 Repository。
 - 初始化器不得跨模块注册 key，也不得依赖注册顺序读取另一个模块的私有状态。
-- 上传授权仍由 Server Route Guard 和文件 Owner/RBAC 负责；注册策略不等于获得上传权限。
+- 上传授权仍由 Server Route / Durable Handler Guard、Host Owner、当前注册 purpose
+  以及持久化的 module/Scope binding 共同负责；注册策略不等于获得上传权限，session ID
+  也不能代替当前授权。
+- Storage Writer DTO 不接受 tenant、Actor、Owner、Scope、Permission、ArtifactRef 或
+  物理 locator；这些字段即使由调用方伪造也不能进入底层调用或审计 metadata。
 - 跨上传者资源读取只允许通过资源策略：Resolver 只返回授权判定，必须回查业务关联，
   不能返回或下发 Repository；直接 fileId、文件名或不可猜引用都不能代替资源授权。
 

package/template/docs/architecture/module-manifest-composition.md

@@ -13,7 +13,7 @@ Manifest 当前覆盖：
 
 - Feature、Permission、API Route、Admin Route 与菜单 Surface；
 - Migration 与 Schema Export 证据；
-- Scheduled Task、Agent Tool、Provider 与 Audit Action；
+- Scheduled Task、Agent Tool、Provider、模块 Secret 与 Audit Action；
 - Feature 依赖与可用 License 版本；
 - 模块依赖及版本元数据。
 
@@ -22,7 +22,7 @@ Manifest 当前覆盖：
 组合校验在运行时业务逻辑前执行，并拒绝：
 
 1. 缺失依赖、依赖循环及同类能力重复 Key；
-2. Menu、Admin Route、API、Task、Tool、Provider 对未知 Permission 或 Feature 的引用；
+2. Menu、Admin Route、API、Task、Tool、Provider、Secret 对未知 Permission 或 Feature 的引用；
 3. 未定义或重复的业务 Audit Action，以及 Tool 对未知 Audit Action 的引用；
 4. Feature 的未知依赖、自依赖、循环依赖和未知 License 版本；
 5. Menu 与 Admin Route 路径或 Guard 漂移；
@@ -87,6 +87,9 @@ Migration、Worker 与监听。不存在“构建通过、启动时才第一次
   监听前验证。Durable Handler 还必须绑定 Manifest 中同一能力的 Feature、Permission
   与 Audit Action；Host 冻结该绑定，并在每次首次执行、重试和恢复领取时按当前
   Actor、License、Feature 与 RBAC 状态重新 Guard。
+- 模块 Secret 只在 Manifest 声明稳定 handle/connection/purpose 与治理绑定，物理
+  `SecretRef` 由 project-owned Composition 提供；locator、跨模块 binding 和未知引用
+  在监听前 fail closed。运行边界见[模块 Secret 解析 Port](./module-secret-resolution.md)。
 - 业务模块可在 `auditActions` 中直接注册包含 Key、名称和说明的动作定义；组合后的
   Audit Action Catalog 与 License Catalog 会通过 Foundation / Admin Bootstrap 契约开放，
   管理端筛选与展示不维护第二份静态业务 Key。

package/template/docs/architecture/module-secret-resolution.md

@@ -0,0 +1,250 @@
+# 模块 Secret 解析 Port
+
+## 目标与边界
+
+业务模块连接 SMB、SFTP 等外部系统时，需要在服务端最后时刻取得凭据，但不能获得任意
+环境变量名、文件路径或平台 Secret Registry。Windy 将声明、物理绑定和运行时使用拆成
+三层：
+
+1. 业务 Module Manifest 只声明稳定的 `handle + connection + purpose` 逻辑三元组，
+   以及 Feature、Permission、License 映射和 Audit Action；
+2. project-owned Server Composition 使用宿主持有的 `SecretRef` / `SecretResolver`
+   提供物理 binding，动态业务 package 不能自行注入 env/file locator；
+3. Request 或 Durable Handler 通过 `ModuleSecretPort.resolve()` 的短生命周期回调使用
+   原始值，Host 在每次调用时重新 Guard、解析和审计。
+
+该 Port 不取代类型化平台配置。Endpoint、Host、端口、超时和非敏感连接选项仍进入模块
+自己的严格配置；Secret Port 只负责凭据值。Manifest、API body、Job payload、Tool 参数
+和业务表都不保存 `SecretRef`、locator 或明文。
+
+## Manifest 契约
+
+示例模块 `archive` 声明 SMB 只读密码：
+
+```ts
+{
+  handle: "archive.smb.password",
+  connection: "archive.smb.primary",
+  purpose: "archive.smb.read",
+  featureKey: "archive.external-storage",
+  permissionKey: "archive.external-storage.read",
+  auditAction: "archive.secret.resolve",
+}
+```
+
+`handle`、`connection` 和 `purpose` 都必须是最多 128 字符的小写稳定 Key，并位于当前
+模块命名空间；换行、NUL、路径、env 风格大写下划线和前后空白均不合法。每个 handle
+全局唯一；声明只能包含这三个逻辑字段和治理字段，出现 `provider`、`locator`、env key、
+文件路径或其它未知字段时，Module Composition 在 Server 监听前失败。
+
+Secret 声明与其它能力执行同一门禁：
+
+- Permission、Feature 与 Audit Action 必须由拥有该 Secret 的同一 Manifest 注册，
+  只在其它模块或全局 Catalog 中存在仍视为未注册；
+- Permission 必须存在同基础 Key Feature；
+- Feature 可用 `allowedLicenseVersions` 声明商业版本；
+- Audit Action 必须在 Manifest `auditActions` 注册；
+- 未知 Feature、Permission、Audit、重复 handle 和命名空间漂移全部 fail closed。
+
+## project-owned 物理绑定
+
+物理 locator 只出现在客户拥有的 `apps/server/src/app/server-composition.ts`。Host 提供
+由发布包 `@southwind-ai/server-sdk` 根导出的 `createModuleSecretBinding()`，把既有
+`SecretRef` / `SecretResolver` 适配为 Composition binding。项目不得导入
+`apps/server/src/module-host/**` 私有实现：
+
+```ts
+import { EnvironmentSecretResolver, SecretRef } from "@southwind-ai/config";
+import {
+  createModuleSecretBinding,
+  defineWindyServerComposition,
+} from "@southwind-ai/server-sdk";
+
+const environmentSecrets = new EnvironmentSecretResolver(process.env);
+
+export const serverCompositionDeclaration = defineWindyServerComposition({
+  assembly: moduleAssembly,
+  adapters: projectAdapters,
+  attachments: projectAttachments,
+  secretBindings: [
+    createModuleSecretBinding({
+      moduleName: "archive",
+      handle: "archive.smb.password",
+      connection: "archive.smb.primary",
+      purpose: "archive.smb.read",
+      reference: new SecretRef("env", "ARCHIVE_SMB_PASSWORD"),
+      resolver: environmentSecrets,
+      enabled: () => process.env.ARCHIVE_SMB_ENABLED === "true",
+    }),
+  ],
+});
+```
+
+示例使用 env 说明接线，不表示生产必须使用 env。生产可以注入受保护文件、Vault 或其它
+实现相同 `SecretResolver` 契约的宿主 Adapter。业务 package 看不到 binding、Resolver
+或 `SecretRef`。Host 会拒绝未安装模块、跨模块命名空间、Manifest 未声明和重复 binding。
+
+`enabled()` 是宿主状态，不由模块或客户端提交。停用后解析返回稳定
+`MODULE_SECRET_DISABLED`；缺少值、binding 或 Resolver 故障返回
+`MODULE_SECRET_UNAVAILABLE`，错误不包含底层异常、locator 或值。
+
+## Request 与 Durable 使用
+
+业务代码必须把三元组定义为服务端常量，不能从 body、Tool 参数或 Job payload 接受：
+
+Request Handler 使用兼容旧 Context 的 helper；缺少 Port 时会抛出稳定 unavailable，
+不会静默跳过连接：
+
+```ts
+import {
+  requireModuleSecretPort,
+  type ModuleRequestContext,
+} from "@southwind-ai/server-sdk";
+
+declare function connectSmb(input: {
+  readonly connectionKey: string;
+  readonly password: string;
+}): Promise<{
+  listNames(cursor?: string): Promise<readonly string[]>;
+  close(): Promise<void>;
+}>;
+
+const smbSecret = {
+  handle: "archive.smb.password",
+  connection: "archive.smb.primary",
+  purpose: "archive.smb.read",
+} as const;
+
+async function listArchive(
+  context: ModuleRequestContext,
+  input: { readonly cursor?: string },
+): Promise<{ readonly names: readonly string[] }> {
+  const secrets = requireModuleSecretPort(context);
+  return secrets.resolve(smbSecret, async (password) => {
+    const client = await connectSmb({
+      connectionKey: smbSecret.connection,
+      password,
+    });
+    try {
+      return { names: await client.listNames(input.cursor) };
+    } finally {
+      await client.close();
+    }
+  });
+}
+```
+
+Durable Handler 每个 attempt 同样必须通过 helper 获取 Port：
+
+```ts
+import {
+  requireModuleSecretPort,
+  type ModuleDurableHandlerContext,
+} from "@southwind-ai/server-sdk";
+
+declare function connectSmb(input: {
+  readonly connectionKey: string;
+  readonly password: string;
+}): Promise<{
+  sync(): Promise<void>;
+  close(): Promise<void>;
+}>;
+
+const smbSecret = {
+  handle: "archive.smb.password",
+  connection: "archive.smb.primary",
+  purpose: "archive.smb.read",
+} as const;
+
+async function syncArchive(
+  context: ModuleDurableHandlerContext,
+): Promise<void> {
+  const secrets = requireModuleSecretPort(context);
+  await secrets.resolve(smbSecret, async (password) => {
+    const client = await connectSmb({
+      connectionKey: smbSecret.connection,
+      password,
+    });
+    try {
+      await client.sync();
+    } finally {
+      await client.close();
+    }
+  });
+}
+```
+
+原始值只在回调内短暂可见。Host 不信任 TypeScript 返回类型，而是把结果 canonicalize
+为新的深冻结 JSON snapshot：只接受 `null`、boolean、有限 number、string、稠密 array
+和 plain object；拒绝 accessor、Proxy、symbol、危险 key、非普通 prototype、循环、
+非 JSON 值以及过深、过宽、过大的结果。Key 和 string value 都会检查当前原始 Secret。
+验证、反射或快照异常统一返回 `MODULE_SECRET_EXPOSURE_BLOCKED`，回调或底层 Resolver
+异常则替换为其它稳定脱敏错误；原 live object 不会返回给调用方。
+
+公开 Context 中 `secrets` 为兼容旧 SDK object literal 的 optional 字段。Windy Host 在
+Request 和每个 Durable attempt 都始终注入受治理 Port；模块通过
+`requireModuleSecretPort(context)` 显式取得它。旧测试桩或 Adapter 缺字段时 helper
+直接抛稳定 `MODULE_SECRET_UNAVAILABLE`，不会回退到 env、文件或全局 Registry。
+
+Durable Worker 每次首次执行、自动重试和恢复都会重建 Actor、重新执行 Handler Guard，
+并创建新的 Secret Port。Port 调用时再次按 Secret 声明执行 License、Feature 和
+Permission Guard，然后调用当前 binding；不缓存此前 attempt 的值或解析结果。因此受
+保护文件或动态 Resolver 的轮换在下一次 resolve 生效，`enabled()` 停用也立即阻断下一次
+调用。
+
+## Agent Tool 暴露边界
+
+`ModuleToolContext` 和 Sandbox Tool Context 都没有 `secrets` 字段。即使模块 Manifest
+声明并由项目绑定 Secret，普通 Agent Tool 也不能通过 Host Port 取得原始值，binding 的
+Resolver 不会被调用。
+
+需要外部连接的 Agent 能力应把凭据使用封装在可信的服务端业务操作中，并只向 Tool
+返回脱敏业务结果；当前契约不提供 Tool 原始 Secret opt-in。纯计算 Sandbox Tool 继续
+保持无 Secret、无 Repository、无网络。若未来确需 Tool 直连外部系统，必须另行设计不
+暴露原始凭据的 Host Adapter，而不是给 `ModuleToolContext` 增加字符串 Secret。
+
+## 审计与失败语义
+
+每次已声明 resolve 都记录声明的 Audit Action：
+
+- `success`：只记录 handle target、逻辑 connection/purpose 和 `resolved` 语义；
+- `denied`：记录稳定的 Guard 原因或 `disabled`；
+- `failure`：记录 `binding-unavailable`、`resolver-failed`、
+  `operation-failed` 或 `exposure-blocked`。
+
+未声明或跨模块三元组使用同形 `MODULE_SECRET_NOT_DECLARED`，并写不包含调用方输入的
+`security.denied`。Provider 的 version 属于敏感、不可信输入，既不原样记录，也不做可
+离线字典确认的无密钥摘要；轮换由每个 attempt 重新解析和新的 `resolved` 事件表达，
+当前不提供跨事件 provider version 相关性。
+
+业务模块仍是可信 Server 代码：Host 能阻止当前 Secret 经平台返回值、错误与事件的意外
+泄漏，但不能识别回调返回的其它未知凭据，也不能把故意通过网络或其它副作用发送凭据的
+恶意模块变成安全代码。这些边界必须继续通过代码审查、模块来源治理和网络策略控制。
+
+## 利剑 SMB / SFTP 接入
+
+利剑升级到包含该契约的 Windy 版本后，按以下方式接入，不需要修改 Windy 的配置
+Registry 或 Agent Tool Runtime：
+
+1. 在拥有 SMB/SFTP 同步能力的利剑 Module Manifest 分别声明 password/private-key
+   handle、稳定 connection/purpose，以及同基础 Key Feature、Permission 和审计动作；
+2. 在利剑 project-owned `server-composition.ts` 为每个声明添加
+   SDK 根导出的 `createModuleSecretBinding()`，生产 Resolver 指向客户批准的 Secret
+   Store；
+3. Route/Service 在一次连接操作内使用
+   `requireModuleSecretPort(context).resolve()`，及时关闭 SMB/SFTP client，只返回文件
+   业务元数据或导入结果；
+4. 后台同步同样使用 `requireModuleSecretPort(context)`，不要把凭据、locator 或
+   provider version 写进 payload；重试和恢复自然取得当前轮换值；
+5. Agent Tool 只查询已落库或由可信业务服务投影的结果，不把 password、private key、
+   endpoint query 或底层连接异常返回给模型。
+
+SMB password 与 SFTP password/private key 应使用不同 handle，读、写、导入等 purpose
+也应分开声明；不要用一个“万能连接 Secret”跨协议、跨动作或跨模块复用。
+
+## 验证范围
+
+定向测试覆盖 Manifest locator 拒绝、物理 binding 双向匹配、跨模块/未声明三元组、
+Permission/Feature/License 拒绝、动态停用、轮换、Durable attempt 重新解析、
+Agent Tool 无 Port、审计成功/拒绝/失败和结果/错误/provider version 脱敏。完整合并与发布矩阵仍由
+合并候选和发版候选门禁统一执行。

package/template/docs/architecture/object-storage.md

@@ -5,7 +5,8 @@
 `@southwind-ai/storage` 是平台文件能力的唯一底层模块。`BlobStore` 只供平台 Storage
 实现使用：流式写入、流式打开和删除；文件名、MIME、上传会话、Owner、权限与审计不
 进入这个底层接口，由上层上传模块统一处理。可安装业务模块只学习
-`@southwind-ai/server-sdk` 的 `ModuleStoragePort`。
+`@southwind-ai/server-sdk` 的既有 create/read Port，以及只向 Request / Durable
+Context 开放的模块作用域 Storage Writer。
 
 `ArtifactRef` 使用 `blob_` 加 128 位随机值，不包含目录、租户或内容摘要，不能由业务主键推算。`ContentHash` 当前固定为 SHA-256。调用方可以声明大小和摘要，本地 Adapter 会在写入过程中验证；任何不一致都不会发布 Blob。
 
@@ -34,7 +35,13 @@
 
 PostgreSQL 通过 `file_upload_sessions`、`file_upload_parts` 和 `file_metadata` 持久化会话进度及最终文件。分片提交使用 `received_byte_size + next_part_number` compare-and-set；最终 Blob 与 FileMetadata 只有数据库状态切换成功后才发布为完成状态。
 
-清理任务先删除已过期会话的分片和已过期文件，再将数据库仍引用的 `ArtifactRef` 集合交给 `LocalFileBlobMaintenance`。本地维护器只删除超过 grace period 的临时文件或未引用 Blob，避免与正在提交的上传竞争。生产应由 Scheduler 周期调用清理入口；grace period 默认一小时。
+清理任务先以持久化 CAS 把已过期、未完成会话 claim 为 `expired`，再删除已 claim
+会话及其分片行；只有数据库删除成功后才删除捕获的 Blob 引用。完成先提交时 claim
+失败，清理不能删除；清理先 claim 时 append/complete CAS 失败，不能发布。claim 或
+数据库删除失败时不删除 Blob；数据库删除后退出留下的孤儿由引用集合和 grace period
+收口。随后清理已过期文件，并将数据库仍引用的 `ArtifactRef` 集合交给
+`LocalFileBlobMaintenance`。生产应由 Scheduler 周期调用清理入口；grace period
+默认一小时。
 
 ## 授权下载与业务接入
 
@@ -52,6 +59,12 @@ Logo 使用 `branding-logo` 上传策略。匿名 `/api/platform/files/:id` 只
 
 - `WINDY_BLOB_DRIVER`：当前生产 Adapter 为 `local`；配置未知驱动时启动失败，不静默回退。
 - `WINDY_STORAGE_ROOT`：本地持久目录，默认 `.data/storage`。Compose 使用独立 named volume 挂载 `/app/data/storage`。
+
+大体积归档或已展开报告的随机读取不由业务模块直接落盘；它通过
+[受治理的大报告暂存](./report-staging.md) 复用 Resource File 授权，并默认使用
+`WINDY_STORAGE_ROOT/report-staging`。需要独立 volume 时可设置
+`WINDY_REPORT_STAGING_ROOT`。
+
 - S3-compatible 支持保留在 `BlobStore` seam；当前不强制安装云 SDK。未来 Adapter 必须保持流式读写、服务端摘要验证、不可猜引用、明确删除与损坏语义，不能让业务模块学习 bucket/key。
 
 ## 故障语义
@@ -61,7 +74,7 @@ Logo 使用 `branding-logo` 上传策略。匿名 `/api/platform/files/:id` 只
 - 删除为幂等操作；第一次存在时返回 `true`，重复删除返回 `false`。
 - 进程在 Blob 发布与元数据发布之间退出时可能产生孤儿内容；上传生命周期模块基于过期时间、引用集合与 grace period 清理。
 
-## 模块受限 Upload/BlobRead Port
+## 模块既有 create/read Port
 
 业务模块不直接使用 `UploadService` / `FileService`，而是经
 `ModuleRequestContext.storage` 或 `ModuleToolContext.storage` 获得
@@ -87,6 +100,132 @@ Logo 使用 `branding-logo` 上传策略。匿名 `/api/platform/files/:id` 只
 读取。Feature、Permission、Audit Action 和 resourceType 仍必须属于当前消费者模块，
 任一未知或越界都会在监听前失败。
 
+## 模块作用域流式写入
+
+`ModuleStorageWritePortV1` 只把既有 `UploadService` 的会话状态机收窄为五个生命周期
+方法，不创建第二套上传引擎。为保持 0.5.2 C1 源码兼容，
+`ModuleRequestContext.storage` 与 `ModuleDurableHandlerContext.storage` 保持原
+create/read 及 `openResourceFile()` 契约；Writer 通过可选 `storageWriter` 独立注入。
+业务用 `requireModuleStorageWritePortV1(context)` fail closed 获取：
+
+| 方法                  | 语义                                           |
+| --------------------- | ---------------------------------------------- |
+| `createUploadSession` | 以当前 Host Actor 和已注册 purpose 创建会话    |
+| `getUploadSession`    | 读取当前会话的服务端续传位置和终态最小投影     |
+| `appendUploadPart`    | 向服务端给出的下一分片号和偏移流式写入一个分片 |
+| `completeUpload`      | 校验总大小和 SHA-256，并发布最终文件           |
+| `abortUpload`         | 显式终止未完成会话并删除其已提交分片           |
+
+SDK Writer DTO 只包含业务上传需要的文件名、MIME、声明大小、可选 SHA-256、purpose、opaque
+session ID、分片流及最小进度/文件结果。输入和输出都不得包含 `tenantId`、`actorId`、
+`ownerId`、Permission/Scope 快照、`ArtifactRef`、bucket/key、主机路径、URL 或其它物理
+locator。业务可以持久化 opaque session ID 以续传，但不能解析或据此扩权。
+Writer 创建输入也不接受绝对 `fileExpiresAt`；Host 从 purpose 对应 Upload Policy 的
+`fileRetentionMs` 派生过期时间，缺失、非安全整数、小于一分钟或大于 365 天均 fail
+closed。旧 `ModuleStoragePort.createUploadSession` 的绝对过期时间行为只为 0.5.2
+兼容保留，不能被 Writer V1 复用。
+Writer 失败统一投影为 `ModuleStorageError` 的稳定 code；可修正的大小、SHA、顺序、
+过期、取消和并发状态保持可判定，未知 Blob/文件系统异常只返回
+`STORAGE_WRITE_FAILED`，不透传主机路径或底层异常正文。
+
+Host 使用当前请求或 Durable attempt 重建的 Actor 填充 Owner；创建时校验 Host 注册的
+purpose，其余四个 Writer 方法每次调用都回读服务端会话，确认 Owner 与当前模块已注册
+purpose 仍然匹配。模块 Writer 创建会话时还会把 Host 生成的模块名与 creation-time
+canonical Scope hash 持久化到 Upload Repository；后续每次 get/append/complete/abort
+都必须与当前 Host binding 完全一致。session ID、客户端声明的 purpose 或历史成功结果
+都不是授权事实。跨模块用途、平台基础用途、当前注册已移除、历史无 binding 会话以及
+Actor/Scope 漂移均 fail closed；底层不存在、越权和不匹配不会泄漏 Owner、文件或存储
+实现细节。
+
+### HTTP 流与背压
+
+模块 HTTP Route 仅可在 `POST` / `PUT` 上显式声明 `bodyMode: "stream"`；声明后，
+Context 才通过 `bodyStream` 接收未解析的请求体流。Host 把同一 Context 的 `signal`
+与 Writer 绑定。`appendUploadPart` 直接把 `ReadableStream` 交给既有
+`UploadService.appendPart()`，不会先转为字符串、`ArrayBuffer` 或完整 Buffer。底层
+Blob Adapter 每写完当前块才拉取下一块，因此客户端发送速度会自然受存储写入速度背压。
+普通 JSON Route 保持原有 `body` 解析契约，不能借 body 字段伪造流、Actor 或 scope。
+Route Guard 拒绝时 Host 会立即取消未消费的请求流，不让无权限请求继续占用上传带宽。
+
+分片的声明大小和 SHA-256 由 Blob Adapter 在流经存储时校验；完成时再次校验会话声明的
+总大小和总 SHA-256。`getUploadSession` 返回的 `nextPartNumber` 与
+`receivedByteSize` 是服务端接收事实；调用方按这两个值回传分片号与偏移，不能通过旧
+偏移或并发请求覆盖已提交进度。
+
+### 完成、取消与清理
+
+`completeUpload` 是终态幂等操作：同一 Owner、模块和 purpose 对已完成会话重放时返回
+首次发布的同一文件最小投影，不创建第二个 FileMetadata 或 Blob。并发完成仍由上传
+Repository 的 CAS 决定唯一胜者；失败方回读终态后得到同一结果。Owner、purpose 或当前
+授权不匹配时，即使会话已经完成也不得返回结果。
+
+请求或 Durable attempt 被取消，或者当前分片写入/完整性校验失败时，Writer 停止当前流，
+并只清理由本次尚未提交的临时 Blob。此前已通过 CAS 提交的分片和 `uploading` 会话继续
+保留，使调用方可以在下一次请求或 attempt 中调用 `getUploadSession` 后恢复；取消不能
+伪装成已经 `abortUpload`。业务确认放弃时显式调用 `abortUpload`，由既有上传服务删除
+全部已提交分片。进程在来不及 abort 时退出，则由 `system.storage.cleanup` 按 session
+TTL 清理；Blob 先发布但元数据未提交产生的孤儿仍由引用集合和 orphan grace period
+收口，不能为模块另建清理循环。
+
+在 abort intent CAS 前已观察到取消的旧 Request/attempt 会以 `UPLOAD_CANCELLED`
+fail closed，不改变会话；业务随后确认放弃时，必须在新的、重新通过 Guard 的
+Request/attempt 中调用 `abortUpload`。若 `aborting` CAS 已先提交，取消只停止后续清理，
+会话不再恢复为 uploading，由下一次重放或 TTL 完成终止。这是 Storage CAS 与进程内
+AbortSignal 之间的明确竞态边界，不把信号描述成数据库 lease fence。完成提交后的分片
+清理为 best effort：重复 `completeUpload` 会继续收口残留行；已完成/已终止会话的分片
+Blob 不再计入活跃引用集合，因此物理删除失败仍可由 orphan cleanup 回收。
+
+显式终止使用可重放状态机 `uploading -> aborting -> aborted`。进入 `aborting` 后先按仍
+持久化的 part 引用幂等删除 Blob，再删除 part 行；只有 Repository 确认分片行为空后才
+提交 `aborted`。Blob 删除、行删除、取消或进程退出都只会留下可恢复的 `aborting`，
+下一次 `abortUpload` 从持久事实继续。兼容升级前可能存在的 `aborted + part` 残留时，
+重放也必须继续清理，不能把终态本身当作清理完成证明。`aborting` 分片仍属于活跃引用，
+避免 orphan maintenance 与恢复竞争；会话超过 TTL 后仍由统一 cleanup 删除。
+
+`0048_illegal_magneto.sql` 为 `file_upload_sessions` 增加 nullable 的
+`module_name/authorization_scope_hash` 成对约束。平台原生上传保持两列都为空；历史模块
+会话无法安全回填 creation-time Scope，因此 Module Writer 对无 binding 会话 fail closed，
+由调用方新建会话或等待 TTL 清理，不能猜测回填。
+
+### 审计白名单
+
+Host 统一写入四类内置普通审计，模块不能改写动作 Key；每类记录只从以下 metadata
+白名单中按实际结果取值：
+
+- `file.upload.create`：purpose、声明总大小、声明 SHA-256；
+- `file.upload.part.write`：purpose、part number、offset、分片大小与 SHA-256；
+- `file.upload.complete`：purpose、总大小、SHA-256，以及是否为幂等重放；
+- `file.upload.abort`：purpose，以及适用时的幂等重放标记。
+
+失败事件额外记录稳定 `errorCode`；Durable 事件由 Host 加入 `jobId` 与
+`attemptNumber`。这些字段都来自平台执行事实，模块和 payload 不能覆盖。
+Module、Actor、Request ID 和时间由平台审计上下文补齐；target 使用当前 session 或
+最终 file 的不透明 ID。审计 metadata 不记录文件内容、文件名、客户端身份/Scope 字段、
+`ArtifactRef`、路径、URL、bucket/key 或底层异常正文。Route / Durable Guard 拒绝继续
+使用统一 `security.denied`，Writer 自身的 purpose/Owner 拒绝也只返回稳定错误，不把
+物理事实变成探测面。
+`getUploadSession` 的 Owner/purpose 同形拒绝额外记录稳定 `security.denied`，不会把
+会话存在性、Owner 或底层错误写入审计。
+
+### 下游接入
+
+1. 在业务模块 `setup(host)` 注册命名空间内 Upload Policy，并在 Manifest Route 或
+   Durable Handler 上绑定真实 Feature、Permission 与审计能力。
+2. HTTP 上传 Route 声明 `bodyMode: "stream"`；后台写入把 opaque session ID 保存到
+   Durable payload 所引用的业务持久事实中，不能只保存在闭包或进程内变量。
+3. 首次调用 `createUploadSession`；重试或恢复先调用 `getUploadSession`，再按服务端
+   位置顺序调用 `appendUploadPart`。
+4. 全部字节写入后调用 `completeUpload`，只持久化返回的 file ID；明确放弃时调用
+   `abortUpload`。
+5. Agent Tool 不自动获得该 Writer；需要模型发起写操作时，仍须另行完成审批、幂等和
+   可追踪结果契约，不能从 JSON Tool 参数绕过 HTTP / Durable 边界。
+
+真实重启集成只在显式提供 `STORAGE_TEST_DATABASE_URL` 时运行，并使用生产
+`DrizzleUploadRepository + LocalFileBlobStore` 重新构造 HTTP Server 与 Durable
+Context。未提供 URL 时该 PostgreSQL 证据明确为 skipped；独立的 filesystem
+checkpoint 测试只证明 Host/Durable/Blob 对象不复用时仍可恢复，不替代生产数据库持久性
+验收。
+
 ## 当前切片
 
 - F1：Blob 端口、SHA-256、随机引用和本地流式 Adapter 已完成。
@@ -95,3 +234,5 @@ Logo 使用 `branding-logo` 上传策略。匿名 `/api/platform/files/:id` 只
 - F4：模块受限 Upload/BlobRead Port 已完成，业务模块经 Host 注册用途并受命名空间约束。
 - F5：Route 与 Tool 共用资源绑定读取 Port，支持受审计、受数据范围约束的跨上传者
   业务文件流读取，不扩散 Storage/Admin Repository。
+- F6：Request 与 Durable Context 共用模块作用域 Storage Writer，复用既有上传会话、
+  背压、完整性校验和清理状态机，并保持 Tool 写入边界关闭。