API 参考

公开消费使用 S3/CDN binding，管理操作使用 /v1/graphql 和 scoped PAT。 Dashboard 工作区使用服务端 session，worker 使用独立内部接口。

• 认证
• 完整 GraphQL operations
• 错误与恢复
• 静态分发 schema
• GraphQL SDL
• Marketplace manifest schema
• Manifest projection schema
• Source-release schema

公开读取

GET revision/stable_latest
GET revision/<revision_id>

Pointer 内容恰为64个小写hex字符，没有JSON或换行；revision是snapshot原始JSON字节的 SHA-256。Snapshot引用catalog、package lookup及其immutable文档，descriptor提供path/hash/size。 客户端校验authority、channel、schema和摘要，一次操作固定一个snapshot，不回退GraphQL。

revision/preview_latest包含所有批准stable/prerelease；stable不含prerelease。 Pointer最多缓存五分钟，并计入HTTP Age；immutable对象可长期缓存。显式历史revision不代表当前政策。 包名为准确canonical namespace/name，不转换大小写或下划线。公开UUID不授予管理权限。

发布与可见性

Plugin 是身份、所有权与生命周期；listing 是关联的市场展示。草稿和pending数据不进入公开snapshot。 隐藏的正式包从discovery移除，准确lookup保留且listing为null，历史公开文档仍可读。 创建草稿后通过 submit_release 一次提交初次 listing 快照及版本，管理员一次审核。 最终鉴权并durable提交publication commitment后才写公开bucket。所需channel与HTML确认后才为published。 临时材料保留7天；公开制品包含相对公开path、摘要、大小和manifest，不含private object key或grant。

发布查询与恢复

publication_status按原actor/command查询，检查当前owner/admin和plugins:read；只有管理员可查其他actor。 结果区分每个channel的revision、covering revision和web状态。recover_publication要求当前管理员、 admin:write和expected_revision，保留原commitment/source identity，重新排队有界核对。 恢复请求自身applied只证明已排队，原publication全部channel/web完成才证明公开完成。