diff --git a/docs/design/.npmignore b/docs/design/.npmignore new file mode 100644 index 0000000..0f75641 --- /dev/null +++ b/docs/design/.npmignore @@ -0,0 +1,2 @@ +# Human-review proposal; not an installed runtime document. +remote-qualification-checklist.md diff --git a/docs/design/remote-deployment.md b/docs/design/remote-deployment.md index 7e9a7b4..d43cd84 100644 --- a/docs/design/remote-deployment.md +++ b/docs/design/remote-deployment.md @@ -10,6 +10,13 @@ | Decision owner | Repository maintainer | | Supersedes | Nothing. The exact-version preflight stays in force until the follow-ups below are implemented and verified | +**Qualification follow-up (proposal, 2026-10-21):** +[Issue #158's checklist-first design](https://github.com/abruption/session-peer-ts/pull/159) proposes +an assessment workflow without a new authority or recovery engine. Draft #155 +is deferred and excluded from 0.5.0. The historical workflow and evidence below +remain context; the new proposal implements none of the F1–F6 follow-ups and +requires human design review before any replacement implementation. + ## Contents - [Context](#context) diff --git a/docs/design/remote-qualification-checklist.md b/docs/design/remote-qualification-checklist.md new file mode 100644 index 0000000..e93ae2f --- /dev/null +++ b/docs/design/remote-qualification-checklist.md @@ -0,0 +1,199 @@ +# Proposal: operator checklist for remote qualification + +Status: **Design only; human review required.** Issue [#158](https://github.com/abruption/session-peer-ts/issues/158), +following [#23](https://github.com/abruption/session-peer-ts/issues/23). +Draft date: 2026-10-21. No release version is assigned; priority is P2. + +## Purpose and boundary + +Help an operator assess one explicitly provisioned, exact-version TypeScript +installation using a small evidence worksheet. The result describes checks; +it neither activates an installation nor authorizes another action. + +The [remote deployment ADR](remote-deployment.md) remains a historical proposal +with dated experiments. This checklist does not implement its F1–F6 follow-ups +or adopt its journal, receipt, lock, activation or recovery machinery. The +2026-10-20 decision in #23 supersedes its earlier release planning: Draft #155 +is deferred and excluded from 0.5.0. Its commits and evidence remain historical; +they are not the implementation starting point for this proposal. + +Installation, rollout, repair, activation, rollback and retention belong to the +operator and the installation's owning manager. No manager takeover, installer, +runtime update, source-streaming fallback, distributed lock, caller accounting, +receipt ownership, recovery/resume protocol or automated cleanup is introduced. +No runtime, CLI flag, schema or program is proposed here. + +Existing exact-version SSH preflight, host-key checks, submission/unknown and +no-resend behavior remain requirements. Passing this checklist proves neither +message delivery nor ACK and grants no permission to switch callers, delete +files, break locks, publish receipts or clean up storage. Existing runtime +handoff and ACK contracts are outside this design. + +## Operator workflow + +1. Select the destination, account, installation path, owning manager and exact + intended local/remote version. Record the intended OS/architecture and runtime + cell. If selection or ownership is uncertain, record that uncertainty and stop + checks that depend on it; do not infer ownership from a marker or directory name. +2. Start a new worksheet with every check `not_checked`. Inspect only explicitly + selected metadata and record its source and observation time. Reading a file + never entails executing a discovered wrapper, Node, npm or agent executable. +3. Assess the static and operator-attestation checks below. Preserve missing and + conflicting evidence. Stop dependent checks on `fail`, `unknown` or + `unsupported`; remediation is a separate human decision. +4. If separately authorized, the operator may execute a specifically selected + existing bounded diagnostic, then record its exact command, scope and result. + Select the local CLI by its explicit absolute path. For a remote diagnostic, + include the selected absolute wrapper in `--remote-bin` and specify + `--remote-platform win32` for Windows, using paths accepted by the existing + CLI. Do not choose a default PATH-based invocation for this assessment. + Missing path/platform binding makes attribution to the selected installation + `unknown`, even if some same-version CLI returned success. An absolute path + is an invocation choice, not authentication or proof against later replacement. + Skipping that step leaves its check `not_checked`, without borrowing old results. +5. Review the individual results and evidence limits. Record unresolved cells and + the next human decision. End the assessment without changing the installation. + +This document grants no live experiment authorization. There is no default SSH +connection, registry request, executable discovery/run or agent contact. A future +diagnostic choice must name the destination, inputs, effects and stopping bound +before execution. `doctor --host` invokes SSH and the remote CLI; +`doctor --check-return-route` can initiate a return SSH probe. `send --dry-run` +means validation without submission, not a guarantee of zero writes, process +launches or network activity across its selected route. Diagnostic labels alone +do not establish an effect boundary; installed behavior and options need review. +No real send, ACK request or peer notification is part of this checklist. + +## Check states + +Each check is local to one assessment invocation and one stated predicate: +`not_checked` → `pass`, `fail`, `unknown` or `unsupported`. + +| State | Meaning | +| --- | --- | +| `not_checked` | No assessment of this predicate was attempted in this invocation, including a deliberately skipped diagnostic. | +| `pass` | Sufficient current evidence supports the precise predicate, using its recorded evidence kind and scope. | +| `fail` | Sufficient current evidence demonstrates the predicate is false, such as an established version mismatch. | +| `unknown` | Attempted assessment cannot establish the predicate: missing, unreadable, stale, ambiguous or conflicting evidence, including interrupted diagnostics. | +| `unsupported` | The selected check method cannot assess this platform/runtime/path case; record the specific limitation. This is neither a pass nor a compatibility claim. | + +An absent selected file is `fail` for “the selected file exists” but `unknown` +for “this installation uses the intended runtime.” A genuinely unsupported +runtime is `fail` for a supported-runtime requirement when established; it is +not hidden as an unsupported inspection method. Contradictory sources cannot +be resolved by choosing the favorable result. Record the conflict as `unknown` +unless authoritative scoped evidence establishes the predicate is false. + +A later inspection is a new observation, recorded alongside the earlier one; +it does not erase a contradiction without explaining its resolution. There is +no aggregate `pass`, automatic “qualified” designation or authorization token. +All checks passing still describes only their individual predicates and scopes. + +## Evidence worksheet + +Use ordinary text or a table; no machine format or persistence protocol is +required. For each check record the predicate, state, evidence kind, exact source, +observed time, destination/account/path and relevant version/runtime identity, +plus the result and limits. Keep sensitive command output out of shared notes. + +Distinguish these evidence kinds: + +- **Static metadata:** inspected artifact/version text, path, wrapper contents, + lockfile or computed hash. It proves only what was read at that time; it cannot + prove the actually running version, current caller use, storage ownership or + that a declared runtime path is the one a process uses. +- **Operator attestation:** a named operator's statement about manager ownership, + intended caller selection or a command result. Record when and where it was + observed and whether output is available; do not relabel it as executed evidence. +- **Executed diagnostic:** the exact command actually run in this invocation, + installed CLI/runtime version evidence, destination/account, time, exit status, + relevant result and observed limits. An observed banner identifies that command + invocation, not every process, caller or storage owner on the host. +- **Historical or synthetic evidence:** dated previous runs or fixtures, kept as + references, not replacement current results. An explicitly selected historical + digest may be an input to a new comparison predicate: record its source, path, + algorithm and original observation time, then measure the current input in this + assessment. The historical check's `pass` is never inherited. Without that + baseline identity or a current measurement, comparison is `unknown`. + Native destination execution must be identified separately + from fake SSH, local fixtures and CI. None supplies a skipped current check. + +Freshness is scoped to the observation, not a reusable time-to-live. A changed +artifact, runtime, destination, account, path, manager or invocation context +invalidates conclusions that depend on it; reinspect or record `unknown`. Record +both the declared identity and what was observed. Do not infer a source commit +from an equal version banner: current wire preflight checks the version line. +Combined conclusions depend on observations referring to the same installation +and context. A path can change between observations; repeat an applicable +inspection or state the continuity limit. No atomic snapshot is promised. + +Hash equality means matching computed digests under the recorded algorithm and +scope at the observation times. It is not an unconditional proof of byte identity. It authenticates no code and proves no current +use or ownership. A missing/uncomputed hash (`null`, if so transcribed) is unknown, +never “unchanged”; two null hashes are not a successful comparison. + +| Minimal check | Evidence sufficient for its limited predicate | +| --- | --- | +| Installation and manager are explicitly selected | Operator attestation naming destination/account/path and manager; uncertain ownership remains unknown. | +| Selected artifact metadata matches the intended version | Current static inspection of the named artifact; independently distinguish any executed banner result. | +| Declared runtime/path/native dependency match the intended cell | Explicit metadata inspection, with missing facts unknown; native loading and actual runtime selection require separately scoped executed evidence. | +| Current measured digest matches an explicitly selected baseline for a named file | Record baseline source/path/algorithm/time and a current measurement in this assessment. Matching digests do not prove continuous preservation between observations, current use or ownership. Missing either input is unknown. | +| Selected existing diagnostic returned the stated result | Actual authorized invocation/output with the explicit local CLI path, remote wrapper/platform where applicable, and selected agent scope. PATH-only results cannot establish attribution. `doctor` completion alone proves no readiness, native lock or send authorization. | +| Remaining destination cell has bounded native evidence | Exact dated OS/arch/account/runtime/package/native-check scope; no expansion to another cell or complete platform support. | + +## Remaining #23 work and evidence limits + +This is a classification of open work, not a new completion claim. “Live” below +means separately scoped native destination execution; none was run for this design. + +| Remaining criterion | Appropriate evidence/work | Current disposition | +| --- | --- | --- | +| Explicit same-version provisioning and supported absolute runtime/native dependency | Docs + static metadata + operator selection; live invocation/native load for actual execution | Preserve exact-version refusal. Source-build commit alignment is operator review, not wire enforcement. | +| Owning manager controls rollout/repair/rollback/retention; preserve Python/npm/uv/pipx installations | Docs + operator attestation; named before/after static measurements where needed | No new authority; a marker/hash cannot establish ownership or current callers. | +| Original #23 criterion: validate the selected workflow on isolated POSIX and Windows destinations | Separately scoped experiments after choosing the workflow and exact evidence cells | Remains open. Human review must decide how the checklist workflow addresses this criterion; no cell is completed here. | +| Linux requalification under the ADR's later receipt/recovery rules and operator-check → receipt → unlock order | Inventory the historical debt before selecting any live experiment | Human decision required: retain the named historical checks, rescope them to checklist qualification, or record why a criterion is no longer needed. This proposal neither silently drops the debt nor requires a recovery engine. | +| Windows destination matrix and other account/architecture/runtime/concurrency cells | Separate live experiment proposals per cell | Bounded historical evidence only; other cells remain unrun. | +| F2–F6 capability/error/identity/provisioning follow-ups | Separate design/implementation review and validation | Proposals, not commands delivered here. No Windows-client jump qualification. | + +Historical anchors remain dated: the 2026-10-02 Debian 13 x86_64/glibc 2.41 +run used published TS 0.2.1 and Node 24.21.0/22.23.3 under then-current ADR rules, with incomplete +operator ordering and later recovery rules unvalidated. The 2026-10-07 Windows +10 x64 administrator/PowerShell 5.1 run used published 0.3.1 and Node 24.16.0: +isolated offline installation, wrapper/native lock, operator SSH doctor and +nonexistent-target dry-run, plus 31 native storage/local-wrapper fixtures. Only +the primary installation had operator SSH evidence. Windows Node 22.23.3 +banner/native-lock smoke is separate from full installation qualification. +See the ADR's dated validation sections and their [validation records](../../VALIDATION.md). +CI/admin-only evidence and these checkpoints do not qualify complete platforms, +current installations, Windows-client jump, delivery or ACK. + +## Design acceptance scenarios (review only) + +These are bounded paper scenarios, not commands or tests to execute. + +| Scenario | Required checklist behavior | +| --- | --- | +| Operator reviews metadata and declines diagnostics | Static predicates may pass; skipped diagnostics stay `not_checked`; no connection or executable run. | +| Metadata version differs from the intended version | Version-match check fails; stop dependent diagnostics pending a human decision. | +| Wrapper metadata declares Node A; a command reports Node B | Record the declaration and observed command as separate predicates. Fail agreement only if runtime B is bound to the selected wrapper; an unrelated PATH Node does not establish a conflict or the selected runtime. | +| Hash cannot be read, or both recorded hashes are null | Comparison is unknown; never report unchanged or authorize deletion. | +| Inspection method cannot interpret the selected native path/platform | Relevant check is unsupported with its limit; unaffected check results remain recorded. | +| Authorized doctor exits 0 with `ready=false` | Completion may pass; the predicate “reported ready=true” fails for the recorded `--agent` selection. This flag is not installation integrity or proof of actual sendability, native locking, delivery or ACK. | +| Authorized diagnostic times out or returns an unparseable result | Record unknown and stop; do not infer completion, submission or permission to retry. | +| A remote command omits the selected wrapper path or Windows platform mode | Attribution is unknown; a same-version banner does not bind the selected installation. | +| An old digest is explicitly selected and compared with a current measurement | Record a new comparison result and both observations' scope; never inherit the old check's pass or claim preservation throughout the interval. | +| Old Windows success is offered for a different account/runtime or a current Linux cell | Keep the dated historical reference; current cell stays unassessed or unknown, according to whether assessment was attempted. | + +## Reporter decision and review gate + +Choose **checklist only** for this stage. There is no demonstrated need for a +reporter, and no implementation is authorized by this proposal. Revisit only if +operator use exposes repeated, concrete static transcription errors or effort +that a bounded regular-file inspection tool would materially reduce. That would +require a separate accepted design covering native paths, limits, explicit unknown +results and preservation of unaffected entries, without executing discovered tools. + +Human review must accept the workflow, evidence limits, state meanings and #23 +mapping before any implementation proposal. Any later implementation or live +experiment needs its own explicit scope and authorization. This review does not +close #23, accept #155 or commit work to a release.