@zq-silk/yui 0.16.2 → 1.0.0-alpha

package/docs/sqlite-control-plane-design.md

@@ -2,312 +2,71 @@
 
 # SQLite control-plane storage
 
-Yui has one authoritative product Store: `YUI_HOME/yui.db` in WAL mode. The
-highest contiguous, checksummed row in `schema_migrations` is the one Home
-storage version accepted by the running release.
+Yui has one authoritative product Store: `YUI_HOME/yui.db`, in WAL mode.
+`storage_schema` contains its single **major.minor** version and schema
+checksum. The clean baseline is **1.0**, introduced by package 1.0.0-alpha.
 
 ## Authority
 
-- `yui.db` owns Tasks, WorkItems, AgentRuns, Messages, Decisions, results, Project
-  Knowledge references, managed workspace records, runtime bindings, mailboxes,
-  durable events, and configuration.
-- Provider Sessions, transcripts, processes, caches, telemetry, and runtime
-  observations support execution and diagnosis; they do not replace durable
-  Task facts.
-- Configuration and diagnostics outside the database do not define another
-  storage version or permit rebuilding Task truth heuristically.
+- SQLite owns Tasks, WorkItems, AgentRuns, Messages, Decisions, results,
+  Project Knowledge, workspace records, runtime bindings, mailboxes, events
+  and configuration.
+- Provider Sessions, transcripts, processes, caches and telemetry support
+  execution and diagnosis; they do not replace durable Task truth.
+- Record `schemaVersion` tags validate current envelopes. They are not
+  separately writable upgrade versions.
+- `storage_migration_archive` preserves opaque original payloads and binary
+  audit evidence. It is not a compatibility reader, scheduler or cache.
 
 ## Admission
 
-Ordinary commands open a Home only when all of these are true:
+Ordinary opens require the exact current format/version/checksum, the current
+physical schema objects, and valid typed records. A missing database in a
+non-empty Home or a missing format identity is not permission to initialize.
+New Homes execute the final baseline DDL once, without replaying old DDL.
 
-1. `yui.db` exists and its migration ledger is a valid immutable prefix.
-2. The ledger head exactly matches the running CLI's current storage version.
-3. Current record validation and reference integrity succeed.
-
-An older Home inside the CLI's supported range fails ordinary admission but is
-classified as upgradeable. `yui doctor` and `yui upgrade --dry-run` report the
-ordered path without changing the Home. Explicit `yui upgrade` is the only
-standalone mutation boundary: it quiesces the Controller, backs up `yui.db`,
-applies all missing migrations transactionally, and validates the current
-model. A newer, below-minimum, incomplete, or malformed Home fails closed.
-There is no runtime normalization, repair worker, file-Store fallback, dual
-read/write path, or second migration authority.
-
-Typed domain payloads use one current validator registry on writes, ordinary
-reads, bounded Context pages and full-Home diagnostics. Direct and worker-backed
-Stores do not have different validation strength. Invalid records are rejected
-without advancing the revision; an invalid stored record remains available for
-explicit diagnosis, never normalized into a valid-looking replacement.
-
-Storage 35 also has a migration-only `storage_migration_archive` table:
-`migration_version / family / record_key / payload / content`. It retains exact
-retired Project/gate payloads and binary logs without interpreting them in the
-current model. It is not scheduling state, a second cache or a runtime fallback.
-Task-scoped historical Integration retirement uses ordinary Task Events.
-Backups retain both current records and this audit archive.
+Writes, ordinary reads, bounded Context pages and full-Home diagnostics share
+the current domain validators. Invalid records fail without normalization;
+failed writes do not advance the Home revision. An open writer rechecks its
+captured schema identity before every mutation.
 
 ## Write and concurrency contract
 
-- Each mutation is one SQLite transaction.
-- WAL plus `synchronous=FULL` provides the durable commit boundary.
-- `home_meta.revision` is the Home-wide CAS/revision used by callers that need
-  a frozen read/modify/write boundary.
-- Typed columns support indexed identity and status queries; the full validated
-  record payload remains the durable domain representation.
-- Mailbox claim, exact AgentRun terminalization, active-pointer removal, result
-  persistence, and downstream wake creation are transactionally coupled where
-  they form one product fact.
-- Idempotency keys and unique constraints protect repeatable external-effect
-  acknowledgements; they do not form a second workflow state machine.
+- Each mutation is a SQLite transaction; WAL plus `synchronous=FULL` is the
+  durable commit boundary.
+- `home_meta.revision` is the Home-wide CAS/revision, not a format version.
+- Indexed typed columns support exact identity/status queries; full validated
+  payloads remain the durable domain representation.
+- Mailbox claims, exact Run terminalization, active-pointer removal, result
+  persistence and downstream notifications commit together where they express
+  one product fact.
+- Idempotency and unique constraints protect confirmed external effects,
+  without inventing a second planning protocol.
 
 ## AgentRun and Session boundary
 
