@zq-silk/yui 0.16.1 → 1.0.0-alpha

package/docs/release-workflow.md

@@ -27,201 +27,54 @@ system sits behind `ReleaseWorkflowPorts`
 external ports exercise recovery without real GitHub, npm, git, Controller,
 or model effects.
 
-## Controller handover fix in 0.16.1
-
-The updater's stop and exact-identity restoration children now explicitly receive
-the parent updater's handover-lock owner identity. They no longer wait on their
-own parent's lock; unrelated callers remain fenced. Storage remains at version 37.
-
-An already-installed older updater, including 0.15.12 or 0.16.0, cannot gain this
-fix merely by staging the new package. If it reports `CONTROLLER_HANDOVER_TIMEOUT`
-before activation, inspect the original Controller and lock ownership. Once the
-failed updater has released its own lock and the original Controller is confirmed
-healthy, normally stop it with that installed release's `yui controller stop`,
-then retry `yui update`. This preserves managed Agent Sessions and retains the
-normal preflight, backup, migration and verification boundaries. Do not delete
-an active lock or force-kill a Controller to bypass the failure.
-
-## Pre-1.0 contract cleanup
-
-Version 0.16.0 retires runtime compatibility before the final
-1.0 baseline cutover. It does not reset storage numbering.
-Storage 27→28 normalizes only provable singleton Role dispatch dedupe keys;
-the old migration ledger, Messages, Task results and unconfirmed effects remain
-unchanged. Ordinary opens require storage 37. Existing Homes advance only through
-the explicit upgrade boundary; no runtime dual-reader is added.
-
-This is a breaking pre-1.0 change:
-
-- `message send` uses `--intent`; `--wake-policy` is no longer accepted by the
-  CLI or capability API. Draft edits preserve intent.
-- Internal command integrations implement `notifyMailboxChanged`; the Task-only
-  notification adapter has been removed with its callers updated.
-- ACP peers must report `configOptions`; there is no `modes`/`set_mode` path.
-- Release recovery requires a pinned Home and installation prefix. Unpinned
-  identities remain unknown, and incomplete handover locks remain fenced.
-- Development link/unlink requires the current registry. It does not discover
-  or adopt older NVM registrations or reconstruct orphan links.
-- GC no longer discovers retired deployment layouts or reconstructs removed
-  worktrees. Unsupported quarantine evidence is retained, never purged as if
-  it were a current move receipt.
-- `task activate` consumes an existing request; no request means no resource
-  adoption. Request creation, deferred admission and atomic workspace adoption
-  remain separate, using the same current boundary.
-- `task integration queue` and its state machine are removed. The Agent chooses
-  each WorkItem result's order and strategy and calls the atomic Integration
-  operations; exact checks, target CAS and completion obligations remain.
-
-Storage 28→29 preserves every former queue payload verbatim in a Task event
-`integration.queue-retired`, with its original queue ID, before dropping the
-active table. Event IDs advance past both the stored counter and existing
-history. This does not accept delivery, generate an Integration or replay work.
-Existing Integrations and Jobs stay intact. Inspect `task event list <task>`
-and the referenced WorkItem/Integration before deciding what remains to do;
-retiring the queue does not settle an unfinished Integration.
-
-Storage 29→30 retires Run-linked wakes into `wake.run-link-retired` Task events
-with the complete original payload. Current notification IDs, delivery status
-and references remain intact, using wake schema 2; Run termination no longer
-consumes notifications. Live Runs, owned retries and unresolved claims referring
-to a retiring wake block both preflight and migration. The migration does not
-stop execution or fabricate acceptance. Global Session sets use an explicit
-`providerBinding: null` when no controlled binding exists.
-
-Storage 30→31 makes every Review's scope explicit. Missing/null scope in a valid
-older WorkItem Review becomes `work-item`; Task-final candidate evidence and
-the old ledger are unchanged. New and retried Reviews always write their scope.
-
-Storage 31→32 removes WorkItem `historicalState` from the current record.
-Before removal, the entire original payload is preserved verbatim in a
-`work-item.execution-state-retired` Task event. Current status, scope, Candidates
-and execution groups are unchanged; no Run or acceptance is created. Unrecognized
-historical shapes fail without changing the record or advancing the ledger.
-
-Storage 32→33 retires the Leader rollout/budget settings and VerificationPlan
-rollout modes. Active plan bodies gain an explicit schema version; their checks
-remain unchanged, while retired Knowledge bodies are preserved. Integration
-records gain explicit `rerunChecks: false`, and shadow reuse counters are removed
-from cached artifacts. Original settings remain recoverable from the explicit
-upgrade backup. This is an approved behavior change, not an assertion that
-`record`, `reuse` and `enforce` meant the same thing.
-
-Admitted `running`/`validating` plan gates block preflight and migration; settle
-them with the old release first. No in-flight Job is relabelled under the new
-proof contract. That cutover's v3 verification-plan digest excluded older cache entries from
-automatic reuse without rewriting historical Job/Integration results or deleting
-their logs. Historical plan interpretation is frozen inside the migration
-directory so earlier migrations keep their original semantics.
-
-The current clean-candidate proof uses a v5 L2-only execution digest. Both local and
-Job-backed verification check candidate cleanliness, branch and exact HEAD
-before publishing reusable success; older cache identities cannot silently pass
-this boundary. Existing records/logs remain readable and admitted Jobs are not
-relabeled under a new digest. Settle old attempts with their matching contract,
-or explicitly abandon them before starting another operation.
-
-The L1 runner, selector and current plan/artifact type branches are removed.
-Storage 34→35 archives the original Project plan payloads and L1 artifacts/logs
-in `storage_migration_archive`, then adopts VerificationPlan schema 2 without L1.
-The archive is raw audit data, not an alternate execution reader or cache.
-Settled historical ChangeSet-source Integrations become full-payload Task Events;
-live workspaces, unsettled Jobs and adoption references block their retirement.
-The complete earlier migration ledger remains unchanged.
-
-Session custody now has one source, SQLite. Legacy `launch-env` owner rows or
-files in `runtime/session-owners` block this cutover: use the old release to
-inspect and settle their exact resources, then explicitly archive obsolete
-files outside the active Home. The migration does not kill, infer ownership,
-repair malformed records or rewrite immutable Session Manifests.
-
-Storage 35→36 preserves historical Agent errors and explicitly marks missing
-failure configuration as unavailable. Storage 36→37 narrows recorded failure
-context to native metadata-query inputs, preserving the original snapshot and
-empty optional identity placeholders in migration audit. Current error readers
-do not depend on the execution snapshot protocol or reconstruct missing history.
-Configuration rejection preserves input without automatic retry; an authorized
-Agent can inspect failure-scoped model capabilities, correct the intended
-configuration, and explicitly retry the rejected notification.
-
-`task turn` and the `yui-dev` completion identity are no longer supported.
-Before rollout, replace Sessions whose old Manifest still names `task turn`,
-and explicitly remove/archive old `yui-dev` completion blocks before installing
-current `yui` completion. User shell files are never rewritten by storage migration.
-Host control/event compatibility and updater handover safety remain unchanged.
-
-Storage 33→34 removes Message `wakePolicy` and activation `origin` from current
-records, preserving their original representations in audit Events. Historical
-save-only Messages become `intent: record`; other user/operator Messages without
-intent become `discuss`. Runtime readers never infer a missing stored intent.
-Editing record-only context does not wake the Leader. Completion reads actual
-pending message references, including an explicit handoff of previously saved context.
-
-Draft editing also preserves request identity: messages bound to submission,
-queue/steer or handoff requests cannot change body in place. Use a new Message
-and request ID; identical-body updates are no-ops. Unkeyed discussion edits
-honor pending/failed activation, while develop edits never start planning or
-create/retry activation. These are operation-boundary fixes, not a new storage
-format or a repair of previously edited historical content.
-
-An origin-less pending immediate Draft activation blocks preflight and migration,
-including on a stopped Task. Activate or cancel it explicitly with the old release
-first. An admitted current request needs no second origin gate: cancellation,
-planning deferral, execution state and exact Session authority remain enforced.
-Old origin metadata, including settled-request history, remains in
-`task.activation-origin-retired` Events; this never fabricates authorization.
-
-New `job start` calls require `--request-id`; RPC callers supply `requestId`, and
-the capability boundary supplies its invocation identity. There is no implicit
-content-addressed request or anonymous Job constructor. Existing Jobs retain
-their operation evidence and remain addressable by ID. Retrying the same explicit
-request is idempotent, changed input conflicts, and Integration recovery still
-finds its original Job across Session replacement. Choosing a new request ID is
-an explicit new operation, not recovery of an uncertain earlier result.
-
-Core Scheduler readers and persistence operations are required ports. A missing
-Session/event reader cannot be interpreted as empty evidence or skipped error
-persistence. Task execution and Web projections read the current store directly;
-queue admission requires its Task lifecycle read. Exact dispatch settlement
-remains separate and does not gain an archive gate that could lose late evidence.
-Observer, config, Knowledge and workspace-cleanup Store readers are also required;
-test doubles implement those contracts rather than selecting production fallbacks.
-
-Task listing and `/api/dashboard` now expose only the bounded catalog; remove
-`--view compact` from callers and use per-Task reads for detail. Scheduler
-catalog projections are required internal ports, not optional full-scan adapters.
-Extra `schema.json`/`state.json` files cannot override SQLite's version or be
-used to reset a development Home; upgrades leave unrelated files untouched.
-A missing database in a non-empty Home remains a refusal to initialize.
-Unrecognized writer leases are diagnosed without adoption or deletion.
-
-`controller status` always reports identity and retains the nonzero health exit
-for contradictory storage. `YUI_STATUS_IDENTITY` no longer selects another
-contract. Update-owned lifecycle capture uses the same resource collector
-directly, without requiring the old Home to pass current-schema health.
-
-Additional current boundaries:
-
-- Project/artifact file locks and handover locks require exact process-generation
-  evidence. Missing/invalid owners or unreadable OS identity remain fenced;
-  age alone never proves a creator exited. No PID-only positive fallback remains.
-- PR head lookup uses one `gh pr list --head ... --state open` query. Only an
-  empty, valid array proves absence. Transport errors, malformed identities and
-  multiple matches fail without attempting creation.
-- Existing Git operations cannot be adopted without the Integration's original
-  progress receipt. Preserve their files and diagnose explicitly; current
-  receipt-backed conflict/Job continuation remains supported.
-
-Before rollout, settle old executions and use explicit cleanup for unsupported
-locks, links or quarantines. Preserve those records until their owner and
-disposition are established; the runtime does not choose recovery for them.
-
-The later baseline cutover must first establish a verified bridge/export to the
-chosen current format, then replace the old initialization/migration chain with
-one clean baseline. Only then remove pre-baseline migrations and their historical
-fixtures. Reset the storage baseline once; do not reset it again when tagging
-1.0.0. Keep unknown-version rejection, exact process/Host identity checks and
-durable audit evidence. Version tags and real migration/publication effects
-require their separate release authorization.
+## Clean baseline release: 1.0.0-alpha
+
+0.16.2 remains the frozen historical bridge. The 1.0.0-alpha runtime starts the
+distinct storage **1.0** baseline and carries no old migration chain or
+conversion tool. Package 1.0.0 will reuse the final verified prerelease storage
+contract without another reset.
+
+Storage versions have two levels. Default updates may advance only contiguous
+minor versions within the same major; pinning a package does not authorize a
+cross-major conversion. Current Yui-owned envelopes and protocols start at 1,
+without resetting business revisions, epochs or audit evidence.
+Any persistent change after an alpha is published requires an explicit new
+minor transition; published schema definitions must not be silently replaced.
+Current bounded automatic recovery, lock waiting, transactions, replay
+protection and valid exact-identity caches remain normal runtime behavior.
+
+Use the exact package version `1.0.0-alpha` to opt into this baseline. Stable
+releases use npm `latest`; prereleases use `next`, never the stable default.
+
+The old-v37 converter is a separate archive. Its source/target verification,
+offline boundary, full backup, original-payload audit, cold startup and rollback
+are specified in [Storage baseline 1.0](./storage-baseline.md).
+Publish its archive and checksum as durable 1.0.0-alpha release attachments alongside
+the exact tested runtime package. Expiring CI artifacts alone are insufficient.
+The alpha-only `baseline-release` job runs after npm publication, uploads missing
+attachments to a draft without overwriting existing files, downloads and compares
+every attachment against the tested artifact, then publishes the prerelease.
+A retry verifies matching existing attachments; a different byte or an incomplete
+already-published Release is an error, not permission to replace release evidence.
+If this job fails after npm publication, resume only this job with the same
+retained artifacts rather than republishing or rebuilding the package.
+The runtime tarball must contain neither tools/ nor dist/storage/migrations/.
+
+Use `yui update --version <exact-version>` for an exact published package.
+Staged metadata must match the requested version, and target-owned storage
+preflight runs before activation and again under the maintenance fence.
+An unsupported Home remains unchanged; use the independent converter rather
+than replacing the global CLI first. Current update/activation children must
+explicitly identify their handover-lock owner.
+
+Restoration checks the captured executable/argv, package version, Controller
+protocol and both storage-version bounds against status and live identity.
+Missing contract fields are errors, not an older-Controller exception.
+
+The converter source, frozen endpoint fixture and converter-specific tests are
+release-only deliverables for 1.0.0-alpha. Remove them from the 1.0.0 development line
+only after the 1.0.0-alpha release attachments and checksums are durably available
+and verified. Do not delete the only conversion path before publication.
 
 ## Authorization model
 
