Skip to content

Add canonical workspace baseline version authority - #1743

Merged
likun666661 merged 5 commits into
apache:mainfrom
zhiiw:codex/workspace-version-authority
Aug 2, 2026
Merged

Add canonical workspace baseline version authority#1743
likun666661 merged 5 commits into
apache:mainfrom
zhiiw:codex/workspace-version-authority

Conversation

@zhiiw

@zhiiw zhiiw commented Aug 1, 2026

Copy link
Copy Markdown
Contributor

Summary

Add a baseline-only workspace authority backed by immutable RuntimeEvents and one atomic SQLite writer.

  • Define strict maka.workspace.epoch_opened@1 and baseline-specific maka.workspace.baseline_accepted@1 facts.
  • Keep the future generic maka.workspace.version_accepted@1 namespace available for real mutation, undo, rebaseline, and merge protocols.
  • Place each epoch on a deterministic, store-owned control-plane RuntimeEvent spine rather than a user Session or AgentRun.
  • Reserve maka_workspace_authority from ordinary Session creation/import and conversation lifecycle paths.
  • Add schema 7 projections for workspace epochs, versions, and heads, guarded by runtime_workspace_version_authority@1; schema 8 adds a singleton durable storage-root binding.
  • Bind the authority database to one authenticated durable rootId before logical state exists, and revalidate that binding in the same SQLite transaction that commits the two canonical facts and all three projections.
  • Rebuild disposable projections from strict immutable facts and fail closed on malformed, orphaned, duplicated, or row/payload-mismatched authority state.
  • Read canonical facts and projections from one SQLite snapshot so a concurrent baseline commit cannot produce false corruption.

Why

A managed Git workspace needs one durable answer to which baseline identity Maka accepted for an epoch. Git refs retain artifacts but do not own Runtime acceptance; mutable projections cannot be the source of truth.

RuntimeEvents remain the canonical causal facts. SQLite projections are disposable and continuously cross-checked against them.

Merge gate: verified artifact receipt

This authority remains package-internal and must not gain a production caller until the Baseline Open composition supplies a durable, typed, and re-verifiable receipt from the Git workspace owner. The foundation PR itself may merge independently because no public execution path can invoke the raw writer.

The current foundation proves fact shape, atomic persistence, arbitration, and rebuild behavior. It does not run Git and therefore cannot independently prove that a supplied commit/tree exists. Raw OIDs, a TypeScript brand, or a caller-provided verified: true flag are not acceptable substitutes for the receipt seam.

Invariant and atomic boundary

For one baseline bundle, the epoch-opened fact, baseline-accepted fact, epoch projection, version projection, and head projection become visible together or not at all. Concurrent exact submissions converge; conflicting identities fail closed.

  • Protocol owner: strict contracts and pure scanner in @maka/core
  • Writer owner: a storage-internal registered writer backed by SqliteRuntimeStore; it is unavailable from the public package surface
  • Atomic boundary: one BEGIN IMMEDIATE ... COMMIT transaction
  • Failure state: malformed facts, semantic-lane conflicts, incomplete pairs, projection mismatch, and authority-stream contamination fail closed
  • Rollback: uncommitted bundles disappear completely; schemas 7/8 are additive, while binary downgrade requires a pre-upgrade backup

Scope limits

This PR intentionally does not:

  • execute Git or independently verify commit/tree/ref existence;
  • create or own a managed repository/worktree;
  • define generic mutation-version, prepared, settled, no-op, or head-CAS facts;
  • integrate Write/Edit, provider admission, Desktop, CLI, or automatic resume.

The verified receipt contract and Baseline Open composition are the required next slices before this authority can become a production acceptance path.

Validation

  • Core, storage, and runtime builds passed locally.
  • Changed files pass Biome formatting.
  • 82 focused authority/storage/recovery tests and 11 multiprocess concurrency tests passed, including strict baseline decoding, transaction failpoints, projection rebuild, exact/conflicting baseline arbitration, concurrent schema 6→8 migration, durable rootId exact binding, unbound logical-data rejection, and reserved control-session identity.
  • 59 RuntimeEvent read-model tests passed in the previous foundation validation.
  • Real process-kill workspace baseline tests remain release evidence for Linux/macOS; this Windows run does not claim equivalent kill durability.
中文说明

概要

新增 baseline-only Workspace Authority,以 immutable RuntimeEvents 为事实权威,并由一个 SQLite 专用原子 writer 提交。

  • 定义严格的 maka.workspace.epoch_opened@1 与 baseline-specific maka.workspace.baseline_accepted@1
  • 为未来真实 mutation、undo、rebaseline 与 merge 保留通用 maka.workspace.version_accepted@1 命名空间。
  • 每个 epoch 使用 store-owned control-plane RuntimeEvent spine,不挂在用户 Session 或 AgentRun 下。
  • 普通 Session create/import 与 conversation lifecycle 不能占用 maka_workspace_authority
  • schema 7 增加 epoch/version/head projection,并由 capability 保护;schema 8 增加 singleton durable storage-root binding。
  • authority 数据库必须在逻辑状态写入前绑定 authenticated durable rootId;该 binding 与两条 canonical facts、三张 projection 在同一 SQLite transaction 中重新校验并提交。
  • projection 可从严格 immutable facts 重建;malformed、orphan、duplicate、row/payload mismatch 全部 fail closed。

