feat(artifacts): share merge and restoration across families

docs/en/docs/operate/atomic-memory-migration.md

@@ -59,7 +59,9 @@ Validation requires versions continuous from 1, consistent predecessor IDs, cont
 manifest references. The current manifest pointer, or the last pointer before compaction, must identify
 that entry's chain tail. Unexplained absence, missing changes, duplicate identities, skipped versions and
 lagging heads block conversion. Legacy active, inactive and compacted entries become active, forgotten and
-retired respectively. Family state versions and common head governance summaries agree.
+retired respectively. Lifecycle is authoritative in `pc_artifact_heads`: these states use `lifecycle_state`
+values `active`, `deprecated` and `retired`, respectively, and newly imported heads have no `merged_into_id`.
+Atomic Memory reads the head's `governance_generation` as its `state_version`.
 
 A formal Owner on an exact legacy entry resource becomes the new memory's Owner. Without enforced access,
 an entry without an Owner migrates without one. Several Owners on one entry or an invalid Owner block
@@ -177,9 +179,9 @@ Cursors, CAS generations, high-water marks, pending/flush requests, accepted tas
 unchanged. Family `memory` and binding `memory-source-window` remain scheduling aliases. Old leases are
 invalidated and their fences advance before maintenance completes. Consumed Sources are not extracted again.
 
-Each entry's history, head, state, Owner, tags, grant conversion and current projection commit together.
+Each entry's history, head, Owner, tags, grant conversion and current projection commit together.
 Embedding preparation occurs outside the transaction. Repeat apply with the same configuration after an
-interruption. Existing targets must match the exact imported history; differing data or orphan content/state
+interruption. Existing targets must match the exact imported history; differing data or orphan content
 is rejected without overwriting authority. Subsequent revisions or lifecycle changes never cause the task
 to reset a target's head, state or tags.
 
@@ -207,7 +209,7 @@ powercontext server atomic-memory-rebuild-projection --env-file .env --maintenan
 ```
 
 This command checks that legacy objects, columns and foreign keys have been removed from public storage and
-that Atomic heads, content and states are valid. It rebuilds only active current rows and removes nonactive
+that Atomic heads, content revisions and head lifecycle data are valid. It rebuilds only active current rows and removes nonactive
 or orphan current rows. Heads, content revisions, lifecycle states, retained history and Source/processing
 progress keep their exact identities and values. Rebuilding reads neither the archive nor legacy entry tables.
 The offline migration `verify` command checks whether legacy history was imported completely; projection
@@ -254,4 +256,4 @@ A current table created during development of this branch (with copied read gran
 to no release and is rejected at initialization. Before migration completes, apply drops and recreates that
 derived table and its report asks for a projection rebuild; after migration, stop writers and run the
 projection rebuild command above. Either way only that derived table is rebuilt from retained authority;
-Artifact history, Family state and grant records are unchanged.
+Artifact history, head lifecycle data and grant records are unchanged.

docs/en/docs/workflows/atomic-memory.md

@@ -136,10 +136,14 @@ Restore directly through `POST /v1/atomic-memory/restorations`:
 {"scope_id": "S", "target": {"artifact_id": "B"}}
 ```
 
-Restoring forgotten content makes it active. Restoring an already active memory without a revision returns unchanged.
+Restoring forgotten content makes it active. Restoring an already active memory without a selected revision returns
+`changed: false` and appends no revision.
 Restoring a merged input undoes the later merges that froze it. For A+B→C followed by C+D→E, restoring B makes
 A, B and D active and retires C and E. Ordinary downstream Artifacts and Source cursors are not rolled back.
-Supplying `target.revision` saves that historical content as a new revision of the target.
+Every memory actually restored or retired appends a revision under its existing Artifact identity, numbered as its current
+revision plus one. Restored inputs use their frozen content; supplying `target.revision` uses that historical content for the
+target's new revision. Existing revisions and the original merge relationships remain intact, and exact historical reads
+continue to return the original content. Current reads and search follow the restored revisions.
 
 Inspect the impact first through `POST /v1/atomic-memory/restoration-previews`:
 