-An AgentRun is an explicitly requested execution. It records associated visible
-inputs and the original result, not hidden reasoning or the full tool trace.
-A Provider Session can contain multiple Runs, ordinary native chat and
-notifications. Native chat and notifications do not automatically create Runs.
-Only an exactly correlated native terminal settles the Run; the Leader remains
-the authority for WorkItem and Task acceptance.
+An AgentRun records an explicit execution request, visible input and original
+result, not hidden reasoning. A native Session may contain several Runs and
+ordinary conversations. Notifications alone do not create Runs; only exact
+native evidence settles one. WorkItem and Task acceptance remain Agent-owned.
 
 ## Update behavior
 
-`yui update` stages an exact package and asks that staged binary to classify the
-Home as current, migration-ready, or blocked. It then stops the exact
-Controller, activates the same package, runs the staged release's complete
-migration chain when required, verifies the installed binary and current Home,
-and starts the replacement Controller.
+Version APIs expose `"1.0"` strings, not floats. Default `upgrade` / `update`
+supports only a known contiguous minor path within the same storage major.
+The initial baseline has no such steps. Cross-major and old integer formats
+require an independent explicit converter; they never enter a runtime fallback.
+The updater preflights the exact staged package before activation, then rechecks
+under its maintenance fence. Unknown ownership remains a blocker.
 
-Every persistent schema or payload change appends one immutable, contiguous
-storage migration. The CLI publishes both `storageVersion` and
-`minimumStorageVersion`; every valid Home in that inclusive range can upgrade
-directly to the current version without installing intermediate releases.
-The current version and migration floor are declared only in
-`src/storage/storageVersions.ts` and exposed by CLI identity. Homes below that
-floor are not migration inputs and remain untouched.
-The target binary's `upgrade --update-preflight` and `--update-apply` result
-shapes and parent-owned handover-lock proof remain backward compatible with
-every updater released from storage version 1 onward, so an old source CLI can
-still drive a much newer target's complete migration chain.
+See [Storage baseline 1.0](./storage-baseline.md) for the independent old-v37
+conversion, backup/rollback, artifact boundaries and cold startup procedure.
 
 ## Unified Home layout
 
