[ViscaOwO]

Closes #300

What was wrong

The 0.3.1 and 0.3.2 release notes both headed their asset table Target | SHA-256, but the column meant different bytes: 0.3.1 listed the worker digest (89b8e1e9… for win32-x64 — the value the archive's runtime/win32-x64/provenance.json records) while 0.3.2 listed the ZIP digest (10e29a8f…, equal to the GitHub asset digest). Checked against both release bodies and both asset lists; all three targets drifted the same way, so it is a changed convention rather than a typo.

A reader following the table literally gets a false result in either direction: compare the 0.3.1 value against the ZIP and the archive looks corrupted; compare the 0.3.2 value against the worker and a healthy install fails its own check. 0.3.1 has no npm channel to fall back on (registry.npmjs.org/dsh-ops/0.3.1 → 404) and carried no SHA256SUMS asset, so those notes were its only record.

Since 0.4.0 the artifact shape changed (main tarball + Windows Bash payload + SHA256SUMS; no runtime ZIPs and no digest table in the body), so the table itself is gone. What remained is the gap that produced it: nothing said what a published checksum refers to, or where its authority lives. That is why this PR does not rename a column — it states the contract and gives readers a command that resolves the question on their own machine.

The change

• docs/release-process.md: one bilingual pair in the existing lead blockquote stating the contract — the SHA256SUMS asset is authoritative for released tarballs, each tarball records its worker digest in runtime/<target>/provenance.json, and the Release body defines neither. The run summary is only a copy; releases from a maintainer machine have no run summary and did not always carry SHA256SUMS, so their record is the in-package receipt. Every published checksum must name its object.
• docs/troubleshooting.md + docs/常见问题.md: a new "how do I verify what I downloaded" section with the checker that needs no platform-specific hashing tool — tar -xzf dsh-ops-<version>.tgz, then node package/bin/native-runtime.mjs check --root package --platform <target>. It records the three traps found while testing it: SHA256SUMS lists every tarball of the release, so sha256sum -c needs all of them side by side; macOS has no sha256sum; and Git for Windows' GNU tar reads a C:\... argument as a remote host.
• docs/PROVENANCE.md: the 0.3.1 section now records the worker-vs-ZIP mismatch instead of leaving it silent.
• docs/CHANGELOG.md: one [Unreleased] entry, EN + ZH.
• test/docs-facts.test.mjs: asserts the contract is stated and that the checker the docs recommend still exists. The matched fragments appear only in the new text — SHA256SUMS alone already occurred as a build artifact, so matching that word would have stayed green on a revert.

Deliberately not done: release.yml is untouched (its publish job runs only when github.ref_type == 'tag', so a notes/asset comparison there could not be exercised by a dry run); no second checksum manifest (the per-target receipt already ships inside the tarball); pack.js / check.js untouched. docs/release-0.3.1.md and the published Release bodies are left as they were; the correction is recorded in docs/PROVENANCE.md, which is how this repository has handled notes-only Releases before, and rewriting a published release is not reviewable.

Validation

Behavior-level red/green: the four fragments the new assertions match are absent from main's versions of the three documents (checked with git show HEAD:<file>), so reverting the change turns docs-facts red; with the change it passes.

The documented command was exercised against the real v0.4.1 asset before being written down:

$ tar -xzf dsh-ops-0.4.1.tgz
$ node package/bin/native-runtime.mjs check --root package --platform win32-x64
win32-x64: 3855872 bytes, sha256 163723991a85b8990e94a620243194edcb6e54906cc0cf8d75ce4309e56953fb
Validated 1 native runtime(s); no install-time scripts or permission changes.

$ node test/run.mjs docs-facts
dsh-ops docs-facts: all 5 checks passed

$ node scripts/validate-manifest.mjs
validate-manifest: all 73 checks passed

$ node scripts/check-file-size.mjs
check-file-size: 385 code file(s) checked, all at or under 1000 lines (longest: bench/setup/profile.mjs (924))

$ npm run verify
dsh-ops test: 5 of 127 suite(s) failed, 50 skipped in 146s

The five failures are environment gaps in this checkout, not regressions: no pinned Bash payload (bash-ipc), no staged native worker (bundle-startup, discovery's host-loop suite, presentation-readiness, resident-tools), and no dsh-TUI checkout. That is the same five-suite set recorded against unmodified main in #336. The 50 skips are the worker-absence skips this environment cannot avoid (staging the worker needs Rust 1.97.1), so this local run is not gate-equivalent — CI required is.

$ gh run view 39600288518 --json url,event,conclusion --jq '"\(.url) \(.event) \(.conclusion)"'
https://github.com/T-Auto/dsh-ops/actions/runs/39600288518 pull_request success

CI required is an aggregate job that starts only after the matrix legs report, so its URL appears after the per-platform checks; the Windows leg is non-blocking since #316 and the gate is validate-posix.

Environment

Windows 11 x64, Node v24.13.0, npm 11.6.2, base ef7f8d6. Existing checkout; the optional @dsh-ops/[email protected] payload is absent, which is what the bash-ipc failure above reports.