@@ -161,9 +165,20 @@ After inspecting it, send the original token to restorations with the same princ
 ```
 
 Success returns `changed`, exact resulting `restored` references, `retired` and `undo_merge_results`.
+When `changed: true`, both `restored` and `retired` reference the newly appended revisions of the objects actually changed.
+A no-op returns `changed: false` and retains the current primary Artifact reference in `restored`, without appending a revision.
 To undo the merge that created C, use `operation: "undo_merge"` and `target: {"artifact_id": "C"}`.
 That operation cannot also select a content revision.
 
+The public Python runtime can read the exact historical group result using the operation's primary new revision:
+
+```python
+outcome = await runtime.artifact_merge.for_scope("S", "atomic-memory").restoration_outcome("B", revision=2)
+```
+
+Replace `2` with the primary revision produced by that operation. The method returns `None` if that revision has no stored
+restoration outcome and requires read permission for every affected Artifact.
+
 | Error | HTTP status | Action |
 | --- | --- | --- |
 | `invalid_preview` | 422 | Check the token, principal, Scope, operation, target and shared signing configuration |
@@ -173,7 +188,7 @@ That operation cannot also select a content revision.
 | `atomic_memory_changed` | 409 | Read the changed content/state before deciding to retry |
 | `invalid_memory_relation` | 409 | Investigate inconsistent stored relationships |
 
-Restore and merge have no `idempotency_key` or durable receipt for replaying an earlier response. A direct restoration
+Restore and merge have no `idempotency_key` and do not automatically replay an earlier response. A direct restoration
 interprets the relationships current on each invocation; repeating it after another merge can undo that newer merge.
 Replaying a successful request with a token can return `preview_stale`. If the connection fails during commit, inspect
 current states before deciding to preview again. The Python SDK does not blindly retry writes with an unknown outcome.

docs/zh/docs/operate/atomic-memory-migration.md

@@ -53,7 +53,9 @@ revision 不会产生该条记忆的新 revision。
 当前 manifest 或 compact 前最后一次出现的指针必须指向本 entry 的版本链末端。
 缺失变化记录、无法解释的缺席、重复身份、跳过版本或落后的 head 都会阻断；迁移不会选取最大版本
 来掩盖不一致。旧 active、inactive、compact 分别成为 active、forgotten、retired。
-状态版本计数与公共 head 的治理摘要同步。
+生命周期以 `pc_artifact_heads` 为权威：这三种状态分别使用 `lifecycle_state` 值 `active`、`deprecated`、
+`retired`，新导入的 head 不设置 `merged_into_id`。Atomic Memory 的 `state_version` 读取 head 的
+`governance_generation`。
 
 旧 entry 的精确资源身份上有正式 Owner 时，它迁为新记忆的 Owner；未启用鉴权的部署中没有 Owner 的
 entry 迁移后同样没有 Owner。同一 entry 有多个 Owner 或 Owner 不合法时会阻断，集合 Owner 不会分配给
@@ -156,9 +158,9 @@ Source Cursor、CAS generation、高水位、pending/flush 请求、已接受任
 `memory` Family 与 `memory-source-window` binding 继续作为调度兼容身份。
 迁移完成前失效旧 Lease 并推进 fence，已消费的 Source 不重新抽取。
 
-每条记忆的历史、head、状态、Owner、标签、授权转换与当前投影在同一个事务提交。
+每条记忆的历史、head、Owner、标签、授权转换与当前投影在同一个事务提交。
 向量准备在事务外完成。中途退出后，可以使用相同配置重复 apply；已提交对象先核验精确导入历史。
-与确定性身份对应的内容不同、存在孤立状态或历史时明确报错，不覆盖目标数据。
+与确定性身份对应的内容不同或存在孤立正文历史时明确报错，不覆盖目标数据。
 已经导入的对象后续产生新 revision 或生命周期变化时，迁移不回退其 head、状态或标签。
 
 如果已转换的授权仍保留旧资源摘要，plan 和 verify 会返回 `ready: false`，并在
@@ -179,7 +181,7 @@ API、宿主、Worker、自动重启和输入写入，然后使用目标部署
 powercontext server atomic-memory-rebuild-projection --env-file .env --maintenance-confirmed
 ```
 
-命令检查公共表中的旧对象、旧列和外键已清理，且 Atomic 的 head、正文和状态有效。它只重建 active 的
+命令检查公共表中的旧对象、旧列和外键已清理，且 Atomic 的 head、正文 revision 和 head 生命周期数据有效。它只重建 active 的
 current 行，清除非 active 或孤立的 current 行；head、正文 revision、生命周期状态、保留历史及
 Source/处理进度保持原身份和原值。重建不读取归档或旧 entry 表；旧历史是否已完整导入，由停服迁移的
 `verify` 负责核验，投影重建不能补做缺失的历史导入。
