dsh-completion-guard 0.8.1 → 0.8.3

package/docs/COMPATIBILITY.md

@@ -2,6 +2,50 @@
 
 Guard binds each accepted installation to its exact package identities, implementation bytes and dependency routes. Version admission and implementation qualification are separate checks; a matching version alone does not establish compatibility.
 
+## 0.8.2–0.8.3: DSH >=0.2.0-rc.2 and official Desktop
+
+0.8.3 retains the host admission and Desktop support introduced in 0.8.2. Each release still requires its own artifact acceptance.
+
+Version admission uses strict SemVer precedence, including later-tuple RCs and ignoring build metadata. The floor is `0.2.0-rc.2`, with no upper limit. `0.2.0-rc.1` keeps its recorded-evidence row but is refused as below the floor. Below-floor and malformed versions are refused. Cordis has a separate `>=4.0.4` peer range and qualification; a DSH version does not establish arbitrary Cordis compatibility.
+
+The reviewed host baseline is DSH `0.2.0-rc.2` / Cordis `4.0.4`, with 46 package identities and published implementation digests in `manifests/rc020-rc2-byte-audit.json`, regenerated from the published `0.2.0-rc.2` tarballs (upstream commit `639ed015397290b3745d163aafe02ffee4aa3f84`). Compared with rc.1, only six cohort packages carry real `lib` changes in rc.2 (`dsh`, `dsh-commands`, `dsh-goal`, `dsh-llm` typert tables; `dsh-tool-bash`/`dsh-tool-pwsh` tool descriptions); every other package differs only in its `package.json` dependency pins. Native acceptance of the final Guard artifact on each platform remains a separate gate; no native validation of a future host is claimed.
+
+### Official Desktop (CG-RC2-002)
+
+The application owns the `desktop` profile (`dsh-profile-desktop`). Its CLI carrier permits plugin management for that profile but refuses CLI boot and `--dump-config`. Use the carrier installed with the app for installation, and Guard's `dump-desktop` command for boot-free composition. See the [Desktop upgrade steps](HOST_LOCK_UPGRADE.md#official-desktop-profile).
+
+Guard identifies the profile by its manifest name. A Desktop profile contains the Web bundle, so bundle presence alone cannot identify the running surface. For macOS, Guard verifies the app's Developer ID signature and DeepSeek team/identifier; for Windows, it verifies the executable's Authenticode status and DeepSeek publisher. It then compares the ASAR header with the integrity value embedded in the signed carrier. A detached archive or a self-reported digest table cannot establish carrier identity.
+
+Desktop's bundled pnpm 11.7 produces a physical hoisted plugin tree with a JSON `.modules.yaml` index and no package map. Guard verifies the index against the actual tree, then applies the same published-byte and dependency-route checks to local critical peers. Missing, unlisted, duplicate, escaped or changed critical packages are refused. A supported package-map layout remains accepted when present; malformed maps never fall back to the physical-tree path.
+
+The archive is read in place. The registry baseline closes the executable/JSON inventory of each critical package, including scripts outside `lib`. Its bytes must match the acquired official tarball digests. The signed archive metadata authenticates the packager's rewritten manifests; executable files have no rewrite exception. Nested critical packages, unlisted code and changed dependency routes are refused. The same fresh route and byte audit also checks critical peers selected from the physical profile.
+
+The lock binds the canonical archive, signed header, runtime manifest and metadata, carrier bytes, installed Guard manifest, profile manifest, map and lockfile. Inject and runtime revalidation use one evaluation path, including foreground renderers and default-workdir providers. Changed inputs refuse the injected lock. Receipts stay under physical, contained profile directories; directory links cannot redirect them elsewhere.
+
+`hostLockProfile: "desktop"` is preserved through composition and readback. Guard refuses Desktop restart with `host_capability_request_unsupported`; the graphical app owns its lifecycle. Exact-artifact backend acceptance, graphical-shell acceptance and real-model behavior are separate gates. Their results belong to the matching Release annexes.
+
+### 0.8.2–0.8.3 中文说明
+
+0.8.3 保留 0.8.2 的宿主准入范围与 Desktop 支持；各版本仍须独立核对制品验收结果。
+
+0.8.2 延续 0.8.x 的任务、证书与数据协议，主要适配 DSH RC.2、增加 Desktop 宿主锁并修复退出证据判定。最低 DSH 版本升至 `0.2.0-rc.2`；请先升级宿主，再安装 Guard、重新注入锁并回读。版本准入没有上限，但版本号相符仍不足以证明实现兼容。Cordis 的独立要求为 `>=4.0.4`。
+
+Desktop 按应用自有的 `dsh-profile-desktop` 名称识别。安装须使用应用附带的 CLI；该 CLI 允许管理 Desktop 插件，但拒绝通过 CLI 启动 Desktop 或执行 `--dump-config`。Guard 的 `dump-desktop` 使用应用内同一套配置组合 API，不启动宿主。具体操作见[Desktop 升级步骤](HOST_LOCK_UPGRADE.md#official-desktop-profile)。
+
+Desktop 自带 pnpm 11.7 生成平铺插件目录，安装索引为 JSON 格式的 `.modules.yaml`，不含 package-map。Guard 核对索引与实际目录，再对本地关键 peer 执行相同的官方字节与依赖路由认证。关键包缺失、未登记、重复、越界或发生改写时均拒绝准入；若存在受支持的 package-map，则使用该布局，损坏的 map 不会回退到平铺目录路径。
+
+Guard 先核验 macOS 的 DeepSeek Developer ID 签名或 Windows 的 DeepSeek Authenticode 发布者，再将 ASAR 头与签名载体内的摘要比对。随后原位读取归档，按独立获取的官方 tarball 清单核验关键包内全部可执行/JSON 文件，包括 `lib` 外的脚本。签名归档的元数据只用于认证打包器改写的 manifest；新增代码、嵌套关键包、错误依赖路由及本地被改动的关键 peer 均拒绝。宿主锁同时绑定应用、载体、profile、安装映射与锁文件；注入和运行时复验采用同一链路，并核验 shell 渲染器及默认工作目录提供者。
+
+Desktop 应用重启仍由应用自行管理，Guard 不提供该能力。最终制品的后端生命周期、图形界面和真实模型验收分别记录在对应 Release annex 中。定时提醒及超时问题的晚到答案仍不授予根指令权限；退出标记被后续 prose 遮挡时，结果保持 `unknown`，不再误判成功。
+
+### RC.2 message sources (CG-RC2-004 / CG-RC2-005)
+
+RC.2 delivers scheduled reminders as `user/message` events with `source.kind === 'schedule'` and late answers to timed questions as `source.kind === 'user-question-reply'`. Neither is root user input: neither activates Guard, counts as real root input, creates work units, or is scanned for instructions. The authority for a schedule is the real user turn that created it, recorded in the durable log; the framing of a scheduled message (rc.2 renders it as "from the user") does not change that classification. A late answer belongs to its question/answer contract, never to a new instruction. Only `source.kind === 'user'` carries root authority, and unknown future source kinds fail closed the same way.
+
+### Consumer prerelease semantics
+
+The plain npm/node-semver expression `>=0.2.0-rc.2` excludes later-tuple prereleases by default. The installed DSH plugin compatibility check (`dsh-app-boot`'s `evaluatePluginCompatibility`) uses `semver.satisfies(..., { includePrerelease: true })`, so a `>=0.2.0-rc.2` peer declaration admits `0.2.1-rc.1` and later RCs on the same tuple, and refuses below-floor values. `benchmarks/incidents/acceptance/semver-matrix.json` records the verified matrix for the new floor. pnpm's peer helper behaves the same way; package installation is not a version-admission proof — Guard's own floor check rejects a below-floor host independently.
+
 ## 0.8.1: DSH >=0.2.0-rc.1
 
 Version admission uses strict SemVer precedence, including later-tuple RCs and ignoring build metadata. The floor is `0.2.0-rc.1`, with no upper limit. Below-floor and malformed versions are refused. Cordis has a separate `>=4.0.4` peer range and qualification; a DSH version does not establish arbitrary Cordis compatibility.
@@ -22,7 +66,7 @@ The plain npm/node-semver expression `>=0.2.0-rc.1` excludes later-tuple prerele
 
 0.8.0 metadata and its production selector accepted exactly `0.1.7-rc.2`, with Cordis `4.0.4`, cohort `dsh-0.1.7-rc.2-core-v1`, manifest `manifests/rc017-rc2-byte-audit.json`. That historical support scope is a property of the released 0.8.0 and is not rewritten by the 0.8.1 adaptation.
 
-Missing, duplicated, mixed, escaped or modified critical packages fail closed. A matching version or `allow-version` cannot bypass host identity. `auditedPlatforms: []` remains empty: local graph/module verification is separate from native acceptance of a frozen Guard tgz. See the [A01–A16 record](DSH_0_1_7_RC2_ACCEPTANCE.md).
+Missing, duplicated, mixed, escaped or modified critical packages fail closed. A matching version or `allow-version` cannot bypass host identity. `auditedPlatforms: []` remains empty: local graph/module verification is separate from native acceptance of a frozen Guard tgz. See the [A01–A16 record](https://github.com/GreenLv/dsh-completion-guard/blob/563f144bf8568793da5017b9ff71395a33dcd265/docs/DSH_0_1_7_RC2_ACCEPTANCE.md).
 
 Upgrade DSH first, install an accepted Guard artifact, rebuild the host lock and restart each profile. Goal is optional; neither Goal nor Inspector nor scheduling is assumed to be enabled. The 0.7.1 recovery fixes and independent proof, Goal and release gates remain in force.
 
@@ -148,7 +192,7 @@ managers therefore see the same two exact host releases as the host-lock
 registry; neither an unregistered stable release nor a future version is
 implicitly admitted.
 
-That historical artifact retained exact `0.1.5-rc.1` development pins. The current build pins DSH `0.2.0-rc.1` while public DSH peers declare the floor range. Historical peer declarations belong to their own release sections
+That historical artifact retained exact `0.1.5-rc.1` development pins. The current 0.8.3 build pins DSH `0.2.0-rc.2` while public DSH peers declare the floor range. Historical peer declarations belong to their own release sections
 above and are not part of the 0.5.2 contract.
 
 ## Terminal outcome contract

package/docs/HOST_LOCK_UPGRADE.md

@@ -1,8 +1,8 @@
 # Upgrading the core host lock
 
-Version 0.8.1 requires DSH `>=0.2.0-rc.1` and qualified Cordis `>=4.0.4`. Upgrade order and what each step produces:
+Version 0.8.3 requires DSH `>=0.2.0-rc.2` and qualified Cordis `>=4.0.4`. Upgrade order and what each step produces:
 
-1. Stop the host, upgrade DSH to `0.2.0-rc.1` or a later version, then install this Guard version.
+1. Stop the host, upgrade DSH to `0.2.0-rc.2` or a later version, then install this Guard version.
 2. Rebuild the host lock for each Guard profile by running `inspect`, `inject` and `verify-dump` from an accepted package or matching source checkout:
    `node bin/dsh-completion-guard-host-lock.mjs inject --runtime-root <DSH runtime> --profile-root <profile>` — then verify with `... verify-dump --dump-config <file>`. A successful rebuild reads back `supported` with `audit_provenance` stating how the graph was established.
 3. Start each Web/Headless profile when needed so it reads the rebuilt lock. The checks above do not require a running host.
@@ -10,11 +10,11 @@ Version 0.8.1 requires DSH `>=0.2.0-rc.1` and qualified Cordis `>=4.0.4`. Upgrad
 Failure readbacks distinguish these cases:
 
 - `host_lock_migration_required`: the configuration lacks the policy or source roots. Supply `--runtime-root` and `--profile-root` when rebuilding the lock.
-- `host_lock_version_below_minimum`: DSH is older than `0.2.0-rc.1`. Upgrade DSH first.
+- `host_lock_version_below_minimum`: DSH is older than `0.2.0-rc.2`. Upgrade DSH first.
 - `host_lock_version_mismatch`: the installed graph differs from the reviewed baseline in version or integrity. For a later compatible version, use `--rebind-registry` to acquire and qualify the published graph. For the baseline, restore the recorded identities.
 - `host_lock_installed_graph_drift`: installed bytes or routes changed after the audit. Inspect the change before rebuilding the lock.
 
-The floor is `>=0.2.0-rc.1` with no upper bound. Passing the version check does not establish native validation; validated versions are recorded separately. Guard's exact DSH core is separate from optional market versions.
+The floor is `>=0.2.0-rc.2` with no upper bound. Passing the version check does not establish native validation; validated versions are recorded separately. Guard's exact DSH core is separate from optional market versions.
 A normal market update no longer changes the core digest. A plugin that changes
 which core packages actually resolve still invalidates the lock.
 
@@ -66,7 +66,7 @@ profile remains a separate user action.
 
 A DSH Headless profile can have no external dependencies and no private `node_modules` or lockfile. From an accepted package or matching source checkout, `node bin/dsh-completion-guard-host-lock.mjs inspect-graph --runtime-root <runtime> --profile-root <profile>` checks that state without initializing or launching the profile.
 
-This narrow case requires exactly the installation-owned `dsh-base` and `dsh-headless` bundles, a complete audited runtime core, and matching bundle versions, package-map origins and patch files. Declared but uninstalled dependencies, partial map/lock pairs, unexplained local modules and foreign parent-module fallbacks are rejected. Existing profiles with both graph files retain their active-importer checks; damaged files are not treated as an empty graph.
+This narrow case requires the installation-owned `dsh-base` and `dsh-headless` bundles, with the RC.2 `dsh-web-app` bundle allowed between them, a complete audited runtime core, and matching bundle versions, package-map origins and patch files. Declared but uninstalled dependencies, partial map/lock pairs, unexplained local modules and foreign parent-module fallbacks are rejected. Existing profiles with both graph files retain their active-importer checks; damaged files are not treated as an empty graph.
 
 The result labels `inspection_scope: pre_install_target` and `profile_graph.state: dependency_free_headless`, with the manifest hash and bundle identities. Its package rows describe the verified runtime core used for this installation target, not a private profile importer or a live boot. After installing Guard, the `inspect`, `inject` and runtime replay checks still require the profile's package map, lockfile and installed plugin binding. This pre-install result cannot replace those checks.
 
@@ -81,7 +81,7 @@ certificate authority — completion certificates, mutation authorization,
 release pre-effect decisions and Goal/Stop boundaries — validates the lock
 freshly at the moment of its own decision.
 
-Version 0.8.1 registers `dsh-0.2.0-rc.1-core-v1` as the audited baseline cohort and derives graph cohorts for compatible hosts above the version floor (see the compatibility guide). Runtime checks authenticate the mapped files and verify that each critical dependency resolves to the mapped instance. Installation imports use native Node resolution; Profile imports use the host's local-first routing and installation fallback only when no local package is selected. A nearer shadow, missing edge, wrong export target or escaped path is rejected even when the recorded versions match.
+Version 0.8.3 registers `dsh-0.2.0-rc.2-core-v1` as the audited baseline cohort and derives graph cohorts for compatible hosts above the version floor (see the compatibility guide). Runtime checks authenticate the mapped files and verify that each critical dependency resolves to the mapped instance. Installation imports use native Node resolution; Profile imports use the host's local-first routing and installation fallback only when no local package is selected. A nearer shadow, missing edge, wrong export target or escaped path is rejected even when the recorded versions match.
 
 The manifest's `registry-derived-pending-native-audit` provenance and empty `auditedPlatforms` list describe its immutable source audit, which is part of the lock digest. Native acceptance belongs to each exact artifact's separate Release annexes; it does not rewrite that digest. Inspection, injection and dump verification report `audit_provenance` alongside the cohort and digest.
 
@@ -100,9 +100,31 @@ that matters for deciding whether you are migrating or just drifting:
   a DSH upgrade, and both are cured by re-running inspect, inject and verify against
   the new runtime rather than by editing the lock.
 
-Historical requirements and session records are retained; old certificates do not become certificates for the new lock. Historical host cohorts are test data only and are not accepted by 0.8.1.
+Historical requirements and session records are retained; old certificates do not become certificates for the new lock. Historical host cohorts are test data only and are not accepted by 0.8.3.
 The shared digest-v3 encoder and its upstream fixtures are unchanged.
 
+## Official Desktop profile
+
+Stop the Desktop app before installing or rebuilding its lock. Use the CLI carrier shipped with that app: `Contents/Resources/runtime/cli/bin/dsh` on macOS, or `resources\runtime\cli\bin\dsh.cmd` in the Windows installation. A separately installed `dsh` CLI cannot manage the reserved Desktop profile.
+
+Install Guard through that carrier with `plugin --profile desktop add dsh-completion-guard@0.8.3`. Use the profile's own host-lock tool and the app's physical `app.asar` as `--runtime-root`. The default profile is `$DSH_HOME/profiles/desktop`, or `.dsh/profiles/desktop` under the user's home when `DSH_HOME` is unset. This POSIX example starts after installation:
+
+```sh
+DSH_DESKTOP_ASAR=/absolute/path/to/DeepSeek-Harness.app/Contents/Resources/app.asar
+DSH_DESKTOP_PROFILE=/absolute/path/to/.dsh/profiles/desktop
+GUARD_DESKTOP_LOCK="$DSH_DESKTOP_PROFILE/node_modules/.bin/dsh-completion-guard-host-lock"
+"$GUARD_DESKTOP_LOCK" inspect --profile desktop --runtime-root "$DSH_DESKTOP_ASAR" --profile-root "$DSH_DESKTOP_PROFILE"
+"$GUARD_DESKTOP_LOCK" inject --profile desktop --runtime-root "$DSH_DESKTOP_ASAR" --profile-root "$DSH_DESKTOP_PROFILE"
+"$GUARD_DESKTOP_LOCK" dump-desktop --profile desktop --runtime-root "$DSH_DESKTOP_ASAR" --profile-root "$DSH_DESKTOP_PROFILE" > desktop-composed.yml
+"$GUARD_DESKTOP_LOCK" verify-dump --profile desktop --runtime-root "$DSH_DESKTOP_ASAR" --profile-root "$DSH_DESKTOP_PROFILE" --dump-config desktop-composed.yml
+```
+
+On Windows use the `.cmd` host-lock launcher and the installation's `resources\app.asar` path. `dump-desktop` authenticates the carrier and uses the app's bundled configuration APIs to compose the same bundle/profile/home layers, without starting a host. It writes the profile's empty loader anchor as the official dump API does. Preserve any composed output privately because user configuration may contain secrets; it is not a Release attachment.
+
+Check `supported` on inspect, inject and verify-dump. Keep Desktop stopped until all checks pass, then open the app when needed. Guard never edits the app archive or restarts the graphical app.
+
+Desktop 升级顺序相同：先停止应用并升级宿主，再用应用附带的 CLI 安装 Guard。普通外部 CLI 无法管理保留的 Desktop profile。以应用的 `app.asar` 和实际 Desktop profile 路径执行 `inspect`、`inject`、`dump-desktop`、`verify-dump`，确认三项 JSON 回读均为 `supported` 后再打开应用。`dump-desktop` 不启动宿主；配置输出可能包含私人信息，请留在本机。Guard 不修改应用归档，也不负责应用重启。
+
 ## Market and restart
 
 Core compatibility does not certify the optional market restart adapter.
@@ -132,7 +154,7 @@ exact artifact and platform; publication is recorded on its GitHub Release.
 
 ## Historical 0.5.1 evidence
 
-Version 0.5.1 registered DSH `0.1.5-rc.1` and `0.1.5-rc.2` with 33 critical packages. Its macOS and Windows results belong only to that artifact and those hosts; see the [0.5.1 release annexes](https://github.com/GreenLv/dsh-completion-guard/releases/tag/v0.5.1). These are historical records, not installation targets for 0.8.1.
+Version 0.5.1 registered DSH `0.1.5-rc.1` and `0.1.5-rc.2` with 33 critical packages. Its macOS and Windows results belong only to that artifact and those hosts; see the [0.5.1 release annexes](https://github.com/GreenLv/dsh-completion-guard/releases/tag/v0.5.1). These are historical records, not installation targets for 0.8.3.
 
 ## Rebinding compatible package versions
 

package/docs/LOCAL_ACCEPTANCE.md

@@ -1,8 +1,22 @@
 # Local Acceptance
 
+## 0.8.3 RC.2 and Desktop acceptance
+
+The candidate keeps the 0.8.x task, certificate and data protocols. Its host floor remains DSH `0.2.0-rc.2`; use the [upgrade guide](HOST_LOCK_UPGRADE.md) before establishing a new lock. The historical [RC.2/Desktop development plan](https://github.com/GreenLv/dsh-completion-guard/blob/563f144bf8568793da5017b9ff71395a33dcd265/docs/DEVELOPMENT_PLAN_DSH_0_2_0_RC2_DESKTOP.md) records the original adaptation scope; the current source, portability, exact-package, native, model and reader gates are defined below and in the repository instructions.
+
+Run the repository entrypoint twice for each native platform, always with the same frozen tgz and source commit. `host_bound_v070` covers Web/Headless. `desktop_bound` takes the physical app archive as `--runtime-root` and the exact DSH version as `--desktop-cohort`; it creates an isolated profile and uses the signed app's bundled CLI and actual Electron Node backend. Pass `--preflight` to each intended command before execution, with distinct unused external output and transfer-receipt paths.
+
+The Desktop backend annex uses `dsh-desktop-bound/v2`. It first installs Guard alone and immediately repeats that add: `single_package_strict_noop` requires byte equality for every tracked profile file and the frozen Guard tree. It then adds the inert update fixture and repeats the multi-package add: `multi_package_semantic_noop` permits only JSON object-key order changes in `node_modules/.modules.yaml`. Complete values, array order and types must remain equal; every other tracked file and the Guard tree still require byte equality. The supported metadata format is pnpm's two-space JSON serialization without a trailing newline; duplicate keys, YAML and other serialization formats fail closed. The producer never normalizes or restores metadata and never retries a failed gate.
+
+pnpm 11.7.0 builds hoisted-location mappings asynchronously and writes their insertion order, so multiple unchanged packages can flip object-key order. The v2 contract explicitly distinguishes that host serialization limit from Guard single-package byte stability. Historical `dsh-desktop-bound/v1` failures remain failures and are not upgraded by this new contract. `schemas/native-desktop-bound-v2.schema.json` and the read-only `scripts/validate_native_desktop.py` consumer bind the new gate set to the exact source, tgz, driver, platform and Desktop lock. The command is `python scripts/validate_native_desktop.py <annex> --artifact <frozen-tgz> --repo-root <clean-checkout> --expected-platform macos --desktop-host-lock-digest <readback-digest>` (use `windows` for that platform).
+
+The backend annex also covers carrier/graph authentication, installation parity, injection and real composed readback, loaded Guard behavior, graceful stop, uninstall and cleanup. It expressly skips `graphical_shell` and `real_model_request`. Those skips require separate GUI/model evidence before the complete Desktop release gate closes. Portable tests, source composition against a real archive and a backend annex cannot substitute for those observations.
+
+每个平台分别运行 Web/Headless 与 Desktop 原生入口，绑定同一份最终 tgz、源码提交及摘要。Desktop 使用 `--gate-profile desktop_bound --runtime-root <app.asar> --desktop-cohort 0.2.0-rc.2`，先加 `--preflight` 做同一次调用环境的能力预检，再去掉该参数执行。该入口在隔离 profile 中验证官方载体、安装字节、单包严格字节 no-op、多包 JSON 值等价、组合配置、实际加载与卸载，并输出独立 annex；它不启动图形界面、不请求真实模型，二者须单独补齐。具体结果留在对应制品的外部回执和 Release 附件，避免文档自引用造成制品身份变化。
+
 ## 0.8.0 rc.2 source-stage snapshot
 
-The [A01–A16 source-stage snapshot](DSH_0_1_7_RC2_ACCEPTANCE.md) records development checks before exact-artifact acceptance. Final CI, platform and model results belong to the matching artifact receipts and Release attachments. This source snapshot neither predicts those results nor transfers earlier acceptance to the changed rc.2 adapter.
+The [A01–A16 source-stage snapshot](https://github.com/GreenLv/dsh-completion-guard/blob/563f144bf8568793da5017b9ff71395a33dcd265/docs/DSH_0_1_7_RC2_ACCEPTANCE.md) records development checks before exact-artifact acceptance. Final CI, platform and model results belong to the matching artifact receipts and Release attachments. This source snapshot neither predicts those results nor transfers earlier acceptance to the changed rc.2 adapter.
 
 ## 0.7.1 recovery feedback patch (2026-09-22; source evidence)
 

package/docs/README.md

@@ -1,14 +1,21 @@
 # Documentation map
 
-Start with [architecture](ARCHITECTURE.md), [compatibility](COMPATIBILITY.md), [privacy](PRIVACY.md), and [host-lock upgrades](HOST_LOCK_UPGRADE.md). [Distribution](distribution.md) describes installation and package channels. [Local acceptance](LOCAL_ACCEPTANCE.md) records evidence for exact candidates; an older result does not certify new package bytes.
+For installation and upgrades, start with [host-lock upgrades](HOST_LOCK_UPGRADE.md) and [compatibility](COMPATIBILITY.md). [Distribution](distribution.md) lists package channels. [Local acceptance](LOCAL_ACCEPTANCE.md) distinguishes source checks, installed-artifact results and their limits.
 
-The [core alignment contract](CORE_ALIGNMENT_CONTRACT_V2.md), [semantic compatibility](SEMANTIC_COMPATIBILITY.md), [upstream base](UPSTREAM_BASE.md), and frozen conformance pin describe shared semantics and their limits. Keep the [0.7.0 development plan](DEVELOPMENT_PLAN_0_7_0.md) with its [plan review](CORE_ALIGNMENT_PLAN_REVIEW.json): these are the original planning snapshot, not a current execution queue or proof of release. Their original bytes remain unchanged.
-
-The current [rc.2 adaptation plan](DEVELOPMENT_PLAN_DSH_0_1_7_RC2.md), [planning evidence](dsh-0.1.7-rc.2-planning-evidence.json), and [A01–A16 status](DSH_0_1_7_RC2_ACCEPTANCE.md) distinguish source work from artifact and native gates.
+For maintenance, use [architecture](ARCHITECTURE.md), [privacy](PRIVACY.md), the [writer-lock protocol](WRITER_LOCK_PROTOCOL.md), and [historical incident coverage](HISTORICAL_INCIDENT_COVERAGE.md). The [core alignment contract](CORE_ALIGNMENT_CONTRACT_V2.md), [semantic compatibility](SEMANTIC_COMPATIBILITY.md), [upstream base](UPSTREAM_BASE.md), and [porting notes](PORTING_NOTES.md) explain shared semantics and product boundaries. [Third-party licenses](THIRD_PARTY_LICENSES.md) records attribution.
 
 ## Historical development material
 
-Completed pre-0.7 plans and one-time execution handoffs have been removed from the current documentation tree. Their exact original content remains available below; historical instructions do not authorize new operations.
+Completed development plans, one-time planning evidence and previous release-note drafts are retained at immutable Git revisions rather than shipped in the current package. Their original bytes remain available below; their pending statuses and instructions describe those historical candidates, not the current release.
+
+- [DEVELOPMENT_PLAN_0_7_0.md](https://github.com/GreenLv/dsh-completion-guard/blob/563f144bf8568793da5017b9ff71395a33dcd265/docs/DEVELOPMENT_PLAN_0_7_0.md)
+- [CORE_ALIGNMENT_PLAN_REVIEW.json](https://github.com/GreenLv/dsh-completion-guard/blob/563f144bf8568793da5017b9ff71395a33dcd265/docs/CORE_ALIGNMENT_PLAN_REVIEW.json)
+- [DEVELOPMENT_PLAN_DSH_0_1_7_RC2.md](https://github.com/GreenLv/dsh-completion-guard/blob/563f144bf8568793da5017b9ff71395a33dcd265/docs/DEVELOPMENT_PLAN_DSH_0_1_7_RC2.md)
+- [dsh-0.1.7-rc.2-planning-evidence.json](https://github.com/GreenLv/dsh-completion-guard/blob/563f144bf8568793da5017b9ff71395a33dcd265/docs/dsh-0.1.7-rc.2-planning-evidence.json)
+- [DSH_0_1_7_RC2_ACCEPTANCE.md](https://github.com/GreenLv/dsh-completion-guard/blob/563f144bf8568793da5017b9ff71395a33dcd265/docs/DSH_0_1_7_RC2_ACCEPTANCE.md)
+- [DEVELOPMENT_PLAN_DSH_0_2_0_RC2_DESKTOP.md](https://github.com/GreenLv/dsh-completion-guard/blob/563f144bf8568793da5017b9ff71395a33dcd265/docs/DEVELOPMENT_PLAN_DSH_0_2_0_RC2_DESKTOP.md)
+- [RELEASE_NOTES_0_7_1.md](https://github.com/GreenLv/dsh-completion-guard/blob/563f144bf8568793da5017b9ff71395a33dcd265/docs/RELEASE_NOTES_0_7_1.md)
+- [RELEASE_NOTES_0_8_2.md](https://github.com/GreenLv/dsh-completion-guard/blob/563f144bf8568793da5017b9ff71395a33dcd265/docs/RELEASE_NOTES_0_8_2.md)
 
 - [DEVELOPMENT_PLAN_0_6_2.md](https://github.com/GreenLv/dsh-completion-guard/blob/784b5452b0da366a351dff6490fa46eeed2839a9/docs/DEVELOPMENT_PLAN_0_6_2.md)
 - [RELEASE_PLAN_0_6_2.md](https://github.com/GreenLv/dsh-completion-guard/blob/784b5452b0da366a351dff6490fa46eeed2839a9/docs/RELEASE_PLAN_0_6_2.md)
@@ -17,6 +24,4 @@ Completed pre-0.7 plans and one-time execution handoffs have been removed from t
 - [EXECUTE_0_6_3_PROMPT.md](https://github.com/GreenLv/dsh-completion-guard/blob/784b5452b0da366a351dff6490fa46eeed2839a9/docs/EXECUTE_0_6_3_PROMPT.md)
 - [DEVELOPMENT_HANDOFF_0_6_3.json](https://github.com/GreenLv/dsh-completion-guard/blob/784b5452b0da366a351dff6490fa46eeed2839a9/docs/DEVELOPMENT_HANDOFF_0_6_3.json)
 
-The [0.6.3 contract revision](CONTRACT_REVISION_0_6_3.md), [bounded cross-end result contract](CROSS_END_RESULT_CONTRACT.md), porting notes and acceptance history remain because they explain compatibility and earlier evidence boundaries. They do not replace the current core contract.
-
-This cleanup changes source documentation for a future package. It does not alter the immutable published 0.7.0 artifact or its acceptance identity.
+The [0.6.3 contract revision](CONTRACT_REVISION_0_6_3.md), [cross-end result contract](CROSS_END_RESULT_CONTRACT.md), and versioned acceptance history remain because current compatibility references still depend on their definitions. Older acceptance does not certify new package bytes.

package/docs/WRITER_LOCK_PROTOCOL.md

@@ -0,0 +1,63 @@
+# Private-ledger writer lock
+
+This document describes the current 0.8.3 protocol (Revision 3.2). It replaces the generation, slot/intent and earlier arbitration designs recorded in Git history. Those earlier designs are not operational instructions.
+
+## Purpose and limits
+
+Only one writer may append to a ledger root at a time. A crashed same-host writer with a complete owner record must be recoverable. Unknown owners, foreign hosts and PIDs that cannot be proved dead are refused. Only ESRCH proves death; PID reuse can delay recovery but must not authorize eviction of a live process.
+
+The protocol targets local filesystems supporting exclusive creation, hard links, append and atomic same-directory rename. Its arbitration model assumes that one complete record write with O_APPEND is ordered with other appends, and a subsequent read observes that order. This is a filesystem assumption, not evidence of native Windows or macOS acceptance; those platforms must be validated separately. A filesystem without hard-link support cannot use this admission path.
+
+## Files and authority
+
+| File | Role |
+| --- | --- |
+| `.writer.lock` | Complete v2-shaped owner record; excludes older writers. |
+| `pending.<nonce>.json` | Unique preparation file; has no admission authority. |
+| `arbitration.log` | Ordered claim, release and eviction records; replay determines the current holder. |
+| `arbitration.log.compact` | Temporary replacement written by the current holder during compaction. |
+
+A record identifies its nonce, PID and hostname. Pending filenames are unique per attempt and are not reused by the protocol. The ledger contents and shared anchors remain separate from these coordination files.
+
+## Admission
+
+1. Inspect pending records. Delete only complete records whose creator is provably dead on this host. Leave live, foreign and unparseable pending files untouched; they do not block admission.
+2. Classify `.writer.lock`. Unknown, foreign or live owners refuse admission. Adopt a complete same-host dead record without modifying or deleting it. If no barrier exists, preparation and publication below are required.
+3. Replay the arbitration log. Refuse a live or foreign holder. For a provably dead holder, append an eviction naming that holder's nonce, then retry classification.
+4. If a barrier is needed, create a unique pending file with O_EXCL, write the complete owner record and fsync it. Publish it with `link(pending, .writer.lock)`. A successful link exposes the complete inode atomically; EEXIST loses publication and causes reclassification. Never publish an empty preparation file.
+5. Append a claim and read the log back. Enter only when replay identifies this attempt's nonce as holder. An unsuccessful claimant removes only its own published barrier after matching its nonce, and its own pending file. An adopted barrier stays untouched.
+
+The barrier and claim use the same nonce. No process automatically removes an observed dead barrier to make room for a replacement.
+
+## Replay and linearization
+
+Replay starts with no holder. A claim grants ownership only when the slot is empty. Release and eviction clear the holder only when their expected previous nonce matches the current holder. An eviction is submitted only after a same-host ESRCH check. A delayed eviction of D therefore cannot remove a later holder B.
+
+Under the append-order assumptions, a successful claim takes effect at its position in the log. Its readback confirms admission; it does not authorize replacing a live holder. Losing claims remain ineffective in that replay order.
+
+Unparseable lines are skipped. Appenders prepend a newline when the observed file does not end at a line boundary. The protocol never truncates the log during tail repair. The parser also accepts a complete final JSON record without a newline; incomplete pending files have no role in this replay.
+
+## Release and compaction
+
+Release appends a record naming the writer's own nonce. It then removes only a barrier it published itself, after matching that nonce, and removes its own pending filename. Adopted barriers remain.
+
+Above the record threshold, the current writer compacts immediately after verified admission, before returning the held lock. The replacement contains the current holder's baseline claim. Compaction occurs during that holder's tenure, not after release. Concurrent stale claims and evictions cannot change that live holder under the admission rules. Readers see either the preceding log or the replacement, with the same holder. Do not move compaction after barrier removal or replace the baseline with a released owner.
+
+## Crash recovery and older versions
+
+| Crash point or state | Subsequent behavior |
+| --- | --- |
+| Before pending write, or during partial write | Only an inert pending file remains; other writers can proceed. Unparseable leftovers remain on disk. |
+| Complete pending, before link | No barrier was published; a dead creator's complete pending record may be collected. |
+| After link, before claim | The barrier contains a complete dead owner; a later writer adopts it and claims the empty slot. |
+| After claim | A later writer adopts the barrier, evicts the provably dead log holder and retries admission. |
+| Old writer holds `.writer.lock` | The new writer refuses while its owner is live or unknown. |
+| New writer holds or adopts `.writer.lock` | Old writers fail exclusive creation and refuse. |
+
+An adopted dead barrier continues to exclude older writers after the new writer releases. Returning to the older protocol requires an explicit maintenance window: stop every Guard process using that ledger root, verify exclusive access, then remove the stale barrier. Never delete a lock in a running shared profile based on its age alone. Unknown locks left by older versions require the same controlled investigation; they are not automatically recovered.
+
+## Regression evidence
+
+The concurrency suite exercises simultaneous child processes, stale evictions, live-holder exclusion, compaction during tenure and both upgrade directions. Deterministic production-child checkpoints cover pending before write, partial write, before link and after link before claim. Each checkpoint checks live-creator safety, kills and waits for that process, then requires subsequent appends to recover with a continuous ledger chain.
+
+These tests establish the tested source behaviors. Candidate CI and native exact-artifact acceptance remain separate gates. No finite test suite constitutes a proof for arbitrary filesystems, external file mutation or power-loss durability.