docs(capture): 明确扩展业务归属与原生 Peer 架构

20-product-tdd/capture-contract.md

@@ -0,0 +1,43 @@
+# Capture Extension 合同
+
+`inkcre/capture` 是 first-party extension，拥有材料、来源、采集图、收入身份、回执和恢复语义。各平台 Distribution 为所在 Peer 提供这些能力；语言和仓库不决定业务中心。声明支持采集的分发在本 Peer 内完成采集、编辑、本机保存、构图和共享写入，不依赖另一个分发补齐收入流程。
+
+原生 Mac 分发通过 PostgreSQL 原生协议操作共享 info-base。Host 提供连接、同连接事务与标准 Block／Relation／Storage 基础操作；Capture 编排业务事务。Python 仓库拥有权威 schema／迁移的交付，不因此成为运行时采集执行者。其他 Peer 按自身能力读取或提供采集分发。
+
+## 材料与持久图
+
+材料包含提交 UUID `submission_id`、采集时间 `captured_at`、入口 `selection | paste | screenshot | manual`、可缺失的 `origin`、有序 `materials` 和可缺失的 `annotation`。出处的应用 ID、标题和 URL 允许缺失；显式粘贴不推断来源。材料和附注不能同时为空。单次至多 128 份材料，文字与附注 UTF-8 加原图 bytes 累计不超过 32 MiB。
+
+支持 PNG、JPEG、GIF、WebP，验证 MIME、实际格式与解码尺寸。已有支持编码保留原 bytes；系统仅提供原生位图时，由平台分发生成 PNG 后作为本次原图。原文和自己的补充保持可区分，OCR、模型处理不阻塞收入。
+
+| 对象或关系 | 合同 |
+| --- | --- |
+| 根 Block | `extensions.capture.capture.v1`，JSON 内容包含采集时间、入口、出处 |
+| 根 → 材料 | 从 `material:0` 连续递增，无重复序号 |
+| 文字 | `core.text.v1`，保持原文 |
+| 图片附件 | `extensions.capture.attachment.v1`，JSON 内容包含 MIME、可选文件名 |
+| 图片附件 → 内容 | 唯一 `content` 关系，目标为 `core.image.v1` |
+| 原图 | 标准 PostgreSQL binary storage `-4`，使用标准 `{"blob_id":"…"}` 指针 |
+| 根 → 用户附注 | 至多一条 `annotation` 关系，目标为 `core.text.v1` |
+
+读取分发按关系解释顺序和附注，畸形关系显式报错。Web 来源只允许 HTTP(S) 点击。信息属于共享 info-base，读取不依赖采集设备本地路径或原分发存活。
+
+## 收入、事务与恢复
+
+用户确认后在本机冻结 UUID、材料和目标。Capture 在事务外完成校验和构图，再于同一数据库连接、同一事务内锁定提交身份、检查回执、写图与原图 bytes、写回执。任何写入错误整体回滚。并发请求以 UUID 字符串的 `hashtextextended(value,0)` 取得事务 advisory lock；回执主键再约束唯一性。
+
+共享 `capture_receipts` 保存 `submission_id`、`payload_digest`、`graph_digest`、`root_block_id`、`committed_at`。摘要必填，根 ID 保留历史引用而不级联删除。相同身份和相同摘要重试恢复原结果；摘要冲突保留材料并要求处理。根删除后返回 `deleted`，不得重建图。
+
+材料指纹为规范 JSON 的 SHA-256：键排序、紧凑 UTF-8、缺失可选值为 null、时间 UTC 六位小数、图片数据替换为 bytes SHA-256。文本换行及 Unicode 组合形式不变，材料顺序不变。本机时间冻结为毫秒精度，再规范化为上述时间文本。
+
+实际图指纹使用 Capture v1 的确定性构图投影：`root_local_id`、有序 `blocks`、`relations`、`blobs`；根局部 ID 为 -1，后续 Block 按材料顺序递减分配，图片附件后紧接内容 Block，附注最后。Block 字段为 id/resolver/content，关系为 from_/to_/content，图片附带项为 block_id/data_base64。对这一投影排序键、紧凑 UTF-8 编码后计算 SHA-256；base64 仅参与摘要投影，原生写入 bytes 使用 bytea 参数。
+
+网络超时不证明提交失败。本机先查询同目标回执，核对材料指纹后确认；没有回执时以原身份重试。共享回执确认前保留本机材料。更改当前连接不重定向待办；用户再次采集同内容使用新 UUID，不按内容去重。对用户展示和本机保存的回执时间统一为毫秒精度，数据库保留原时间精度。
+
+## 平台分发与启停
+
+Capture 的本机草稿格式、待办状态机、系统采集策略和界面属于其平台分发。Host 提供应用、窗口／命令挂载、凭据、持久目录和扩展生命周期。停用某个 Peer 的 Capture 不删除材料或改变共享 schema。
+
+Swift 原生分发以 `swift_bundled` 标识，随签名应用携带精确 producer manifest；扩展版本独立于应用版本。未配置数据库时可本机运行。首次加入创建缺失的参与记录，已有选择必须读取且不得覆盖；加入或明确启用成功后，重连不重建已移除的参与，不用缓存启用值覆盖共享意图。用户在线明确启用可以重新创建本 Peer 的缺失参与。离线开关只改变本机运行并说明共享意图未更新；重连读取共享选择，共享写入前复核其精确版本与启用意图。
+
+此 Capture 合同尚未发布，采用一个原生收入协议，不提供旧 HTTP 提交 API、旧回执空摘要或历史本机格式迁移。平台通用数据库协议仍保持原生与 HTTP 的权限对等；未来 HTTP 收入实现须明确自己的事务入口。