@@ -270,7 +123,7 @@ Candidate and Task-final ReviewRound records must all carry that one contract.
 Conflicting records fail closed; there is no rebind event, recovery command, or
 second contract state machine.
 
-## Persistent Agent Host compatibility
+## Current Agent Host boundary
 
 A running Host keeps its original Endpoint implementation. It records exact
 Session/attempt/native-Turn facts in the existing durable Inbox before contacting
@@ -284,24 +137,27 @@ the long-lived Session environment. This preserves pre-adoption evidence even
 when the frozen Run workspace differs from the Role's default; later activity
 and terminal facts still resolve solely by their own native input identities.
 
-The supported Host boundary is control `yui-agent-host/v5`, event source
-`yui-agent-host-events/v1`, and Controller RPC version 4. Hosts advertising
-`storage=controller-owned` do not open the Home database, including for process
-custody, native account locations, or execution-environment checks. Home 22
-declares the additive Inbox source envelope; valid older Inbox v1 facts and
-domain history remain readable. Future changes must retain this wire boundary
-or reject incompatible live producers before changing storage. CLI wrapper
-refresh and a successful new `doctor` are not Host compatibility proofs.
-
-`upgrade`, the staged target's `update` preflight, and release activation inspect
-live Host capabilities independently. An old Host without this capability,
-including an idle Host or one whose response is unconfirmed, blocks adoption.
-Checks are repeated at the existing fenced/quiesced handover boundary before
-migration or promotion. No Host is killed, replaced, or reloaded by these checks.
-Let existing work settle and preserve original pending input/result evidence;
-then an authorized Operator can select a safe Session replacement/cleanup before
-retrying. Installing this change cannot repair already-loaded legacy Host code
-or collect a terminal that that code never durably emitted.
+The current Host boundary is control `yui-agent-host-control/v1`, event source
+`yui-agent-host-events/v1`, and Controller RPC version 1. Hosts do not open the
+Home database, including for process custody, native account locations, or
+execution-environment checks. Only the Controller owns storage and resolves
+durable facts; malformed current input fails at its normal protocol boundary.
+
+Breaking upgrades do not inherit historical Hosts or processes. Runtime startup,
+`upgrade`, `update`, and release activation no longer scan old Host sockets or
+processes, infer their capabilities, or negotiate a compatibility handoff. Use a
+clean runtime environment; this is not permission to discard pending work or
+kill resources of uncertain ownership. Current Controller restart, exact
+process-generation checks, handover locks, Session authority and event replay
+protection remain enforced.
+
+Storage upgrades are limited to the current major's explicit minor steps.
+Cross-major conversion is independently authorized and is not a runtime fallback.
+Session CLI refresh only retargets the current two-argument quoted wrapper
+named by a valid Manifest. It does not convert retired wrapper forms. Runtime
+diagnostics do not interpret `schema.json`, `state.json`, or a whole-map release
+idempotency file; current SQLite data and per-key release receipts remain the
+authorities, and unrelated files are left untouched.
 
 `task role status`, `task role list`, and `task role session inspect` expose Host
 reporting alongside durable Run state. Pending native results or known reporting

