# Workspace Version Authority v1:Baseline 事实权威 - 状态:authority foundation 已合并;schema 9 reader/migration、RuntimeEvents、projection reader/rebuild 继续受支持,当前没有生产 baseline writer consumer - 更新日期:2026-08-29 - 主要不变量:经专用 writer 提交的一个 workspace epoch,其 baseline canonical facts 与三个 SQLite projection 对外只能全可见或全不可见 - 事实权威:immutable RuntimeEvents - artifact owner:后续 Gitoxide data plane;本切片不执行 Git 命令 - 主要发布证明平台:Linux、macOS;Windows 当前仅验证 SQLite 事务与多进程路径 ## 1. 本切片为什么存在 Git-native managed workspace 需要先回答一个比“怎样创建 worktree”更基础的问题: > 哪一个 Git commit/tree 已被 Maka 正式接受为某个 workspace epoch 的初始版本? 如果答案只存在于 Git ref、内存对象或一张可变的 `workspace_heads` 表里,崩溃、重建或并发打开都可能 产生第二套真相。本切片因此先建立一个很窄的 authority: ```text epoch opened RuntimeEvent + baseline version accepted RuntimeEvent + epoch projection + version projection + head projection ``` 五部分由一个专用 SQLite writer 在同一个事务中提交。RuntimeEvents 是 canonical facts;三张表只是 可删除、可重建、每次读取都要与 canonical facts 交叉验证的 projection。若维护操作或外部损坏只删除 projection,公开 reader 会 fail closed,直到显式 rebuild;这种损坏态不被伪装成合法的“全不可见”。 本节定义的 baseline transaction 只接受 baseline;独立的 successor/mutation authority extension 不属于这个 历史切片。它不创建 internal repository、不创建 worktree、不调用工具,也不改变 Desktop/CLI 行为。 authority slice 本身只证明事实合同、SQLite 原子写入与 projection 可重建性。旧 Git-CLI-shaped Baseline Open composition 从未获得生产调用方,现已删除;后续生产 writer 必须由 Gitoxide data plane 建立新的窄 admission 边界。裸 OID、TypeScript brand、caller 自报的 `verified: true` 或 caller 提供的 policy hash 都不构成证据。 ## 2. Owner、边界、失败状态与回滚 | 项目 | 决策 | |---|---| | 协议 owner | `@maka/core` 的 strict fact contract 与 pure scanner | | baseline 写入 owner | storage-internal WeakMap writer;不属于 package API,当前没有 production baseline producer;独立 successor/mutation writer 不由旧 owner 提供 | | 原子性边界 | 单个 `BEGIN IMMEDIATE ... COMMIT` SQLite transaction | | canonical source | store-owned authority stream 中的两条 immutable RuntimeEvents | | disposable state | `runtime_workspace_epochs`、`runtime_workspace_versions`、`runtime_workspace_heads` | | 正常失败 | exact retry 返回 existing;payload/identity drift 返回 conflict | | 损坏失败 | malformed fact、orphan、projection mismatch、partial snapshot 污染全部 fail closed | | 运行时回滚 | 事务未提交时五部分全部回滚;已提交时五部分全部可读 | | 版本回滚 | schema 9 数据库不能由只支持 schema 8 的旧 binary 打开;降级必须使用升级前备份 | 逻辑回滚可以停止调用本 writer,但必须保留 schema 9 reader/migration;不能通过删除 capability marker 伪装成旧格式。 ## 3. Authority stream Workspace facts 不挂在普通用户 Session、AgentRun 或工具 invocation 下。每个 epoch 使用一个确定性的 store-owned execution spine: ```text sessionId = maka_workspace_authority invocationId = workspace_inv_ runId = workspace_run_ turnId = workspace_turn_ event_seq = 1 (epoch opened), 2 (baseline accepted) ``` 原因: 1. 普通 conversation copy/purge 不能复制或删除 workspace authority; 2. provider replay 与 UI 消息不应看到 control-plane facts; 3. caller 不能借普通 append、T1/T2、recovery bundle 或 continuation writer 写入保留语义; 4. 每个 epoch 有独立、确定、可重试的物理 spine。 `RuntimeEvent` 的 execution identity 通常对应 AgentRun,但协议现在明确允许 storage-owned control-plane stream。这个例外只由专用 writer 创建,不能成为 generic append 的逃生口。 ## 4. v1 事实合同 ### 4.1 Epoch opened ```ts { kind: 'maka.workspace.epoch_opened', version: 1, payload: { protocol: 'workspace_epoch_opened_v1', repositoryId, workspaceId, workspaceEpochId, workspaceInstanceId, initialWorkspaceVersionId, mode: 'managed_worktree', objectFormat: 'sha1' | 'sha256', sourceCommitOid, sourceTreeOid, materializationProfileDigest, materializationSemantics: 'git_tree_materialized_with_fixed_config_v1', policyHash } } ``` ### 4.2 Baseline version accepted ```ts { kind: 'maka.workspace.baseline_accepted', version: 1, payload: { protocol: 'workspace_baseline_accepted_v1', repositoryId, workspaceId, workspaceEpochId, workspaceVersionId, objectFormat: 'sha1' | 'sha256', parents: [], origin: { kind: 'baseline', epochOpenedEventId }, commitOid, treeOid, policyHash, treeDeltaDigest, changedFileCount, deletedFileCount: 0 } } ``` Strict decoder 逐层拒绝额外字段、未知 kind/version/protocol、非法 namespace ID、非小写 digest、 不安全计数以及与 `objectFormat` 长度不符的 Git OID。它不做 legacy normalization,也不允许 `runtimeFact` 充当 workspace fact 的别名。 跨事实 scanner 还必须证明: - 两条事实的 repository/workspace/epoch/object format/policy 一致; - `initialWorkspaceVersionId === workspaceVersionId`; - baseline origin 精确引用 epoch event; - baseline `treeOid === sourceTreeOid`; - baseline 没有 parent,也没有 deletion; - 两条事件位于同一条确定 authority spine 的 seq 1/2。 ## 5. Semantic lane 与写权限 合法 workspace fact event 的唯一形状是: ```text partial = false role = system author = system content/status/branch/refs = absent actions 的唯一 key = workspaceFact ``` 任何与 text、function call/response、tool dispatch/recovery、continuation、terminal state 或 partial 混合的事件都是 lane corruption。 Writer reservation 同时覆盖: - SQLite generic append、batch import 与 terminal writer; - JSONL append 与 terminal writer; - tool T1/T2; - recovery bundle; - continuation claim/start; - conversation copy; - ordinary event 占用保留 authority stream; - ordinary Session purge 试图删除 authority session。 storage 内部 writer 接受 typed baseline input,由 store 自己构造 RuntimeEvents。它不接受 caller 拼好的 event,因此 caller 没有机会夹带另一条 semantic lane。该 seam 所在模块不从 `@maka/storage` 导出; 公开 store 只暴露 capability、reader 与 projection rebuild。baseline raw writer 不进入 package root exports, 当前没有生产 composition 可以调用它。 ## 6. Baseline writer 状态 `commitWorkspaceBaselineInternal` 继续作为 schema 9 authority 的 storage-internal 测试 seam,用于证明 atomic bundle、exact retry、conflict、crash rollback 与 projection rebuild。旧 Git executable receipt → writer composition 已删除;后续 Gitoxide producer 必须重新建立 artifact admission,不能复用或恢复旧 owner、receipt 或 worktree materialization path。 ## 7. Schema 7–8 与 projection Schema 7 从 schema 6 增加 workspace authority facts/projections 并写入 capability: ```text runtime_workspace_version_authority @ 1 ``` 三张 projection: | 表 | 含义 | |---|---| | `runtime_workspace_epochs` | epoch identity、source 与 materialization policy | | `runtime_workspace_versions` | accepted baseline commit/tree 与因果引用 | | `runtime_workspace_heads` | 当前 epoch head;M0 必须等于 baseline | | `runtime_storage_root_binding` | singleton durable rootId;阻止单独复制/移动 `runtime.sqlite` 后被另一 storage root 静默认领 | Schema 9 增加 `runtime_storage_root_binding(singleton=1, root_id, protocol_version=1)`。当时 schema 8 仍含 旧 Eval harness 的 event table;schema 12 已删除该表。M0 在任何 workspace fact 写入前,通过 storage-internal binder 将它绑定到 authenticated root owner 的 durable `rootId`;已绑定数据库只接受 exact rootId。没有 binding 但已经含任何 Session、RuntimeEvent、claim 或 workspace fact 等逻辑数据的实验数据库必须显式 adopt/清理,不能自动认领;只有除 schema/capability metadata 外完全为空的新数据库可以首次绑定。正式 whole-root import 保留 marker 与数据库中的同一 rootId,并只通过 `adoptStorageRootOnImport` 更新 host-local dev/ino,因此仍可打开;只复制 `runtime.sqlite` 会 fail closed。 公开的 `WorkspaceHeadRecordV1` 使用通用字段 `acceptedEventId`,因为后续 head 可能由 mutation acceptance 推进;只有 baseline version record 与 canonical scanner 使用更具体的 `baselineAcceptedEventId`。SQLite 列继续使用语义稳定的 `accepted_event_id`,不把 M0 的 baseline 特例固化为长期 head 合同。 构造 store 时缺少 capability、capability 版本未知或数据库 schema 比 binary 新,全部拒绝打开;不静默 降级到 JSONL 或无 authority 模式。 读取 epoch/version/head 时,store 先从全部 immutable RuntimeEvents 重建 canonical baseline 集合,再与 三张 projection 做完整比较。整次 canonical scan、projection compare 与目标 lookup 必须位于同一个 SQLite read transaction/snapshot;否则并发 writer 可能让读者拼接两个合法时刻并误报 corruption。 不能只信 projection,也不能用冗余 `event_kind` 过滤 canonical rows。 显式 rebuild 先在内存中严格扫描所有事实,只有 canonical ledger 完整时才在一个事务中替换 projection。 扫描失败不会先清空旧 projection;事务插入失败也会保留旧状态。 ## 8. 幂等、并发与 crash matrix | 场景 | 必须结果 | |---|---| | 同一进程 exact retry | `created=false`,不新增 event | | 两进程提交相同 baseline | 一个 created、一个 existing | | 两进程提交冲突 baseline | 只接受一个;另一个 conflict | | reader 扫描期间另一进程提交 baseline | reader 在旧 snapshot 返回 absent;下一次读取看到完整 baseline | | schema 6/7 两进程同时升级 | 在 migration lock 内重读版本,每个 pending migration 只执行一次 | | epoch event insert 后崩溃 | facts/projections 全无 | | version event insert 后崩溃 | facts/projections 全无 | | epoch projection insert 后崩溃 | facts/projections 全无 | | version projection insert 后崩溃 | facts/projections 全无 | | head projection insert 后崩溃 | facts/projections 全无 | | COMMIT 后进程被杀 | 两条 facts 与三张 projection 全部可读 | | projection 被删除 | explicit rebuild 精确恢复 | | canonical payload/row 被篡改 | read/rebuild fail closed | | authority partial snapshot 出现 | fail closed,不把 mutable state 当 canonical fact | 事务内五个 failpoint 已有定向 rollback 测试。真实子进程 kill harness 覆盖“事务内被杀”和“commit 后被杀”;它在 Linux/macOS CI 承担发布证明,Windows 本地不反向宣称同等 crash durability。 ## 9. 平台能力矩阵 | 能力 | Linux | macOS | Windows | |---|---|---|---| | strict fact/lane | 支持 | 支持 | 支持 | | SQLite bundle 原子性 | 支持 | 支持 | 支持 | | 多进程 exact/conflict arbitration | 支持 | 支持 | 已有定向测试 | | schema 6/7→8 并发升级 | 支持 | 支持 | 已有定向测试 | | 真实 SIGKILL crash harness | 发布门槛 | 发布门槛 | 当前不承诺 | | Git object/worktree 语义 | 后续切片 | 后续切片 | 后续能力矩阵 | 本表只描述 authority persistence,不能推导 managed worktree 已跨平台可用。 ## 10. Baseline slice 之外的扩展 以下能力不由本文的 baseline authority slice 定义;它们可以由独立 authority extension 提供: - verified Git runtime 探测、source eligibility 与 internal bare repository; - managed worktree 创建、owner lifecycle、quarantine 与 repair; - `.maka-workspace.json` 在 managed worktree 的 identity/exclude 策略; - ignored dependency/cache 路径的挂载或 scratch policy; - tool mutation prepared/settled/no-op facts; - T1/T2 与 workspace version 的原子接受; - head CAS、conditional redo、undo、publish 与 multi-agent merge; - continuation boundary 绑定 workspace version; - Desktop/CLI 设置、默认启用或自动恢复。 本文不定义 mutation。Successor/mutation fact 必须由其独立 authority 与真实 Durable Write 的 T1/T2、 tool outcome 引用、session retention 和 head CAS 一起冻结。 ## 11. 后续生产接线 旧 Git-CLI-shaped service、owner、receipt 与 worktree materialization path 已删除,不能成为新生产 backend 的 identity owner。 当前 Gitoxide 验证栈已拆成三个窄、可独立合并的 enabling-infrastructure 层:isolated short-lived Rust helper、exact helper artifact → opaque invocation capability、bounded invocation → opaque repository admission capability。分别见: - [`gitoxide-short-lived-helper-admission-v1.zh-CN.md`](./gitoxide-short-lived-helper-admission-v1.zh-CN.md) - [`gitoxide-helper-artifact-authority-v1.zh-CN.md`](./gitoxide-helper-artifact-authority-v1.zh-CN.md) - [`gitoxide-helper-invocation-owner-v1.zh-CN.md`](./gitoxide-helper-invocation-owner-v1.zh-CN.md) - [`gitoxide-repository-admission-capability-v1.zh-CN.md`](./gitoxide-repository-admission-capability-v1.zh-CN.md) 这些基础设施尚未建立 signed packaged-release trust root,也没有 Desktop/CLI/T1 消费者,因此不能据此 恢复 managed mode。后续 production writer 必须从真实 Gitoxide artifact admission 出发,并继续复用本 文档定义的 schema 9 RuntimeEvents 与 projection authority;接线前仍需先拍板 ignored dependencies/scratch、 identity marker、symlink/LFS/submodule/case/filemode 平台政策。