DEV-X-03-001 公共文件引用与释放契约
本页规定WP-STORAGE-001的跨仓边界，实际wire类型和发布能力以producer docs/openapi/file-reference-v1.json、Platform docs/openapi/platform.json及Runtime server/client类型为源。目标合同与已发布路由分别核对，不复制第二套运行时类型。
按ADR-0024，本期调用方与服务端统一交付以下新契约，不承担旧Platform/Runtime/产品对象协议、旧开发数据或跨版本兼容回退。现有源码中的历史入口是否仍存在，以具名实现为准；不能由本文推定已删除代码。
文件Owner接口
共同前缀/internal/files/v1。每次请求需专用Bearer与X-Oceanway-File-Principal，不用旧客户TokenAuth。首次adopt源用户/项目/namespace来自服务端配置；描述、首次retain及读授权另需短期签名grant。仅file_ref或浏览器scope不构成授权。
| 路径 | 输入与责任 | 结果/恢复 |
|---|---|---|
POST /files/adoptions | 稳定command、已授权永久Asset、原subject/product/Operation；仅获准adopter | 同file_ref/revision与platform output claim；原位核验，不Put/Copy |
POST /files/original-outputs | 专用principal与稳定command、原task_id、output_index及可信scope；只接受新lane已登记的永久原输出 | 返回同FileReferenceReceipt；不收任意asset、URL、bucket/key或字节，不触发生成、Put或Copy |
GET /files/:file_ref/revisions/:revision | 现有有效grant与固定版本 | 验证元数据/临时grant，不返回物理位置 |
POST /files/:file_ref/retentions | 稳定command、revision、purpose/reference_id及有效来源grant | 调用方自有claim；提交未知恢复原命令，不新建意图 |
POST /claims/renew | 原创建command_id、file_ref/revision、完整scope、purpose/reference_id，claim_ref可用于额外核对 | 无需旧grant；按principal+namespace+原命令严格查已有active claim，返回同claim/新grant；404不创建、410不复活released |
POST /claims/:claim_ref/release | 稳定release command_id、claim_command_id、file_ref/revision、完整scope/purpose/reference_id | 专用身份与完全原意图证明caller-owned；不依赖grant有效期。同release命令可重放已released，异命令409；不返回可读grant、不删原件 |
POST /files/:file_ref/read-authorizations | 有效grant、固定revision、GET/HEAD | 有界短期读取能力；过期重新核已有保留，不重新生成或另存 |
新链所有release请求统一提供完整owned proof，不交付仅command_id加grant的旧释放协议适配。跨principal、namespace、subject、product、Operation、file/version、purpose/reference与原命令的任何不符均拒绝。
scope固定为{subject_id, product, operation_id}。文件receipt包含file_ref、revision、sha256、十进制字符串byte_length、content_type、save_receipt_id、storage_class: "permanent"、file_state: "ready"、claim_ref及scope；access_grant仅在服务调用栈传递。释放成功仅返回{claim_ref, released: true}，不返回可读授权。
续签及完整proof释放的错误边界为：原创建命令或caller-owned claim不存在404；subject/product/Operation不符403；文件/版本、purpose/reference或原命令身份冲突409；续签已释放claim为410；proof缺字段、部分提供或必要字段为null均为400，不降级为其它授权方式。
claim恢复不Get对象正文、不Put/Copy，不新增保留；admission停新时原恢复/释放仍可用。读取和续签遇后端配置漂移时拒绝，不按新backend错误定位旧对象。完整owned-proof释放只核登记的原身份，无需未过期grant、对象在线或当前backend匹配；保留与读取能力必须分别判断。
当前选定的TOS S3北京profile显式配置S3_ENDPOINT=https://tos-s3-cn-beijing.volces.com、S3_REGION=cn-beijing和S3_FORCE_PATH_STYLE=false，使用virtual-host寻址；endpoint不包含bucket名。永久桶由OCEANWAY_FILE_BRIDGE_PERMANENT_BUCKET独立指定，必须与ASSET_LIBRARY_BUCKET相同、与媒体临时桶S3_BUCKET不同，并且不得配置物理到期规则。不得将S3_BUCKET改设为永久桶来绕过该约束。
该profile使用服务已有配置能力，不改变既有默认值或现网环境。各环境启用前须具名核对endpoint、region、bucket、寻址方式及永久桶策略；不得通过放宽IAM权限规避InvalidPathAccess，也不得据一个环境的配置推定其它环境可用。
Platform与Runtime
Platform仅把原Operation/输出序号及可信原结果绑定到同文件。首次绑定严格核原SHA/length/MIME；URL/ref-only无可信原摘要不能登记。新产品输出、引用Writer及读取按统一版本接入，不维护旧Platform Base64/字节输出的双轨协议；供应商结果格式由媒体调度适配，不将其等同于产品旧协议兼容。
当前新来源首切为原生异步图片。Platform的OCEANWAY_PLATFORM_FILE_ORIGINAL_OUTPUT_ENABLED=true显式开启、默认关闭，仅可信产品调用且文件桥配置/新准入成立、native与文件Owner origin相同时启用；服务端将namespace冻结于原price snapshot，并以私有X-Oceanway-File-Output-Namespace提交，浏览器不提供该值。producer在原归档写点形成一份永久原件及原task/index登记；原生查询仅返回output_refs中的index/SHA/十进制长度/MIME，不再把该lane的URL或Base64带回Platform。Platform使用冻结的原task描述，manifest缺mapping时持久化稳定命令并调用original-outputs自动采用，不下载再上传，也不要求客户端先提供AssetID。混合字节/引用、不同task/index/namespace、摘要或长度不符均拒绝。停新不改变已发任务的原来源和恢复模式。
Studio/Drama可信host的新图片请求显式声明output_contract: "oceanway.platform.file-output.v1"，从首次准备时写入原媒体请求及请求指纹。Platform在报价、预留资金和供应提交前验证该契约要求的原输出模式、文件桥、新准入及来源配置；未齐时提前拒绝，不能先付费生成普通URL/字节再因manifest缺失失败。显式空值、null、未知契约及不支持的媒体组合均拒绝。产品原请求恢复和manifest读取必须核同一冻结声明，不新增字节回退。未声明的现用普通客户接口保留原有行为。
严格停新增引用任务时，保持已选原输出模式，关闭文件桥新增准入；仅将OCEANWAY_PLATFORM_FILE_ORIGINAL_OUTPUT_ENABLED置false不能当作严格停新证明。原Operation重放、已有映射、消费者独立claim读取及原释放沿冻结状态恢复，不能被停新改成另一输出模式。精确配置和实际制品门禁见DEV-X-06-002。
新异步Task在private_data中固定file_output_namespace和file_outputs；启用及恢复必须核对包含这些字段、原输出登记结构和original-outputs接口的统一目标新版本。历史owned-claims/v1候选镜像认证不覆盖本次新增契约；本期验证目标新版本制品、同一原任务的重启/未知回执恢复与独立引用读取，不要求备份、三库联合恢复、同版本完整恢复部署或旧版适配/兼容fallback，也不转为默认后续待办。新来源默认关闭，文档和开发验证不代替具名启用。
本轮OS-GEMINI-01扩展Gemini原生异步图片，仍不扩展video、临时晋升或大文件验收。Studio的具体接线及领域关联见DEV-STUDIO-07-002，共同要求仍是独立保留、可信解绑和本期引用完整性。
PlatformReleaseMediaOutputFile(ctx, actor, operation, outputIndex, releaseCommand)为可信服务端hook，要求actor对原Operation具有query和file_release权限，不接收任意claim或客户身份。原输出HTTP入口仍为POST /api/platform/v1/products/{product}/media/original/tasks/{id}/output-files/{index}，要求专用产品凭据、原请求证明和当前operation:result授权；没有新增浏览器释放路由。
Platform以原采用命令为claim_command_id，purpose为platform_output，reference_id为原Operation ID，发送完整proof释放自己持有的claim。platform_media_output_file_releases先持久pending意图，远端成功后记released，原输出映射保持可追溯。两种释放状态均阻止原映射再次adopt、manifest续签及Platform读授权；响应或本地提交丢失只重放原release命令，不复活映射，不改变Runtime独立claim、原结果或资金事实。
Runtime可信宿主注入subject/callerScope/product、原Operation与目标对象。prepare冻结原文件描述；adopt先以runtime.adopt.<assetVersionId>为原创建command_id、purpose为runtime_asset_version、reference_id为AssetVersion ID恢复owned claim。已有claim即独立取回，只有明确404才经原Platform授权首次retain；410、403、409、超时或其它失败均不走新建。远端成功但本地尚无claim_ref，也按相同命令找回，不能退回另存原件。renewReference(scope, artifactId)仅按Runtime自己的原claim续签，原Platform anchor可已释放。
Artifact/AssetVersion/Delivery复用原身份。目标schema的reference_releases保存pending/detached/released outbox；不以旧开发库迁移或历史schema checksum兼容作为本期交付条件。requestReferenceRelease(scope, {artifactId, commandId})先锁Artifact并持久冻结意图，阻止新prepare/adopt/deliver、撤销待送达租约；未知本地adoption先恢复原claim，再进入释放。processReferenceRelease(scope, {releaseId, workerId, leaseMs})在事务外取逐项产品证明，持久提交全部detached证明后才按完整owned proof发送原release命令，最后提交released。远端释放或本地提交未知仍从原outbox恢复。
pending、离线或已送达但回执丢失的Delivery均可能有产品关联。可信服务端端口ReferenceReleaseSink.confirmDetached必须读取产品持久tombstone；证明原送达不存在时，也须持久拒绝同一delivery的迟到提交，不能只查一次缺行。输入固定原release/delivery、Artifact/AssetVersion、fileRef/revision/claimRef、scope及target，已知候选回执可作额外核对。
产品证明中的scope使用RuntimeScope，即{subjectId, callerScope, product}；不把文件Owner的snake_case FileScope或浏览器输入替代可信宿主身份。
返回ReferenceDetachReceipt的version为oceanway.reference-detach.v1，包含receiptId、releaseId、deliveryId、artifactId、assetVersionId、fileRef、revision、claimRef、scope、target和state: "detached"。Runtime逐字段校核并白名单持久化；无端口、超时、缺证明、scope或target不符均保持pending与原保护。工作统一按Artifact→Delivery锁序和租约/fence提交；产品tombstone阻止迟到外部送达，Runtime数据库围栏阻止旧worker补写成功。
产品ResultSink/inbox对原delivery、业务目标、文件版本与claim做幂等持久接收；解绑证明经可信服务鉴权，不给其它target/subject复用。产品只解除自己的关联，不获文件物理删除权。Runtime/Platform内部入口不得直接暴露为浏览器任意claim管理API，产品host须独立实现上述持久证明合同。
未纳入首切的目标能力
新结果allocation/register、临时一次promotion、上传会话/分片、prepared binding/confirm、完整command query和物理deletion request由后续交付；未发布的能力不能靠本文表述推为已实现。大文件16/24/20MiB各链、Range/断流、派生、CDN/GC另具名验收。
Gemini与逐模型能力
获准Gemini新输出复用同一file-output.v1、output_refs及original-outputs接口，不新增Gemini专用产品存储协议。producer仅在受信服务端namespace非空且准入通过时选择新lane；原生参考图contents/generationConfig必须原样进入已冻结请求。为恢复未知原件写入，结果先暂存原响应再归档和登记，任务成功时清除PendingResult及NativeResponse，仅保留原输出元数据。原件登记与元数据receipt必须按候选/part顺序绑定原task与连续output index；混合URL/Base64与descriptor、越界数量或身份不符拒绝。现用namespace为空的客户、同步/流式及自带交付行为不由新lane覆盖。
Platform显式冻结output_contract进入私有持久派发envelope、原价格/协议快照和原请求证明；队列及恢复不能丢失声明或改走普通结果路径。只有实际支持该gateway协议、文件桥与来源配置的模型才公布media_generation_profile.output_contracts中的file-output.v1。Drama按正式能力字段核对，不硬编码Gemini型号名单，也不从reference_images存在与否推断文件输出支持。未发布能力时在模型提交前拒绝。
new-api的GET /v1/models/metadata、GET /v1/models/{model}/metadata，以及include_metadata=true形式提供账号可见范围内的meta_data；参数合同以producer docs/api/model_metadata.md和dto/model_metadata.go为源。schema_version必须为2，menu_scope必须为all_eligible_channels；仅variants中verification.status=verified的完整endpoint/parameters/request_path组合可用于可执行表单，unverified_variants仅诊断。未知版本、空菜单或无法转译的路径不由消费者自行猜测补值。该接口不替代Platform资金/权限/模型发布，也不证明独立文件引用已接通；本轮记录正式交接，动态参数表单消费另按实际实现核验。
当前参考输入继续采用inline-base64-sha256-v1，不在本轮改为新的输入文件协议。Drama的platform_media_input.wire、私有任务意图binding.envelope.reference_images及Runtime Job.input.envelope含冻结的参考Base64；它们是受保护的原执行请求快照，不是无字节元数据，不能对外宣称所有持久层零图片字节。输出file/artifact/asset/candidate映射仍只有文件身份；临时签名URL/grant和Owner长期凭据不得写入这些快照、公开任务投影或日志。
Drama输入来源被在途原任务保留；来源业务关系退出后，任务成功/失败明确终结时，按冻结输入的精确文件ID重新核当前权限与最后真实使用，产品事务内写解绑outbox，提交后才释放。UNKNOWN不能提前释放或重做生成。输出候选、读取和最后引用退出仍遵循统一Writer、独立claim与逐delivery可信收件/解绑证明。
本期验证要求
F01-AC2/3/4必须实际覆盖上游释放、短期grant过期、新进程、未知远端提交及原释放重放；F01-AC5覆盖产品提交丢回执与解绑。PG并发时序不能用sleep碰概率，且事务不执行网络I/O。
全链记录同file_ref/version与Put/Copy/Delete账、原Operation/Artifact/保留/Delivery关联、原资金摘要。新原输出链的业务原件成功Put为1、后续引用Put/Copy为0、备份Put为0；条件写探针和失败尝试单列计账。未知写入ACK按原任务和同制品重启确认，原命令恢复不重新收费生成，也不创建恢复副本。源码、夹具、真实TOS和实际制品证据分栏，详见PROC-02-006。