package/docs/release-workflow.zh-CN.md

@@ -20,150 +20,43 @@ Agent 选择一个预先声明的计划，设施从持久状态驱动该计划
 （`src/release/releaseWorkflowPorts.ts`）之后。可用临时 SQLite 和确定性的外部端口测试
 恢复逻辑，无需真实 GitHub、npm、git、Controller 或模型效果。
 
-## 0.16.1 的 Controller 交接修复
-
-升级器的停止与精确身份恢复子进程，现在显式接收父升级进程的交接锁归属身份，
-不再等待自己父进程持有的锁；无关调用仍被阻止。存储版本保持 37。
-
-已经安装的旧升级器（包括 0.15.12、0.16.0）不会因为暂存新包而提前获得此修复。
-若其在激活前报告 `CONTROLLER_HANDOVER_TIMEOUT`，先检查原 Controller 和锁的归属。
-确认失败的升级器已释放自己的锁、原 Controller 仍健康后，使用已安装版本的
-`yui controller stop` 正常停止 Controller，再重试 `yui update`。此操作保留受管
-Agent Session，仍完整执行预检、备份、迁移和验证；不要删除活动锁或强杀 Controller
-来绕过失败。
-
-## 1.0 前的契约清理
-
-版本 `0.16.0` 先清退运行时兼容分支，尚未执行最终 1.0 基线切换，也不重置
-存储编号。存储 `27→28` 只规范化可明确识别的单条 Role 调度去重键，旧迁移账本、
-Message、Task 结果和不确定外部效果保持不变。普通打开要求存储 37；已有 Home 只通过
-显式升级入口前进，不增加运行时双读。
-
-这是一次 1.0 前的破坏性变更：
-
-- `message send` 统一使用 `--intent`；CLI 与 capability API 不再接受 `--wake-policy`
-  或 `wakePolicy` 参数，Draft 编辑保留原提交意图。
-- 内部命令集成实现 `notifyMailboxChanged`；Task-only 通知适配器及其调用已统一。
-- ACP peer 必须回报 `configOptions`，不再走 `modes`／`set_mode` 路径。
-- Release 恢复要求精确 Home 与安装 prefix。缺少固定目标的效果保持 unknown，
-  身份不完整的 handover lock 保持围栏。
-- 开发 link/unlink 要求当前登记文件，不搜索或接管旧 NVM 登记，不重建孤立链接。
-- GC 不再发现旧 deployment 布局或重建已删除 worktree；不受支持的 quarantine
-  证据保留，不会被当成当前 move 回执清除。
-- `task activate` 只消费已有请求；没有请求就不采用资源。请求创建、延后准入和
-  原子工作区采用仍分开，并复用同一个现行执行边界。
-- 删除 `task integration queue` 及其状态机。Agent 选择每个 WorkItem 结果的顺序与
-  策略，逐项调用原子 Integration；保留精确检查、目标 CAS 和完成义务。
-
-存储 `28→29` 在删除活动队列表前，将每条旧 payload 原样保存在
-`integration.queue-retired` Task 事件中，并保留原队列 ID。事件编号越过已有计数器
-和历史最大 ID。此操作不验收交付、不生成 Integration、不重放工作；已有 Integration
-与 Job 保持不变。通过 `task event list <task>` 和引用的 WorkItem/Integration
-判断剩余工作；队列退役不代表未完成的 Integration 已结算。
-
-存储 `29→30` 将 Run-linked wake 的完整原文移入 `wake.run-link-retired` Task 事件。
-现有通知保留 ID、投递状态和引用，使用 wake schema 2；Run 终态不再消费通知。
-引用待退役 wake 的活动 Run、受管重试或未决 claim 会同时阻止预检和迁移；
-迁移不停止执行、不编造接受。Global Session 没有受控 binding 时统一显式保存
-`providerBinding: null`。
-
-存储 `30→31` 将 Review scope 统一为显式值：有效旧 WorkItem Review 的缺失／null
-scope 转为 `work-item`，Task-final 候选证据和原迁移账本不变。新建和重试均显式写入 scope。
-
-存储 `31→32` 从当前 WorkItem 移除 `historicalState`，移除前将完整原始 payload
-原样保存在 `work-item.execution-state-retired` Task 事件。当前状态、工作范围、
-Candidate 和执行组不变，不生成 Run 或验收。未知历史形态会报错，记录和迁移账本不前进。
-
-存储 `32→33` 清退 Leader 过渡／预算配置以及 VerificationPlan 的模式。
-活动计划显式补上 schema 版本，实际检查保持不变；已退役 Knowledge 原文保留。
-Integration 显式补入 `rerunChecks: false`，缓存 Artifact 移除试运行复用计数。
-原配置可从显式升级备份恢复。这是已确认的行为变更，不将三种旧模式声称为等价。
-
-已接纳且仍为 `running/validating` 的计划验证会阻止预检和迁移，需先用旧版本完成
-结算；不会把运行中的 Job 改标为新证据契约。该次切换使用 v3 验证摘要，使更早缓存不再被
-自动复用，不重写历史 Job／Integration 结果或删除其日志。旧计划解析冻结在迁移
-目录中，早期迁移保持原有语义。
-
-现行干净候选证明采用 v5 L2-only 执行摘要。Job 和本地验证都在发布可复用成功前，
-检查候选工作区的干净状态、分支和精确 HEAD；旧缓存身份不能绕过这一边界。
-旧记录和日志保持可读，已接纳 Job 不会被改标为新摘要。应先按原契约结算旧尝试，
-或明确放弃后再开始新操作。
-
-L1 执行入口、选择器及当前计划／artifact 类型分支已移除。存储 `34→35` 将
-原始 Project 计划、L1 artifact 与日志保存在 `storage_migration_archive`，
-当前计划改为不含 L1 的 schema 2。存档只是原始审计数据，不是执行 reader 或缓存。
-已结算的旧 ChangeSet-source Integration 转为完整 payload 的 Task 事件；
-仍有工作区、未结算 Job 或 adoption 引用时阻止退休。旧迁移账本不变。
-
-Session 归属统一使用 SQLite。旧 `launch-env` owner 行或 `runtime/session-owners`
-中的文件会阻止切换：先使用旧版本检查并释放精确资源，再明确将旧文件归档到
-活动 Home 之外。迁移不杀进程、不推断归属、不修复损坏数据，也不重写不可变 Manifest。
-
-存储 `35→36` 保留历史 Agent 错误，并将缺失的失败配置明确标为不可用。
-存储 `36→37` 将已记录的失败上下文缩小为原生元数据查询所需输入，原始快照和
-空的可选身份占位值保存在迁移审计中。当前错误读取不依赖执行快照协议，也不
-重建缺失历史。配置拒绝保留原始输入但不自动重试；有权限的 Agent 可查询该次
-失败的模型能力、修正原本要求的配置，再显式重试被拒绝的通知。
-
-不再支持 `task turn` 和 `yui-dev` 补全身份。上线前应替换仍依赖 `task turn`
-Manifest 的 Session；明确卸载／归档旧 `yui-dev` 补全块后，再安装现行 `yui` 补全。
-存储迁移不会修改用户 shell 文件。Host 控制／事件兼容与 updater 交接安全检查保持不变。
-
-存储 `33→34` 从当前记录移除 Message `wakePolicy` 与激活 `origin`，原始表达
-保存在审计事件。旧的仅记录消息转换为 `intent: record`，其他缺少意图的
-user/operator 消息转换为 `discuss`；运行时不再解释缺失的持久化意图。
-编辑仅记录内容不会唤醒 Leader。完成检查读取实际待投递消息引用，也涵盖显式交接
-此前仅保存的内容。
-
-Draft 编辑同时保护请求身份：已经绑定 submission、queue/steer 或交接请求的消息
-不能原地改正文，需新建消息并使用新请求 ID；相同正文更新为无操作。未绑定请求
-身份的讨论编辑仍遵守 pending/failed 激活状态，develop 编辑不启动规划或创建／
-重试激活。这是操作边界修复，不改变存储格式，也不猜测修复过去已被编辑的原文。
-
-Draft 中缺少 origin 且仍 pending 的旧 immediate 激活请求会阻止预检和迁移，即使 Task
-已停止执行。必须先用旧版本显式激活或取消；升级不替用户做这个决定。当前已接纳
-请求不再经过第二次来源门槛，但取消、planning 延后、执行状态与精确 Session 权限
-仍需检查。旧来源及 settled 请求历史保留在 `task.activation-origin-retired` 事件。
-
-新 `job start` 必须带 `--request-id`；RPC 必须提供 `requestId`，capability
-入口使用 invocation 身份。不再从命令内容隐式生成请求，也不再构造匿名 Job。
-已有 Job 的操作证据和按 ID 读取保持不变；相同请求重试防重、不同输入冲突，
-Integration 在 Session 替换后仍找回原 Job。新 request ID 表示明确的新操作，
-不是对旧未知结果的自动重放。
-
-Scheduler 核心读取和持久化操作成为必需接口，缺少 Session／Event 读取不再被当作
-空证据，也不能跳过错误持久化。执行及 Web 投影直接读取当前 Store；
-消息入队必须读取 Task 生命周期。精确投递结算仍独立，不增加会丢失迟到证据的归档门槛。
-Observer、配置、Knowledge 与工作区清理所需 Store 读取也成为必需接口；
-测试替身实现现行合同，不再令生产代码降级。
-
-Task 列表及 `/api/dashboard` 只保留有界目录；调用方去掉 `--view compact`，
-详情使用单 Task 读取。Scheduler 目录索引是必需接口，不再兼容缺失时的全量扫描。
-额外 `schema.json`／`state.json` 不覆盖 SQLite 版本，也不用于开发 Home reset；
-升级保留无关文件。非空 Home 缺少数据库时仍拒绝初始化。
-不认识的 writer lease 明确诊断，不接管、不删除。
-
-`controller status` 固定输出身份信息，存储矛盾仍返回非零健康退出码；
-`YUI_STATUS_IDENTITY` 不再选择另一套契约。升级侧直接复用资源采集器读取生命周期，
-无需让旧 Home 先通过当前 schema 的健康校验。
-
-现行边界进一步收敛：
-
-- Project／Artifact 文件锁及 handover lock 要求精确进程代际证据。owner 缺失、
-  格式不完整或 OS 身份不可读时保持围栏；仅凭年龄不能证明创建者退出，不再用
-  PID-only 存活判断代替身份确认。
-- PR head 查询只调用 `gh pr list --head ... --state open`。仅有效空数组证明不存在；
-  传输失败、身份格式错误和多个匹配都不允许继续创建。
-- 已有 Git 操作缺少原 Integration 进度回执时不再被接管。保留文件并明确诊断；
-  有精确回执的正常冲突／Job 续作仍受支持。
-
-发布前应先收敛旧执行，对不受支持的锁、链接和隔离资源做显式清理。归属与处置尚未
-确定时保留原记录，运行时不替 Agent 选择恢复方案。
-
-后续基线切换必须先验证到目标格式的桥接或导出，再用一个干净基线替换旧初始化和迁移链，
-之后才能删除基线之前的迁移及历史夹具。存储基线只重置一次，不在发布 `1.0.0` 时再次
-重置。未知版本拒绝、精确进程／Host 身份检查与持久审计证据仍应保留。版本 tag、真实
-Home 迁移和发布效果需要各自的发布授权。
+## 纯净基线版本：1.0.0-alpha
+
+0.16.2 保留为冻结历史桥接版。1.0.0-alpha 运行包启用独立的存储 **1.0**，
+不携带旧迁移链或一次性转换工具；之后的 1.0.0 复用最终已验证的预发布存储契约，
+不再重置。
+
+存储采用主版本、小版本两级编号，默认更新只允许同主版本内连续的小版本升级。
+指定软件版本不代表授权跨存储主版本。当前 Yui 自有格式和协议从 1 开始，
+但不重置业务 revision、epoch 或审计证据。
+alpha 发布后如需改变持久化契约，必须声明新的小版本迁移，不能静默改写
+已发布基线。有界自动恢复、锁等待、事务、重放保护和精确身份匹配的有效缓存
+都是当前运行能力，不作为历史兼容删除。
+
+使用精确软件版本 `1.0.0-alpha` 主动选择新基线。正式版使用 npm `latest`，
+预发布版使用 `next`，不能覆盖默认稳定版本。
+
+恢复 Controller 时，status 和 live identity 都必须匹配此前捕获的执行文件、
+参数、软件版本、Controller 协议和存储版本上下界。缺少字段直接报错，
+不再为较早的 Controller 放宽校验。
+
+旧 v37 转换器独立分发；来源与目标校验、离线边界、完整备份、原始负载审计、
+冷启动和回滚见[存储基线 1.0](./storage-baseline.zh-CN.md)。
+发布时将转换包及校验和作为 1.0.0-alpha 的长期附件，与确切测试过的运行包一同保留；
+不能只依赖会过期的 CI artifact。运行 tarball 不得包含 tools/ 或旧迁移目录。
+alpha 专用 `baseline-release` 在 npm 发布成功后向草稿上传缺少的附件，不覆盖
+已有文件；逐个下载并与经过测试的产物比较后，才公开预发布 Release。
+重试只接受字节一致的已有附件；字节不同或已公开 Release 缺少附件都明确失败，
+不自动覆盖发布证据。若 npm 已发布而此步骤失败，只用同一批保留产物重跑该
+job，不重新构建或再次发布 npm 包。
+
+转换器源码、冻结终点样本及专用测试只服务于 1.0.0-alpha 的独立交付。
+必须先确认 1.0.0-alpha 长期发布附件和校验和可取得且验证通过，才能在 1.0.0
+开发线上移除它们；不能在发布前删掉唯一转换入口。
+
+`yui update --version <exact-version>` 选择精确发布包，实际暂存版本必须匹配。
+激活前及维护锁内分别执行目标包的存储预检。不支持的 Home 保持不变，应使用
+独立转换工具，不能先覆盖全局 CLI。当前交接子进程必须显式提供锁持有者身份。
 
 ## 授权模型
 