合并硬门槛:verified artifact receipt

本 authority 保持 package-internal;Baseline Open composition 提供由 Git workspace owner 持久化、typed、可重读并可重新验证的 receipt 之前,不得拥有生产 caller。由于 raw writer 不存在 public execution path,本 foundation PR 本身可以独立合并。

当前 foundation 只证明事实形状、原子持久化、并发仲裁与 projection rebuild。它不执行 Git,因此不能独立证明 supplied commit/tree 真实存在。裸 OID、TypeScript brand 或 caller 自报 verified: true 都不能替代 receipt seam。

不变量与原子边界

同一个 baseline bundle 的 epoch-opened fact、baseline-accepted fact、epoch/version/head projection 只能一起可见或一起不可见。并发 exact submission 收敛,identity 冲突 fail closed。

  • 协议 owner: @maka/core strict contract 与 pure scanner
  • Writer owner: storage-internal registered writer,由 SqliteRuntimeStore 实现且不暴露在 package public surface
  • 原子边界: 单个 BEGIN IMMEDIATE ... COMMIT
  • 失败状态: malformed fact、semantic-lane conflict、incomplete pair、projection mismatch 与 authority-stream contamination 全部 fail closed

明确不包含

  • 执行 Git 或独立验证 commit/tree/ref 真实存在;
  • 创建或持有 managed repository/worktree;
  • 通用 mutation version、prepared、settled、no-op 或 head CAS facts;
  • Write/Edit、provider admission、Desktop、CLI 或自动 resume 接线。

verified receipt contract 与 Baseline Open composition 是本 authority 成为生产 acceptance path 之前的必需后续切片。

验证

  • Core、Storage、Runtime build 本地通过。
  • 本分支变更文件通过 Biome formatting。
  • authority/storage/recovery focused tests 82/82,multiprocess concurrency tests 11/11;覆盖 strict baseline decoder、transaction failpoint、projection rebuild、exact/conflicting baseline 仲裁、并发 schema 6→8 migration、durable rootId exact binding、unbound logical-data 拒绝与 reserved control-session identity。
  • 前一轮 foundation 验证中的 RuntimeEvent read-model tests 59/59。
  • 真实 process-kill baseline proof 仍由 Linux/macOS 承担;本次 Windows 运行不宣称同等 kill durability。

@zhiiw

zhiiw commented Aug 1, 2026

Copy link
Copy Markdown
Contributor Author

The baseline-protocol findings are addressed in e2e23f2f, with one explicit merge gate retained.

  • The fact is now baseline-specific: maka.workspace.baseline_accepted@1 / workspace_baseline_accepted_v1.
  • The generic workspace.version_accepted@1 namespace is no longer frozen around baseline-only parents/origin rules.
  • maka_workspace_authority is rejected by the ordinary Session identity guard, covering regular creation and import paths that share that guard.
  • The architecture document now states that this PR must remain Draft until a durable, typed, re-verifiable Git baseline receipt is consumed by the Baseline Open composition.

I am not treating a TypeScript brand or caller-provided verified: true as a solution to the missing-artifact problem. This branch proves the RuntimeEvent/SQLite authority mechanics only; it will not be marked Ready or gain a production caller before the receipt seam exists.

Local validation is green: core/storage/runtime builds, changed-file Biome formatting, and 26 focused authority/storage tests.

中文说明

e2e23f2f 已处理 baseline 协议评审项,同时明确保留一个合并硬门槛:

  • fact 已改为 baseline-specific:maka.workspace.baseline_accepted@1 / workspace_baseline_accepted_v1
  • 通用 workspace.version_accepted@1 不再被 baseline-only parents/origin 规则冻结;
  • 普通 Session identity guard 现在拒绝 maka_workspace_authority,覆盖共用该 guard 的常规创建与导入路径;
  • 架构文档明确:durable、typed、可重新验证的 Git baseline receipt 被 Baseline Open composition 消费前,本 PR 必须保持 Draft。

我没有用 TypeScript brand 或 caller 自报 verified: true 来假装解决 artifact 不存在的问题。本分支只证明 RuntimeEvent/SQLite authority mechanics;receipt seam 存在前不会标记 Ready,也不会接入生产 caller。

本地验证通过:core/storage/runtime builds、变更文件 Biome formatting、authority/storage focused tests 26/26。

@zhiiw
zhiiw marked this pull request as ready for review August 1, 2026 11:03
@likun666661
likun666661 merged commit d286586 into apache:main Aug 2, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants