From 6c2cb9d0307479c8e44b6af310d5b97b7681547d Mon Sep 17 00:00:00 2001 From: Lan_zhijiang Date: Wed, 21 Oct 2026 17:35:05 +0800 Subject: [PATCH 1/3] =?UTF-8?q?docs(topology):=20=E7=BA=B3=E5=85=A5=20macO?= =?UTF-8?q?S=20=E9=87=87=E9=9B=86=20Peer?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 定义 Mac 系统采集与持久待办的能力边界 - 明确通过共享公告调用采集能力，收入后由其他 Peer 独立读取 --- 20-product-tdd/unit-topology.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/20-product-tdd/unit-topology.md b/20-product-tdd/unit-topology.md index 2f17fae..6437e96 100644 --- a/20-product-tdd/unit-topology.md +++ b/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. +- `impl-swift` 的首个 macOS 分发提供系统采集和持久待办。它通过共享 Peer 公告调用精确采集能力， + 不承载通用扩展宿主；已收入的材料属于共享 info-base，其他具备解释能力的 Peer 可以独立读取。 - 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。 From fee3347f1488adae9ae6e141bc15fe1375958a14 Mon Sep 17 00:00:00 2001 From: Lan_zhijiang Date: Wed, 21 Oct 2026 20:29:41 +0800 Subject: [PATCH 2/3] =?UTF-8?q?fix(capture):=20=E6=98=8E=E7=A1=AE=20Mac=20?= =?UTF-8?q?=E7=9B=B4=E6=8E=A5=E5=86=99=E5=85=A5=E5=85=B1=E4=BA=AB=E6=95=B0?= =?UTF-8?q?=E6=8D=AE=E5=BA=93?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 将采集构图与校验归还 Mac Peer，读取分发可选。 - 定义图、原始字节和幂等回执的原子提交合同。 --- 20-product-tdd/capture-contract.md | 58 ++++++++++++++++++++++++++++++ 20-product-tdd/unit-topology.md | 5 +-- docs/index.md | 1 + 3 files changed, 62 insertions(+), 2 deletions(-) create mode 100644 20-product-tdd/capture-contract.md diff --git a/20-product-tdd/capture-contract.md b/20-product-tdd/capture-contract.md new file mode 100644 index 0000000..dec229c --- /dev/null +++ b/20-product-tdd/capture-contract.md @@ -0,0 +1,58 @@ +# 主动采集持久化契约 + +原生 Mac Peer 自己校验采集材料、构造共享图并写入 info-base。它通过既有认证数据库协议访问 PostgreSQL／PostgREST，无需 Python Peer、执行者公告或通用扩展宿主。Python 仓库拥有数据库 schema 和迁移，这不构成运行时写入依赖。 + +本契约拥有跨 Peer 的 Capture 图、提交身份与原子持久化语义。`impl-swift` 拥有本机采集、待办和构图实现；`impl-py` 拥有数据库事务函数及可选 Python 读取分发；`impl-ts` 拥有可选 Web 读取分发。读取分发的存在、启用与否不影响写入。收入后的信息属于共享 info-base，不依赖原采集者或任何特定执行 Peer 存活。 + +## 冻结材料与图 + +本机冻结载荷包含 UUID `submission_id`、带时区的 `captured_at`、入口 `selection | paste | screenshot | manual`、可缺失的 `origin`、有序 `materials` 和可缺失的 `annotation`。出处的 `application_id`、`title`、`url` 都允许缺失；显式粘贴不能推断原始来源。文本材料使用 `kind: text` 和 `text`，图片使用 `kind: image`、`mime_type`、`data_base64` 和可缺失的 `filename`。材料与附注不能同时为空。采集 Peer 将该载荷转换为下述图命令，数据库不接收载荷后代为构图。 + +单次最多 128 份材料，文本和附注的 UTF-8 字节数加解码图片累计不得超过 32 MiB，HTTP JSON 请求不得超过 48 MiB。支持 PNG、JPEG、GIF、WebP；采集 Peer 验证实际图片格式与声明的 MIME，并拒绝文件损坏或解码尺寸过大的图片。原始字节不经过缩放或重新编码。代理也必须允许相同请求体上限；这两个上限是协议边界，不是所有设备与代理都已完成性能校准的承诺。 + +调用方先冻结提交 UUID、材料和目标信息库，再发送。网络超时不证明提交失败。恢复先查询同一信息库的 `capture_receipts`，核对指纹，再确认本机结果；没有回执时只可使用原 UUID 和原材料重试。切换当前连接不能重定向已有待办。再次主动采集相同内容使用新 UUID，不进行内容去重。 + +指纹为规范 JSON 的 SHA-256：对象键排序、紧凑分隔符、UTF-8、缺失的可选字段显式为 `null`，时间转 UTC 并保留六位小数，图片的 `data_base64` 替换为原始字节的 `data_sha256`。UUID 使用标准小写形式；数组顺序、文本换行及 Unicode 组合形式保持原样。Swift 对冻结载荷的网络时间表示再规范化，避免本机亚毫秒时间参与指纹却未被发送。 + +相同 UUID、相同材料与图返回原回执；相同 UUID、不同材料摘要或不同实际图返回 409，客户端保留材料并要求处理。成功结果包含 `submission_id`、`root_block_id`、`committed_at` 和 `availability: available | deleted`。根 Block 删除后回执仍保留，重试返回 `deleted`，不能复活内容。 + +## 持久图 + +| 对象或关系 | 合同 | +| --- | --- | +| 根 Block | `extensions.capture.capture.v1`，内容为时间、入口、出处的 JSON | +| 根 → 材料 | `material:0` 起连续递增的关系，序号不可重复 | +| 文本材料 | 标准 `core.text.v1`，原文保持不变 | +| 图片材料 | `extensions.capture.attachment.v1`，内容为 MIME 与可选文件名 | +| 图片材料 → 原始内容 | 唯一 `content` 关系，目标为 `core.image.v1` | +| 原始图片 | 标准 PostgreSQL binary storage（`storage = -4`）保存原始字节 | +| 根 → 用户附注 | 至多一条 `annotation` 关系，目标为 `core.text.v1` | + +Resolver 按关系解释材料顺序，不把附注混入原文；缺失或畸形关系显式报错。Web 来源链接仅允许 HTTP(S) 点击，其他来源位置仍可作为文本查看。图片通过标准 storage/resolver 读取，不依赖 Mac 本地文件、Python 内存或派生 OCR。OCR、通用文件、整页抓取和知识查询不属于此版采集范围。 + +## 数据库原子提交 + +认证 Peer 调用 `inkcre.commit_capture(submission_id uuid, payload_digest text, graph jsonb)`，PostgREST 对应 `POST /rpc/commit_capture`。JSON 请求键与参数同名；函数返回一个成功结果对象。它使用既有部署 Peer JWT／数据库角色，没有匿名入口，不派发 Job，不查找其他 Peer。 + +`graph` 是采集 Peer 已构造的图，不是待处理的材料请求。其字段为： + +| 字段 | 结构与约束 | +| --- | --- | +| `root_local_id` | 根 Block 的负数局部 ID | +| `blocks` | 1–258 项，每项为 `id`、`resolver`、`content`；ID 为互不重复的负整数，content 为字符串 | +| `relations` | 至多 257 项，每项为 `from_`、`to_`、`content`，两端只引用本命令的局部 Block | +| `blobs` | 至多 128 项，每项为 `block_id`、`data_base64`；只关联本命令中不同的 Block | + +函数分配共享 Block ID，将附带 bytes 写入标准 PostgreSQL binary storage，为对应 Block 填入标准 `{"blob_id":"…"}` 指针，并按局部 ID 映射写入关系。它只校验提交结构、引用和限额，不决定 resolver、材料顺序、来源或附注语义，不解码图片或执行采集业务。图 JSON 的 UTF-8 表示至多 48 MiB，解码后 bytes 累计至多 32 MiB；采集 Peer 仍负责前述材料总量和图片格式校验。 + +图、bytes 和 `capture_receipts` 必须在同一个事务中提交。任何引用、编码或持久化错误都回滚整个命令。UUID 的事务 advisory lock 串行化并发重试，回执主键提供唯一性约束；通用图写入原有的新建语义不变。 + +回执保留 `payload_digest`，用于核对已有本机冻结材料，并由数据库从收到的 `graph` JSONB 计算 `graph_digest`（JSONB 文本的 UTF-8 SHA-256），将提交身份绑定实际图与 bytes。新调用不能沿用同一材料摘要而替换图。函数只为新提交写回执；回执中的根 ID 没有删除级联外键，因此根被删除后重试返回 `deleted`，不会重建图。 + +早期开发合同的回执没有 `graph_digest`，迁移保留其 NULL 值并沿用材料摘要恢复，既有待办的 UUID、目标和材料摘要不迁移。新协议写出的回执总有图摘要；不能通过删除旧回执或重新分配待办身份来升级。 + +## 验收边界 + +决定写入是否独立的关键观察是在 Python Peer 停止、其他执行者不可用时，Mac 仍能通过 PostgreSQL／PostgREST 写入包含文字、原图与附注的图。成功提交后丢失响应、重开本机待办并重试只产生一份图；原始 bytes 读回一致。另需覆盖同 UUID 的实际图冲突、事务回滚、根删除后的重放，以及停止 Mac 后其他已具备读取能力的 Peer 冷读共享图。 + +这些数据库与跨 Peer 观察不替代 macOS 系统权限、真实选区、输入法、物理快捷键和多屏像素的原生验收。 diff --git a/20-product-tdd/unit-topology.md b/20-product-tdd/unit-topology.md index 6437e96..ea2272d 100644 --- a/20-product-tdd/unit-topology.md +++ b/20-product-tdd/unit-topology.md @@ -22,8 +22,9 @@ 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. -- `impl-swift` 的首个 macOS 分发提供系统采集和持久待办。它通过共享 Peer 公告调用精确采集能力， - 不承载通用扩展宿主；已收入的材料属于共享 info-base，其他具备解释能力的 Peer 可以独立读取。 +- `impl-swift` 的首个 macOS 分发提供系统采集和持久待办。它自行构图，通过共享数据库协议原子写入， + 不依赖 Python Peer 或通用扩展宿主；已收入的材料属于共享 info-base，其他具备解释能力的 Peer 可以独立读取。具体跨 Peer + 语义见[主动采集持久化契约](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。 diff --git a/docs/index.md b/docs/index.md index 3a4733f..6f500c4 100644 --- a/docs/index.md +++ b/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) From 569d8918ef3cd25c6e511ba993a4d680272a5a4f Mon Sep 17 00:00:00 2001 From: Lan_zhijiang Date: Wed, 21 Oct 2026 22:55:33 +0800 Subject: [PATCH 3/3] =?UTF-8?q?docs(capture):=20=E6=98=8E=E7=A1=AE?= =?UTF-8?q?=E5=8E=9F=E7=94=9F=E5=88=86=E5=8F=91=E4=B8=8E=20Host=20?= =?UTF-8?q?=E7=9A=84=E8=81=8C=E8=B4=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 将 Capture 业务事务归属扩展，Mac 原生直连共享 PostgreSQL - 定义随签名应用交付的精确分发及启停参与语义 --- 20-product-tdd/capture-contract.md | 61 +++++++------------ .../extension-release-and-installation.md | 6 ++ 20-product-tdd/unit-topology.md | 5 +- 3 files changed, 31 insertions(+), 41 deletions(-) diff --git a/20-product-tdd/capture-contract.md b/20-product-tdd/capture-contract.md index dec229c..9a410fb 100644 --- a/20-product-tdd/capture-contract.md +++ b/20-product-tdd/capture-contract.md @@ -1,58 +1,43 @@ -# 主动采集持久化契约 +# Capture Extension 合同 -原生 Mac Peer 自己校验采集材料、构造共享图并写入 info-base。它通过既有认证数据库协议访问 PostgreSQL／PostgREST，无需 Python Peer、执行者公告或通用扩展宿主。Python 仓库拥有数据库 schema 和迁移，这不构成运行时写入依赖。 +`inkcre/capture` 是 first-party extension，拥有材料、来源、采集图、收入身份、回执和恢复语义。各平台 Distribution 为所在 Peer 提供这些能力；语言和仓库不决定业务中心。声明支持采集的分发在本 Peer 内完成采集、编辑、本机保存、构图和共享写入，不依赖另一个分发补齐收入流程。 -本契约拥有跨 Peer 的 Capture 图、提交身份与原子持久化语义。`impl-swift` 拥有本机采集、待办和构图实现；`impl-py` 拥有数据库事务函数及可选 Python 读取分发；`impl-ts` 拥有可选 Web 读取分发。读取分发的存在、启用与否不影响写入。收入后的信息属于共享 info-base，不依赖原采集者或任何特定执行 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`。出处的 `application_id`、`title`、`url` 都允许缺失；显式粘贴不能推断原始来源。文本材料使用 `kind: text` 和 `text`，图片使用 `kind: image`、`mime_type`、`data_base64` 和可缺失的 `filename`。材料与附注不能同时为空。采集 Peer 将该载荷转换为下述图命令，数据库不接收载荷后代为构图。 +材料包含提交 UUID `submission_id`、采集时间 `captured_at`、入口 `selection | paste | screenshot | manual`、可缺失的 `origin`、有序 `materials` 和可缺失的 `annotation`。出处的应用 ID、标题和 URL 允许缺失；显式粘贴不推断来源。材料和附注不能同时为空。单次至多 128 份材料，文字与附注 UTF-8 加原图 bytes 累计不超过 32 MiB。 -单次最多 128 份材料，文本和附注的 UTF-8 字节数加解码图片累计不得超过 32 MiB，HTTP JSON 请求不得超过 48 MiB。支持 PNG、JPEG、GIF、WebP；采集 Peer 验证实际图片格式与声明的 MIME，并拒绝文件损坏或解码尺寸过大的图片。原始字节不经过缩放或重新编码。代理也必须允许相同请求体上限；这两个上限是协议边界，不是所有设备与代理都已完成性能校准的承诺。 - -调用方先冻结提交 UUID、材料和目标信息库，再发送。网络超时不证明提交失败。恢复先查询同一信息库的 `capture_receipts`，核对指纹，再确认本机结果；没有回执时只可使用原 UUID 和原材料重试。切换当前连接不能重定向已有待办。再次主动采集相同内容使用新 UUID，不进行内容去重。 - -指纹为规范 JSON 的 SHA-256：对象键排序、紧凑分隔符、UTF-8、缺失的可选字段显式为 `null`，时间转 UTC 并保留六位小数，图片的 `data_base64` 替换为原始字节的 `data_sha256`。UUID 使用标准小写形式；数组顺序、文本换行及 Unicode 组合形式保持原样。Swift 对冻结载荷的网络时间表示再规范化，避免本机亚毫秒时间参与指纹却未被发送。 - -相同 UUID、相同材料与图返回原回执；相同 UUID、不同材料摘要或不同实际图返回 409，客户端保留材料并要求处理。成功结果包含 `submission_id`、`root_block_id`、`committed_at` 和 `availability: available | deleted`。根 Block 删除后回执仍保留，重试返回 `deleted`，不能复活内容。 - -## 持久图 +支持 PNG、JPEG、GIF、WebP，验证 MIME、实际格式与解码尺寸。已有支持编码保留原 bytes；系统仅提供原生位图时，由平台分发生成 PNG 后作为本次原图。原文和自己的补充保持可区分，OCR、模型处理不阻塞收入。 | 对象或关系 | 合同 | | --- | --- | -| 根 Block | `extensions.capture.capture.v1`，内容为时间、入口、出处的 JSON | -| 根 → 材料 | `material:0` 起连续递增的关系，序号不可重复 | -| 文本材料 | 标准 `core.text.v1`，原文保持不变 | -| 图片材料 | `extensions.capture.attachment.v1`，内容为 MIME 与可选文件名 | -| 图片材料 → 原始内容 | 唯一 `content` 关系，目标为 `core.image.v1` | -| 原始图片 | 标准 PostgreSQL binary storage（`storage = -4`）保存原始字节 | +| 根 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` | -Resolver 按关系解释材料顺序，不把附注混入原文；缺失或畸形关系显式报错。Web 来源链接仅允许 HTTP(S) 点击，其他来源位置仍可作为文本查看。图片通过标准 storage/resolver 读取，不依赖 Mac 本地文件、Python 内存或派生 OCR。OCR、通用文件、整页抓取和知识查询不属于此版采集范围。 - -## 数据库原子提交 +读取分发按关系解释顺序和附注，畸形关系显式报错。Web 来源只允许 HTTP(S) 点击。信息属于共享 info-base，读取不依赖采集设备本地路径或原分发存活。 -认证 Peer 调用 `inkcre.commit_capture(submission_id uuid, payload_digest text, graph jsonb)`，PostgREST 对应 `POST /rpc/commit_capture`。JSON 请求键与参数同名；函数返回一个成功结果对象。它使用既有部署 Peer JWT／数据库角色，没有匿名入口，不派发 Job，不查找其他 Peer。 +## 收入、事务与恢复 -`graph` 是采集 Peer 已构造的图，不是待处理的材料请求。其字段为： +用户确认后在本机冻结 UUID、材料和目标。Capture 在事务外完成校验和构图，再于同一数据库连接、同一事务内锁定提交身份、检查回执、写图与原图 bytes、写回执。任何写入错误整体回滚。并发请求以 UUID 字符串的 `hashtextextended(value,0)` 取得事务 advisory lock；回执主键再约束唯一性。 -| 字段 | 结构与约束 | -| --- | --- | -| `root_local_id` | 根 Block 的负数局部 ID | -| `blocks` | 1–258 项，每项为 `id`、`resolver`、`content`；ID 为互不重复的负整数，content 为字符串 | -| `relations` | 至多 257 项，每项为 `from_`、`to_`、`content`，两端只引用本命令的局部 Block | -| `blobs` | 至多 128 项，每项为 `block_id`、`data_base64`；只关联本命令中不同的 Block | +共享 `capture_receipts` 保存 `submission_id`、`payload_digest`、`graph_digest`、`root_block_id`、`committed_at`。摘要必填，根 ID 保留历史引用而不级联删除。相同身份和相同摘要重试恢复原结果；摘要冲突保留材料并要求处理。根删除后返回 `deleted`，不得重建图。 -函数分配共享 Block ID，将附带 bytes 写入标准 PostgreSQL binary storage，为对应 Block 填入标准 `{"blob_id":"…"}` 指针，并按局部 ID 映射写入关系。它只校验提交结构、引用和限额，不决定 resolver、材料顺序、来源或附注语义，不解码图片或执行采集业务。图 JSON 的 UTF-8 表示至多 48 MiB，解码后 bytes 累计至多 32 MiB；采集 Peer 仍负责前述材料总量和图片格式校验。 +材料指纹为规范 JSON 的 SHA-256：键排序、紧凑 UTF-8、缺失可选值为 null、时间 UTC 六位小数、图片数据替换为 bytes SHA-256。文本换行及 Unicode 组合形式不变，材料顺序不变。本机时间冻结为毫秒精度，再规范化为上述时间文本。 -图、bytes 和 `capture_receipts` 必须在同一个事务中提交。任何引用、编码或持久化错误都回滚整个命令。UUID 的事务 advisory lock 串行化并发重试，回执主键提供唯一性约束；通用图写入原有的新建语义不变。 +实际图指纹使用 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 参数。 -回执保留 `payload_digest`，用于核对已有本机冻结材料，并由数据库从收到的 `graph` JSONB 计算 `graph_digest`（JSONB 文本的 UTF-8 SHA-256），将提交身份绑定实际图与 bytes。新调用不能沿用同一材料摘要而替换图。函数只为新提交写回执；回执中的根 ID 没有删除级联外键，因此根被删除后重试返回 `deleted`，不会重建图。 +网络超时不证明提交失败。本机先查询同目标回执，核对材料指纹后确认；没有回执时以原身份重试。共享回执确认前保留本机材料。更改当前连接不重定向待办；用户再次采集同内容使用新 UUID，不按内容去重。对用户展示和本机保存的回执时间统一为毫秒精度，数据库保留原时间精度。 -早期开发合同的回执没有 `graph_digest`，迁移保留其 NULL 值并沿用材料摘要恢复，既有待办的 UUID、目标和材料摘要不迁移。新协议写出的回执总有图摘要；不能通过删除旧回执或重新分配待办身份来升级。 +## 平台分发与启停 -## 验收边界 +Capture 的本机草稿格式、待办状态机、系统采集策略和界面属于其平台分发。Host 提供应用、窗口／命令挂载、凭据、持久目录和扩展生命周期。停用某个 Peer 的 Capture 不删除材料或改变共享 schema。 -决定写入是否独立的关键观察是在 Python Peer 停止、其他执行者不可用时，Mac 仍能通过 PostgreSQL／PostgREST 写入包含文字、原图与附注的图。成功提交后丢失响应、重开本机待办并重试只产生一份图；原始 bytes 读回一致。另需覆盖同 UUID 的实际图冲突、事务回滚、根删除后的重放，以及停止 Mac 后其他已具备读取能力的 Peer 冷读共享图。 +Swift 原生分发以 `swift_bundled` 标识，随签名应用携带精确 producer manifest；扩展版本独立于应用版本。未配置数据库时可本机运行。首次加入创建缺失的参与记录，已有选择必须读取且不得覆盖；加入或明确启用成功后，重连不重建已移除的参与，不用缓存启用值覆盖共享意图。用户在线明确启用可以重新创建本 Peer 的缺失参与。离线开关只改变本机运行并说明共享意图未更新；重连读取共享选择，共享写入前复核其精确版本与启用意图。 -这些数据库与跨 Peer 观察不替代 macOS 系统权限、真实选区、输入法、物理快捷键和多屏像素的原生验收。 +此 Capture 合同尚未发布，采用一个原生收入协议，不提供旧 HTTP 提交 API、旧回执空摘要或历史本机格式迁移。平台通用数据库协议仍保持原生与 HTTP 的权限对等；未来 HTTP 收入实现须明确自己的事务入口。 diff --git a/20-product-tdd/extension-release-and-installation.md b/20-product-tdd/extension-release-and-installation.md index 6f535bc..49fb045 100644 --- a/20-product-tdd/extension-release-and-installation.md +++ b/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 及精确版本，并保存自己的启用意图。数据库保存这些持久事实；运行端报告实际加载的分发、版本和运行结果。 diff --git a/20-product-tdd/unit-topology.md b/20-product-tdd/unit-topology.md index ea2272d..82a2460 100644 --- a/20-product-tdd/unit-topology.md +++ b/20-product-tdd/unit-topology.md @@ -22,9 +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. -- `impl-swift` 的首个 macOS 分发提供系统采集和持久待办。它自行构图，通过共享数据库协议原子写入， - 不依赖 Python Peer 或通用扩展宿主；已收入的材料属于共享 info-base，其他具备解释能力的 Peer 可以独立读取。具体跨 Peer - 语义见[主动采集持久化契约](capture-contract.md)。 +- `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。