20-product-tdd/extension-release-and-installation.md

@@ -12,6 +12,12 @@ Extension 发布者、Registry、开发工具和宿主共同消费本契约。Re
 
 prepare、upload、publish 一次针对一个 Native Release。只有它自己的全部原生对象齐备时才可公开，检查与提交之间改变产物身份或关联必须重新验证。发布 Python 不等待 MF，发布 MF 不等待 Python。已发布的坐标及产物身份不可覆盖；相同请求可幂等重试，冲突需要新版本。文档不使缺少可执行产物的分发成为可安装版本。
 
+## 随签名应用交付的原生分发
+
+`swift_bundled` 表示宿主签名应用携带的原生分发。producer manifest 定义 Extension Name、分发格式和精确版本，由模块资源与签名应用一起交付。宿主只运行实际携带的模块，不下载动态代码、不替换精确选择；需要其他版本时明确要求更新应用。其产物供应链是签名应用，不把不存在的 Registry 发布或原生热加载能力作为已完成事实。
+
+此分发仍有真实启停生命周期和 Peer 参与记录；应用关闭只停止实际运行，不撤回共享启用意图。未配置数据库时可离线使用扩展。首次加入与重连须区分：首次事务内创建缺失的参与，冲突则读已有值；加入或明确启用成功后，重连不重建已移除记录、不重放离线开关。用户在线明确启用可以重新创建本 Peer 的缺失参与；离线操作只改变本机运行并显示共享意图尚未更新。共享写入前复核参与选择和启用意图。Python／MF 原生产物继续按各自 Registry 发布流程交付。
+
 ## 部署共享状态与 Peer 参与
 
 部署中一个插件只有一个逻辑身份及其共享配置、业务状态。安装选择属于 `Peer × Extension`：该 Peer 选择一种宿主支持的 Distribution 及精确版本，并保存自己的启用意图。数据库保存这些持久事实；运行端报告实际加载的分发、版本和运行结果。

20-product-tdd/unit-topology.md

@@ -11,7 +11,7 @@ Define cross-unit technical boundaries and ownership so changes do not leak resp
 
 ## Database Peer Topology
 
-- `impl-py`, `impl-ts`, and future units are peer nodes; frontend/backend hierarchy is not
+- `impl-py`, `impl-ts`, `impl-swift`, and future units are peer nodes; frontend/backend hierarchy is not
   part of the durable topology.
 - Native PostgreSQL and PostgREST are transports over one admitted database protocol, not
   separate semantic authorities.
@@ -22,6 +22,8 @@ Define cross-unit technical boundaries and ownership so changes do not leak resp
 - Peer equality does not imply identical execution ability. A business facade may execute
   locally on a capable Peer or delegate one exact synchronous capability to another live
   Peer without turning the deployment into a fixed frontend/backend hierarchy.
+- `inkcre/capture` 是 first-party extension，拥有跨平台的材料、采集图与收入语义。Mac 原生分发在本 Peer 内完成采集、持久待办、构图与共享写入；Host/Core 提供通用运行和数据库能力。
+- Mac 使用 PostgreSQL 原生协议，Web 按浏览器运行能力使用 PostgREST；传输选择不划分 Peer 业务权威。仓库维护位置不构成运行时流水线。具体语义见[Capture Extension 合同](capture-contract.md)。
 - Shared actors，assets，trust boundaries and proportional security classification use the
   [Security Boundary Model](security-boundary-model.md)。Each Unit still owns its executable
   admission，rendering，runtime and deployment mechanics。

docs/index.md

@@ -9,6 +9,7 @@
 - [Cross-unit contracts](../20-product-tdd/cross-unit-contracts.md)
 - [跨 Peer 可观测性契约](../20-product-tdd/observability-contract.md)
 - [Twitter 归档信息与接入契约](../20-product-tdd/twitter-archive-contract.md)
+- [主动采集持久化契约](../20-product-tdd/capture-contract.md)
 - [Knowledge capability contract](../20-product-tdd/knowledge-capability-contract.md)
 - [Semantic retrieval and Peer capabilities](../20-product-tdd/semantic-retrieval-and-peer-capabilities.md)
 - [Feature retrieval and media interpretation](../20-product-tdd/feature-retrieval-and-media-interpretation.md)