@@ -219,4 +221,4 @@ plan、apply 和 verify 读取保留的全部旧历史和 Source/任务快照，
 本分支开发过程中创建的 current 表（含读取授权副本或 Owner 列）不属于任何发布版本，初始化时会被
 明确拒绝。迁移尚未完成时，apply 会删除并重建这张派生表，结果报告提示随后执行投影重建；迁移已完成
 时，停服后直接执行上述投影重建命令。两种方式都只重建这张派生表，并从正式记录恢复活跃记忆，
-不改变 Artifact 历史、Family 状态和授权记录。
+不改变 Artifact 历史、head 的生命周期数据和授权记录。

docs/zh/docs/workflows/atomic-memory.md

@@ -131,9 +131,11 @@ Atomic Memory 将每条事实、偏好或决策保存为独立的 `atomic-memory
 {"scope_id": "S", "target": {"artifact_id": "B"}}
 ```
 
-恢复 forgotten 使其重新在役；恢复已经 active 且未指定 revision 的记忆返回未变化。
+恢复 forgotten 使其重新在役；恢复已经 active 且未指定 revision 的记忆返回 `changed: false`，不追加版本。
 恢复 merged 会撤销冻结该目标的后续合并。例如 A+B→C、C+D→E，恢复 B 会让 A、B、D 在役，C、E 退役。
-普通下游 Artifact 和 Source cursor 不随之回滚。指定 `target.revision` 时，将所选历史正文保存为目标的新 revision。
+普通下游 Artifact 和 Source cursor 不随之回滚。每个实际恢复或退役的记忆均在原 Artifact 身份下追加新 revision，
+版本号为其当前 revision 加一。恢复输入使用被冻结时的正文；指定 `target.revision` 时，目标的新版本使用所选历史正文。
+旧版本和原始合并关系保留，精确历史读取仍返回原内容；当前读取和检索跟随恢复后的新版本。
 
 先查看影响范围可调用 `POST /v1/atomic-memory/restoration-previews`：
 
@@ -155,9 +157,19 @@ operation 和 target 向 restorations 提交原 token：
 ```
 
 成功响应返回 `changed`、恢复后的精确 `restored` 引用、`retired` 和 `undo_merge_results`。
+`changed: true` 时，`restored` 和 `retired` 均引用实际变化对象所追加的新版本。
+no-op 返回 `changed: false`，`restored` 保留当前主制品的引用，不追加版本。
 若要撤销创建结果 C 的合并，改用 `operation: "undo_merge"`、`target: {"artifact_id": "C"}`；
 该操作不能同时指定内容 revision。
 
+公共 Python runtime 可以按本次操作的主新版本查询精确的整组历史结果：
+
+```python
+outcome = await runtime.artifact_merge.for_scope("S", "atomic-memory").restoration_outcome("B", revision=2)
+```
+
+将 `2` 替换为本次操作产生的主版本。该版本没有保存恢复结果时返回 `None`；读取需要所有受影响制品的读取权限。
+
 | 错误 | HTTP 状态 | 处理 |
 | --- | --- | --- |
 | `invalid_preview` | 422 | 检查 token、主体、Scope、operation、target 及共享签名配置 |
@@ -167,7 +179,7 @@ operation 和 target 向 restorations 提交原 token：
 | `atomic_memory_changed` | 409 | 当前内容或状态已变，重新读取后决定是否重试 |
 | `invalid_memory_relation` | 409 | 关系数据不一致，需要排查存储数据 |
 
-恢复与合并没有 `idempotency_key`，不返回某次旧请求的持久回执。不带 token 的恢复按每次调用时的当前关系解释；
+恢复与合并没有 `idempotency_key`，不会自动重放某次旧请求的响应。不带 token 的恢复按每次调用时的当前关系解释；
 目标后来又被合并，重复请求可能撤销新的合并。携带 token 的成功请求重发也可能返回 `preview_stale`。
 连接在提交时中断，应先读取各对象状态确认结果，再决定是否重新预览。Python SDK 不盲目重试结果未知的写入。
 签名密钥、有效期及直接恢复重试预算见[配置](../operate/configuration.md#atomic-memory)。