@@ -204,7 +97,7 @@ Session 使用普通的 `yui` 命令，兼容性由协议和存储身份检查
 Task-final 的 ReviewRound 记录必须全部携带那唯一的合同。冲突的记录 fail closed；
 不存在重新绑定事件、恢复命令或第二套合同状态机。
 
-## 常驻 Agent Host 升级兼容
+## 当前 Agent Host 边界
 
 存活 Host 保持原 Endpoint 实现，先把准确的 Session/attempt/nativeTurn 事实写入现有
 持久 Inbox，再联系 Controller。只有当前 Controller 解析 Run 归属、校验权限、工作区、
@@ -215,18 +108,21 @@ ACK 不会重放用户输入或模型工作。
 环境。即使冻结的 Run 工作区不同于 Role 默认值，登记前的证据也能保留；后续活动和
 终态仍只按各自的原生输入身份解析归属。
 
-支持边界为控制协议 `yui-agent-host/v5`、事件来源协议 `yui-agent-host-events/v1`、
-Controller RPC 版本 4。声明 `storage=controller-owned` 的 Host 不打开 Home 数据库，
-包括进程归属、原生账号位置和执行环境校验。Home 22 声明 Inbox 的新增来源字段，
-不改写有效历史事实与业务记录。后续版本要么保留该线协议，要么在修改存储前拒绝不兼容
-的存活生产者。刷新 Session CLI wrapper 或新 `doctor` 成功都不能证明旧 Host 兼容。
-
-`upgrade`、`update` 的目标版本预检及 release activation 独立检查存活 Host。
-没有此能力的 legacy Host（包括 idle）以及兼容响应不确定的 Host 都阻止采用；
-在既有隔离/静默交接边界再次检查，先于迁移或发布切换。检查不会 kill、替换或 reload
-Host。先让原有工作结束并保留原始未决输入/结果证据，再由获授权的 Operator 在安全
-边界选择 Session 替换或清理，之后重试。安装新代码不能修改已加载的 legacy Host 内存，
-也不能回收它从未持久投递过的终态。
+当前边界为控制协议 `yui-agent-host-control/v1`、事件来源协议 `yui-agent-host-events/v1`、
+Controller RPC 版本 1。Host 不打开 Home 数据库，包括进程归属、原生账号位置和
+执行环境校验。只有 Controller 拥有存储并解析持久事实；非法当前输入在正常协议
+边界得到明确错误。
+
+破坏性升级不承接历史 Host 或进程。启动、`upgrade`、`update` 和 release activation
+不再扫描旧 Host socket／进程、推断旧能力或协商兼容交接。使用干净的运行时环境；
+这不授权丢弃未决工作或终止归属不确定的资源。当前 Controller 正常重启、准确进程
+代际校验、交接锁、Session 权限与事件防重放继续生效。
+
+存储升级仅包含同主版本内明确的小版本步骤。跨主版本转换独立授权，
+不构成运行时回退。
+Session CLI 刷新只重定位有效 Manifest 指向的当前双参数引号 wrapper，不转换
+退役形态。运行时诊断不解释 `schema.json`、`state.json` 或整表 release 幂等文件；
+当前 SQLite 与逐 key release 回执仍是权威，无关文件保持原样。
 
 `task role status`、`task role list` 和 `task role session inspect` 在持久 Run 状态旁
 显示 Host 上报观测。原生结果待落库或已知上报故障需要关注，但不代表 Provider 失败、