-Every Yui self-managed directory lives under the single canonical `YUI_HOME`
-(default `~/.yui`; an explicit `YUI_HOME` is honoured verbatim). `YUI_HOME` is
-never inferred from the current working directory and never substituted with a
-username. `src/storage/homeLayout.ts` is the one authority that derives each
-managed root from Home:
-
-| Root | Path | Holds |
-|---|---|---|
-| Managed worktrees | `<home>/workspaces/tasks/<taskId>/<owner>/<projectDirectory>` | Actual Task/WorkItem/Review/Integration Git directories, addressed by the bound Project directory. Owners are `main`, `work-items/<id>`, `reviews/<id>`, `integrations/<id>` and `execution-lanes/<group>/<lane>`. |
-| Read-only context views | Within the same owner directory | Regenerable symlinks to read-only Project context only; writable entries are actual Git directories, not links. |
-| Global Role workspace | `<home>/workspaces/global` | Default cwd for Yui-auto-created Global Roles (the `yui setup` Operator/Leader and ad-hoc Global Roles added without an explicit `--workspace`). A plain cwd, not a managed Git workspace. |
-| Task provider runtimes | `<home>/runtime/task-runtimes` | Task provider data/cache/tmp; also the planning cwd at `…/planning/<taskId>`. |
-| Integration runtimes | `<home>/runtime/integration-runtimes` | The integration check's provider data/cache/tmp (a separate partition from Task runtimes). |
-| Update staging | `<home>/runtime/update-staging` | `yui update`'s side-by-side package install (an upgrade artifact). |
-| Release workflow scratch | `<home>/runtime/release-workflow` | The release workflow's smoke-install dir and verified publish-snapshot tarball (release artifacts). |
-| Storage backups | `<home>/backups` | Pre-upgrade DB backups (the fenced upgrade's rollback anchor). |
-
-Published migrations 1–23 remain unchanged, including Task artifacts in local
-Git (19), Integration continuation (20), force-archive evidence (21), and
-Controller-owned Host ingress (22), and unified message input control (23).
-The two offline layout steps are now 23→24 (`unify-home-layout`) and
-24→25 (`collapse-worktree-layout`). Version 24's
-`workspaces/worktree` directory is an intermediate layout, not a second live
-root at version 25. A single upgrade applies the full pending chain.
-
-Stop this Home's writers and take a backup before upgrading. The layout steps
-copy and verify the registered Git trees, repair only the copies' links, and
-preserve old sources for manual recovery. Version 25 replaces registered
-Task-view symlinks with real writable directories; unrelated Task scratch is
-retained. Read-only context remains a view and can be promoted to a writable
-worktree when WorkItem scope expands. Do not delete the old sources until the
-new layout is verified; a failed upgrade requires manual residue cleanup and
-backup recovery, not automatic resume.
-
-Both runtime partitions (`runtime/task-runtimes`, `runtime/integration-runtimes`)
-are the ONLY Home subtrees a provider runtime root is allowed to overlap; a
-runtime root overlapping any other part of Home (the database, `workspaces/`,
-`projects/`) is still rejected by `assertTaskRuntimeIsolationPreflight`, so
-unifying the root does not weaken control-data or cross-owner isolation.
-
-`defaultWorkspace` is a user-facing cwd for external Project input only; it is
-**not** a second authority for internal managed paths, and is intentionally not
-an input to `homeLayout.ts`. A Yui-auto-created Global Role that carries no
-user-chosen cwd no longer falls back to it (or to `process.cwd()`): `yui setup`'s
-built-in Operator/Leader and `yui config role add` without `--workspace` now default to
-the Home-internal `managedGlobalRoleWorkspace(home)` (`<home>/workspaces/global`),
-and `setup` no longer fabricates an external Home-sibling `workspace/` — a
-`default-workspace` is persisted only if the user configured one. A user who
-*names* an external directory (explicit `--workspace`, or a configured
-`default-workspace`) keeps external-resource semantics; the outside-Home guard
-still applies to it. The "planning/global cwd" that criterion 1 places under Home
-is thus both the *disposable runtime cwd Yui materializes itself* — the Draft
-planning cwd (`planningRuntimeCwd`, under `runtime/task-runtimes/planning`) — and
-the auto-created Global Role cwd above; only an operator's *explicitly named*
-external directory stays outside by design.
-
-Only genuine short-path IPC socket ENDPOINTS remain outside Home, and only
-because a Unix-domain `sockaddr_un` path has a small fixed length budget that a
-deep Home path would exceed. Each is a single socket path, never a data/cache/tmp
-root:
-
-- the Controller socket (`/tmp/yui-<uid>/<homeId>.sock`),
-- the tmux server socket (`/tmp/tmux-<uid>` via the tmux namespace),
-- the Agent Host socket (`/tmp/yui-<uid>/agent-host/…sock`), and
-- the integration check's tmux socket dir (`/tmp/yi-<uid>-<digest>`), bound only
-  into `TMUX_TMPDIR`.
-
-The integration check's ordinary runtime state is **not** an exception: its
-provider data, cache, and temp roots live in the Home partition above
-(`runtime/integration-runtimes`); `TMPDIR`/`TMP`/`TEMP` point there, and only
-`TMUX_TMPDIR` is redirected to the short `/tmp` socket dir.
-
-## Migration 23 → 24: unify managed paths under Home
-
-Historically the managed worktrees lived under the out-of-Home
-`defaultWorkspace` (`<ws>/worktree`, `<ws>/tasks`) and the provider runtimes
-under a string-built Home sibling (`<home>.task-runtimes`). The one forward
-migration `unify-home-layout` (`src/storage/migrations/unifyHomeLayout.ts`)
-brings that content under Home and rewrites the persisted absolute pointers the
-runtime dereferences as live, without re-cloning Git content or renaming the
-path-independent Git refs. It runs as the migration's `migrateData` step inside
-the upgrade transaction, so schema and data advance atomically or roll back
-together.
-
-**Exactly one tree is physically relocated: the managed Git worktree tree.** It
-is the sole subtree that holds durable, non-regenerable content (committed **and**
-uncommitted work), so it alone is copied on disk. Everything else that "moves"
-moves only by pointer:
-
-- the per-Task symlink views (`<ws>/tasks`) are regenerable — the pointer is
-  rewritten and `ensureWorkspaceView` rebuilds the links at the next launch;
-- the provider runtimes (`<home>.task-runtimes`) are disposable — the pointer is
-  rewritten and the roots are recreated at the next launch.
-
-The worktree copy is **non-destructive and verified** (see *Recovery and
-rollback*): the source is copied (never renamed away), the replica's content
-digest is checked against the source, and only a verified replica is atomically
-published. The original worktree tree is **preserved** as the rollback anchor;
-removing it is a later, authorized, post-restart cleanup step, never part of this
-transaction.
-
-The pointer rewrite is **surgical, not a table sweep** — only records the runtime
-treats as live launch pointers are touched:
-
-- `managed_workspaces` — the authoritative registry (`path` column, payload
-  `root`, every `entries[].path`). Every surviving row is live (dispositioned
-  rows are deleted at cleanup).
-- active (`status='active'`) `turns` — **both** `run.effective.workspace` (the
-  actual OS launch cwd source) and the `run.workspace` mirror, rewritten together
-  because `validateRun` requires them to stay identical; a run's
-  `.result.systemEvidence.workspaceSnapshot` is frozen Git evidence and is left
-  byte-for-byte intact.
-- `role_session_sets` / `global_role_session_sets` — each live session's
-  `effective.workspace` in the `sessions` map; terminal sessions in `history` are
-  preserved.
-- `review_rounds` — the mirrored workspace (only while its `managed_workspaces`
-  owner row still exists) and each OPEN execution lane; an orphaned mirror or a
-  terminal lane is frozen evidence and is preserved.
-- `work_items` — each OPEN execution lane inside `executionGroups`; candidate
-  snapshots (`work_item_candidates`) are frozen and preserved.
-- `task_roles.workspace` — the live launch cwd, including a Draft's planning Role
-  under the old runtime sibling (never self-healed until activation).
-- `task_records.cwd` — self-heals on the next `prepareTaskWorkspace`, but is
-  rewritten defensively to close the stale-read window.
-
-Everything else is preserved on purpose: `context_snapshots`, terminal `turns`
-(with their system evidence), terminal sessions, `work_item_candidates`, terminal
-execution lanes, terminal `durable_jobs`, `events`, and reports are frozen
-history. `resource_registry` is re-discovered from disk; `projects.path` is an
-external, user-owned checkout.
-
-The migration is applied **offline** and is **fail-closed and pre-checkable**.
-It is run by the standalone `yui upgrade` boundary AFTER the operator has stopped
-this Home's Controller, Agent Host, and any execution/Job writers; it does not
-orchestrate that shutdown, coordinate an online write-stop, or migrate a live
-Session. It keeps only the minimal preconditions it can implement directly:
-
-- It **refuses** if a queued or running `durable_jobs` step is bound to a tree
-  about to relocate. A durable Job's runner is detached and could outlive an
-  incompletely stopped Controller, so moving that tree would risk an in-flight
-  silent move; this is the one residual runtime signal the offline migration
-  still guards. Let the Job drain or cancel it, then re-run the upgrade.
-  (`active_turns` is steady state, not an in-flight signal, and is deliberately
-  not consulted.)
-- It **refuses** if a relocation target already exists at all — it is either a
-  foreign directory or residue from a failed prior run, and the offline migration
-  never adopts a pre-existing target. Confirm the source is intact, then move or
-  remove the target and re-run the upgrade.
-- Every refusal is surfaced as a **collected, read-only pre-check**: `yui
-  upgrade --dry-run` and the updater's `--update-preflight` run the same plan and
-  the same blocking conditions execute would throw on, opening the DB read-only
-  and reporting each independent blocker as `{reason, detail}` (blocked outcome)
-  without mutating the Home — a genuine pre-check, not a best-effort guess.
-- A Home already in the unified layout (or a fresh Home with nothing to relocate)
-  is a **no-op**.
-
-### Recovery and rollback
-
-The migration keeps **no recovery manifest and no resumable state machine** — it
-is a one-time offline transform, not an interruptible online orchestration. The
-worktree relocation is **copy → digest-verify → atomic-publish → preserve-source**:
-
-1. the relocation target must not already exist; a pre-existing target is refused
-   up front (foreign directory or failed-run residue — never adopted);
-2. the source is copied into a same-filesystem staging dir (`<to>.incoming`),
-   never renamed away;
-3. a content-addressed inventory digest of the replica is compared to the source
-   — a mismatch deletes the staging copy and aborts (nothing published, source
-   intact);
-4. only a verified replica is `rename`d into the final target (atomic on one
-   filesystem);
-5. the original source tree is left in place as the rollback anchor.
-
-There is **no automatic idempotent recovery**. Because a pre-existing target is
-always refused, a run interrupted after a partial publish does not silently
-resume or adopt the partial tree on the next attempt: the operator inspects the
-preserved source, removes the incomplete target (and any `<to>.incoming`
-staging), and re-runs the upgrade from a clean state. The `--dry-run` /
-`--update-preflight` pre-check surfaces exactly this `target-conflict` before the
-apply transaction is entered, so the residue is reported, not discovered
-mid-migration.
-
-After the copy, the worktrees are reconnected. `git worktree repair` chases the
-absolute pointer files inside a worktree, so running it on a verbatim copy whose
-pointers still address the OLD source would rewrite the OLD source's `.git`
-files and corrupt the rollback anchor. The migration therefore **relinks first**:
-it deterministically repoints, in the NEW copy only, the two cross-reference
-pointer files (a linked worktree's `.git` stub and each
-`main/.git/worktrees/<name>/gitdir`) from OLD to NEW, and only THEN runs `git
-worktree repair` from each main clone at its new path as a belt-and-braces
-reconciliation now confined to the new tree. This keeps the preserved source a
-fully independent, working Git: its `.git` is byte-for-byte unchanged and it
-still resolves HEAD/index/status after the migration (verified empirically on a
-private disposable Home). **A repair failure is fatal** — it aborts the migration
-so the transaction rolls back rather than advancing the version over unrepaired
-worktrees.
-
-Because the data step runs inside the upgrade transaction, any throw rolls the
-schema back to its original version; the fenced upgrade orchestrator additionally takes a
-`database.backup()` and restores it on failure. Recovery from a failed run is
-**manual, not automatic**: because the source is never removed and the copy is
-digest-verified before publish, the preserved source is always intact, so the
-operator clears any partial target and re-runs the upgrade. No re-run can lose or
-corrupt the original content, but the tool does not itself resume an interrupted
-move set.
-
-**Old-source cleanup** is intentionally deferred and out of band: after a
-successful upgrade the old external `worktree`, `tasks`, and `<home>.task-runtimes`
-roots are left **in place** (not emptied) until an operator-authorized cleanup
-removes them. This keeps a full rollback anchor available across the first
-restart.
-
-**Rollback limits:** once the Controller restarts against the unified layout and
-begins writing new records under Home, restoring the pre-upgrade DB backup no
-longer matches the newly written on-disk state. Until that first post-upgrade
-write, the preserved old source plus the DB backup are a complete rollback pair;
-after it, the supported recovery is forward (the layout is already unified), not a
-downgrade to the split layout. Verify an upgrade only on a private, disposable
-Home before applying it to a shared environment.
+Self-managed data stays under one canonical Home: Task worktrees under
+`workspaces/tasks/<task>/<owner>/<project>`, Global scratch under
+`workspaces/global`, runtime data under `runtime`, and backups under `backups`.
+Explicit external Project inputs keep their external-resource semantics.
+Only deliberately short IPC socket paths may live outside Home.
+The converter does not relocate workspaces or rewrite their Git identities.

package/docs/sqlite-control-plane-design.zh-CN.md

@@ -2,72 +2,56 @@
 
 # SQLite 控制面存储
 
-Yui 只有一个权威产品 Store：WAL 模式下的 `YUI_HOME/yui.db`。`schema_migrations`
-中连续且带校验和的最高一行，就是当前发行版接受的那一个 Home 存储版本。
+Yui 唯一的权威产品 Store 是 WAL 模式的 `YUI_HOME/yui.db`。
+`storage_schema` 单行记录唯一的**主版本.小版本**与 Schema 摘要；
+1.0.0-alpha 软件包引入的纯净基线为 **1.0**。
 
 ## 权威
 
-- `yui.db` 拥有 Task、WorkItem、AgentRun、Message、Decision、结果、Project
-  Knowledge 引用、受管工作区记录、运行时绑定、mailbox、持久事件和配置。
-- Provider Session、transcript、进程、缓存、telemetry 和运行时观察服务于执行
-  与诊断，不替代持久的 Task 事实。
-- 数据库之外的配置和诊断不定义另一个存储版本，也不允许启发式地重建 Task 真相。
+SQLite 拥有 Task、WorkItem、AgentRun、Message、Decision、结果、Project
+Knowledge、工作区、运行绑定、mailbox、事件及配置。Provider Session、
+transcript、进程、缓存和 telemetry 服务于执行诊断，不替代持久 Task 真相。
+记录的 `schemaVersion` 仅校验当前格式，不构成独立升级轴。
+`storage_migration_archive` 保留不透明原始负载和二进制审计证据，
+不是旧格式读取器、调度器或缓存。
 
 ## 准入
 
-普通命令只有在同时满足以下条件时才打开 Home：
-
-1. `yui.db` 存在，且其迁移账本是一个有效的不可变前缀。
-2. 账本头恰好等于运行中 CLI 的当前存储版本。
-3. 当前记录校验与引用完整性均通过。
-
-落在 CLI 支持区间内的更旧 Home 无法通过普通准入，但被归类为可升级。
-`yui doctor` 和 `yui upgrade --dry-run` 会报告有序的升级路径而不改动 Home。
-显式的 `yui upgrade` 是唯一的独立变更边界：它让 Controller 静止、备份
-`yui.db`、以事务方式套用所有缺失迁移，并校验当前模型。更新的、低于最低版本的、
-不完整的或损坏的 Home 一律 fail closed。不存在运行时归一化、修复 worker、
-文件 Store 回退、双读写路径或第二套迁移权威。
-
-类型化领域记录在写入、普通读取、有界 Context 分页和全 Home 检查时，共用一份
-现行校验注册表。直接 Store 与 worker-backed Store 不存在不同强度的校验。
-无效写入不会推进 revision；已存在的无效记录只会报错并保留供明确诊断，
-不会被自动规范化成看似有效的替代记录。
-
-存储 35 新增仅由迁移写入的 `storage_migration_archive`：
-`migration_version / family / record_key / payload / content`。它保留退休的
-Project／gate 原始 payload 和二进制日志，不在当前模型中解释这些历史格式，
-也不是调度状态、第二份缓存或运行时回退。Task 内的历史 Integration 使用普通
-Task 事件保存。数据库备份同时保留当前记录与这份审计存档。
+普通打开要求精确的当前格式、版本、摘要、物理结构与类型化记录。
+非空 Home 缺少数据库或版本身份时拒绝初始化。新 Home 一次创建最终 DDL，
+不重放旧迁移。写入、普通读取、Context 分页及全 Home 诊断共享当前校验器；
+无效记录只报错，不规范化修复；失败写入不推进 revision。
+已打开的写连接在每次修改前重查它捕获的 Schema 身份。
 
 ## 写入与并发合同
 
-- 每次修改是一个 SQLite 事务。
-- WAL 加 `synchronous=FULL` 提供持久提交边界。
-- `home_meta.revision` 是全 Home 范围的 CAS/revision，供需要冻结
-  read/modify/write 边界的调用者使用。
-- 类型化列支持按身份和状态建索引查询；完整且经校验的记录负载仍是持久的领域表示。
-- mailbox 认领、精确的 AgentRun 终结、活动指针移除、结果持久化以及下游唤醒创建，
-  在它们构成同一条产品事实时以事务方式耦合。
-- 幂等键与唯一约束保护可重复的外部效果确认，不构成第二套工作流状态机。
+每次修改是 SQLite 事务，WAL 和 `synchronous=FULL` 保护持久提交。
+`home_meta.revision` 是 Home 范围的 CAS/revision，不是格式版本。
+索引列支持精确查询，完整且经过校验的负载仍是领域表示。
+mailbox 认领、精确 Run 终结、活动指针移除、结果持久化及下游通知，
+在构成同一产品事实时一并提交。幂等键和唯一约束保护外部效果，
+不另建规划协议。
 
 ## AgentRun 与 Session 边界
 
-AgentRun 是一次明确请求的执行。它记录相关的可见输入和原始结果，而不是隐藏的
-推理过程或完整工具轨迹。一个 Provider Session 可以包含多个 Run、普通原生对话
-和通知。原生对话和通知不会自动创建 Run。只有精确关联的原生终态才结算该 Run；
-WorkItem 与 Task 的验收权威仍归 Leader。
+AgentRun 记录显式执行请求、可见输入和原始结果，不记录隐藏推理。
+一个原生 Session 可以包含多个 Run 和普通对话。通知本身不创建 Run，
+只有精确原生证据才能结算；WorkItem、Task 的验收仍由 Agent 判断。
 
 ## 更新行为
 
-`yui update` 暂存一个确切的包，并要求那个暂存二进制把 Home 判定为当前、可迁移
-或受阻。随后它停止那个确切的 Controller、激活同一个包、在需要时运行暂存发行版
-的完整迁移链、校验已安装二进制与当前 Home，再启动替换后的 Controller。
+版本 API 返回 `"1.0"` 字符串，不用浮点数。默认 `upgrade/update`
+只接受同一存储主版本内完整且连续的小版本路径；初始基线尚无升级步骤。
+跨主版本和旧整数格式只由独立显式转换器处理，运行包没有回退。
+updater 先检查精确暂存包，再在维护锁内重查；未知所有权始终阻塞。
+
+独立旧 v37 转换、备份恢复、产物边界和冷启动流程见
+[存储基线 1.0](./storage-baseline.zh-CN.md)。
+
+## Home 布局
 
-每次持久 schema 或负载变更都追加一条不可变、连续的存储迁移。CLI 同时发布
-`storageVersion` 与 `minimumStorageVersion`；处在该闭区间内的每个有效 Home 都能
-直接升级到当前版本，无需安装中间发行版。当前版本及最低支持版本统一由
-`src/storage/storageVersions.ts` 声明，并由 CLI 身份读取暴露。
-低于该下限的 Home 不是迁移输入，保持原样不动。目标二进制的
-`upgrade --update-preflight` 与 `--update-apply` 结果形态，以及由父进程持有的
-交接锁证明，对从存储版本 1 起发布的每个 updater 都保持向后兼容，因此一个旧的
-源码 CLI 仍能驱动一个新得多的目标的完整迁移链。
+自管理数据位于规范 Home 内：Task worktree 在
+`workspaces/tasks/<task>/<owner>/<project>`，Global scratch 在
+`workspaces/global`，运行数据在 `runtime`，备份在 `backups`。
+显式外部 Project 保留外部资源语义；只有受限长度的 IPC socket 可位于 Home 外。
+一次性转换不搬迁工作区，也不改写 Git 身份。

package/docs/storage-baseline.md

@@ -0,0 +1,132 @@
+# Storage baseline 1.0
+
+Yui 1.0.0-alpha is the clean runtime baseline. Package version `1.0.0-alpha`, Home
+storage version `1.0`, record envelope version `1`, and Controller protocol `1`
+have different responsibilities. The later 1.0.0 package reuses the final
+verified prerelease storage contract; it must not reset it again. Persistent
+changes after the first alpha publication require explicit minor transitions.
+
+## Current runtime
+
+- `storage_schema` contains one authoritative identity: format, major, minor,
+  schema checksum and creation time. JSON APIs expose storage versions as
+  canonical strings such as `"1.0"`, not floating-point numbers.
+- New Homes execute the complete current DDL once. They do not replay the old
+  v1..v37 ledger. Ordinary reads validate the current identity, physical schema
+  and typed records; they never normalize data.
+- Explicit `upgrade` / `update` can apply only a complete, contiguous **minor**
+  path within one major. The initial 1.0 baseline has no minor steps.
+  Cross-major, downgrade, unknown and old integer formats fail before activation.
+  An exact package selector is not permission to cross a storage major.
+- Yui-owned record envelopes start at 1. Host control uses the distinct
+  `yui-agent-host-control/v1` identity, so it cannot accidentally adopt an old
+  `yui-agent-host/v1` producer. Context/Run/Host-event/Driver contracts already at
+  v1 remain there. External Provider protocols and package versions are unchanged.
+- Business revisions, authority epochs, IDs, event sequences, native data and
+  immutable Context resources are not schema versions. Never reset them.
+- `storage_migration_archive` is opaque audit evidence, not an executable
+  compatibility reader. Old numbers and original bytes in audit remain intact.
+- Candidates have one current authority: the owning WorkItem's candidate array.
+  The baseline does not create the unused `work_item_candidates` or
+  `coordination_locks` tables, or the obsolete `idx_input_open` index.
+
+The runtime tarball contains neither historical migration modules nor the
+standalone converter. Source-level history and previous published packages
+remain available for explicit diagnosis, not automatic runtime fallback.
+
+## One-time conversion from 0.16.2
+
+The independent `yui-baseline-cutover` archive accepts only the exact frozen
+0.16.2 schema and its complete v37 ledger. Older Homes must first use 0.16.2.
+Admission is based on this exact storage contract, not an installed package
+version: an already-valid v37 Home does not need a cosmetic rewrite.
+It never runs the old migration chain itself.
+
+The unpublished v37 → 1.0 transition preserves Runs with missing optional Snapshot
+references, including their original references and results. A retained record
+need not be ready to execute: missing evidence must not block Home conversion.
+The Leader/Operator can inspect and retire the affected Run; an explicit ordinary
+retry creates a new Run and Snapshot from current authorized facts without
+rewriting the old evidence. Exact Review/synthesis reuse still requires its
+frozen evidence. Unknown formats, structural corruption and unsettled external
+effects remain separate conversion blockers.
+
+1. Using 0.16.2, settle active Runs, Jobs, claimed notifications, in-flight
+   retries and unconfirmed effects. Preserve queued intent rather than marking
+   it completed. Stop managed Sessions and the Controller. `session stop --all`
+   refuses busy Sessions; it is not authority to force-stop or discard work.
+2. Stage the published 1.0.0-alpha package in a separate installation prefix, with
+   its native dependencies installed. Do not overwrite the global CLI or try to
+   run the new Controller against the old Home.
+3. Verify the converter archive checksum, unpack it, then use its entrypoint.
+   The examples below use **placeholders**, not a production Home:
+
+```sh
+node /absolute/converter/cli.mjs \
+  --home /absolute/home --runtime /absolute/staged/package
+
+node /absolute/converter/cli.mjs \
+  --home /absolute/home --runtime /absolute/staged/package \
+  --apply --backup-dir /absolute/new-backup-directory
+```
+
+`--runtime` names the package directory containing `package.json`, `dist/` and
+available dependencies, not its `bin/yui` entrypoint. The default invocation is
+read-only. `--apply` requires a new backup directory outside Home, under an
+existing canonical parent. Run from an external Operator shell, not a managed
+Task or a Session that is itself being converted.
+
+The tool refuses active durable execution, pending outbox operations, active
+Session bindings, recorded live processes, observable processes referencing
+this Home/database, pending native Inbox files and unfinished Controller
+handover/discovery. Unknown identity for a recorded owner remains a blocker;
+unrelated user processes are not adopted or terminated. Stop unmanaged writers
+and external workspace editors too; a file copy is not a filesystem snapshot.
+The maintenance fence and SQL write transaction protect the conversion.
+
+Before mutation, the tool copies Home and creates a self-contained SQLite
+backup with checksum. It converts only named Yui envelopes and active typed
+verification plans, preserving each changed payload and the original ledger in
+audit. User text, native payloads, frozen Context bytes, Git data, dirty files,
+IDs, counters and Task outcomes are preserved.
+Before dropping the two unused source tables, every original row is retained
+under `baseline-v37/retired-table/<table>` in the audit archive. Their payloads
+are opaque evidence, not active records to normalize. The receipt reports
+`retiredRows` separately from changed current records.
+
+Old `active-release.json` and `runtime-identity.json` are archived in
+`retired-runtime/`, not relabelled as observations of the new runtime. The tool
+also verifies and converts the typed isolation owner markers at the declared
+runtime inventory paths, retaining their originals and recomputing only the
+format-dependent fingerprint. Resource paths, namespace and port allocations
+do not change. Unknown markers or links remain blockers. The tool
+does not resume old Hosts, update the global installation, start a Controller,
+or submit model input. After a successful conversion, use the staged 1.0.0-alpha CLI
+to install the exact package and start only the new runtime. Start new managed
+Sessions through the ordinary explicit lifecycle; history is not live authority.
+
+## Evidence and recovery
+
+Success is `outcome: converted`, target `1.0`, with the exact backup path.
+Repeating against a valid current Home returns `already-current` without
+creating another backup or rewriting records.
+
+- `backup/home/` preserves the Home tree; `backup/yui.db` is the consistent
+  standalone database snapshot; `receipt.json` identifies source, target,
+  checksum and completed conversion. `retired-runtime/` preserves old bindings.
+- A validation failure rolls back the SQL transaction and restores runtime
+  bindings moved by that attempt. If restoration cannot be proven, the error
+  names the retained files; keep Home stopped.
+- A crash or receipt-write failure is not proof that storage stayed old.
+  Inspect the actual format and backup before choosing recovery. There is no
+  automatic repair worker or speculative replay.
+- To roll back, stop all new writers, preserve the failed/new Home separately,
+  and restore the old Home tree plus the standalone `yui.db` at the **same**
+  original Home path, without mixing in newer WAL/SHM files. Use only 0.16.2.
+  Review the converter-owned lock in the snapshot by exact process identity.
+- After new business writes, restoring the old backup loses those writes.
+  Recovery then needs an explicit disposition; never restore automatically.
+
+Real Home conversion and publication require separate user authorization.
+Isolated fixture evidence does not claim that a particular production Home is
+ready to convert.