package/docs/roles-and-configuration.md

@@ -136,6 +136,36 @@ requests for the same scope share the active probe, including refresh requests;
 once it settles, an explicit refresh probes again. Retained results are labelled
 as cached rather than as a new live response. No cleanup timer or worker is added.
 
+Catalog `source` describes the metadata query: `live` is a successful current
+query, `cache` reuses an identity-matched observation, and `fallback` has no
+usable native observation. It does **not** confirm every configuration field.
+The same catalog can combine native model/help enumeration, local profile names,
+and declared static adapter inputs. Field `reason` and catalog `warnings` identify
+these boundaries; `available: false` marks an unavailable native enumeration or
+capability, not permission to guess values. `allowCustom` permits explicit input,
+not a promise of Provider acceptance.
+
+Missing or unparseable help enums stay empty. Known static contracts (such as
+Yui's permission strategies and supported configuration syntax) remain available
+with an explicit static label; they are not described as server-discovered options.
+The permission picker never supplies its own list when a field is absent, and
+retains an existing value as an explicitly unreported current setting. A query
+does not change configuration, permissions, model, or account.
+
+Cache responses retain the original `fetchedAt`, last probe `attemptedAt`, field
+reasons, warnings, and any failed refresh's error. Identity matching is not a
+freshness guarantee: native files, account entitlements and remote policy may
+change, so use explicit refresh when needed. The discovery contract is part of
+cache identity; older derived caches that could contain guessed help values are
+not reused by this contract. Durable Home schemas and migration history are
+unchanged.
+
+Doctor inspects installation and help only, using the same declared fields and
+enum parser. Its field counts distinguish help-observed, static/unverified, and
+unavailable fields; it does not enumerate account models. The retained minimum
+versions and latest offline producer evidence have different meanings; see
+the source repository's `docs/provider-protocol-contracts.md`.
+
 On Role creation, explicit Agent settings require `--agent`. On update, omitted
 `--agent` targets the active binding; a named binding is updated without being
 activated. `task role bind` changes selection. A live Session requires the

package/docs/roles-and-configuration.zh-CN.md

@@ -110,6 +110,26 @@ yui task role session new <task> <role> --reason "<why a fresh Session is useful
 正在进行的查询，结束后显式刷新才重新查询。缓存命中标为缓存，不冒充新的实时响应。
 这不增加清理定时器或后台 worker。
 
+目录的 `source` 描述元数据查询来源：`live` 是本次查询成功，`cache` 是复用身份
+匹配的历史观测，`fallback` 表示没有可用原生观测；它不表示每个配置字段都已获
+原生确认。同一目录可同时包含原生模型／help 枚举、本地 profile 名称及明确声明的
+adapter 静态输入合同。字段 `reason` 和目录 `warnings` 说明这些边界；
+`available: false` 表示原生枚举或能力不可用，不允许据此猜测值；`allowCustom`
+只允许显式输入，不承诺 Provider 会接受。
+
+help 枚举缺失或解析失败时保持为空。Yui 权限策略、支持的配置语法等确定静态合同
+仍可使用，但明确标为静态，不冒充服务端枚举。权限选择器不再为缺失字段自行补列表；
+已有设置可作为“本次目录未报告的当前值”保留。查询不修改配置、权限、模型或账号。
+
+缓存返回保留原始 `fetchedAt`、最后一次查询的 `attemptedAt`、字段说明、警告和刷新
+失败原因。身份匹配不等于实时有效：原生文件、账户权限、远端策略仍可能变化，需要时
+显式刷新。发现合同也参与缓存身份，因此可能包含猜测 help 值的旧派生缓存不再复用；
+Home 持久 schema 与迁移历史不变。
+
+Doctor 只检查安装和 help，复用相同静态字段和枚举解析，分别统计 help 已观测、
+静态／未确认、不可用字段，不枚举账户模型。保留的最低支持版本与最新离线生产者
+证据含义不同，详见源仓库的 `docs/provider-protocol-contracts.md`。
+
 创建 Role 时，显式的 Agent 设置需要 `--agent`。更新时，省略 `--agent` 针对活动
 绑定；一个具名绑定会被更新但不被激活。`task role bind` 更改选择。在更改期望设置
 之前，活动 Session 需要该命令的显式确认。