docs(protocol): document DIG_NODE_FORWARD_ON_MISS forwarded-ask gate

[MichaelTaylor3d]

Summary

• Documents DIG_NODE_FORWARD_ON_MISS, the default-OFF forwarded-ask gate shipped in dig-node v0.128.0 (PR #258), in docs/protocol/peer-network.md's redirect-on-miss section (§9a), alongside the existing DIG_NODE_ON_MISS=fetch setting.
• Same addition mirrored across all 13 locale copies (i18n/*/docusaurus-plugin-content-docs/current/protocol/peer-network.md) — 14 files total.
• Facts verified directly against dig-node's crates/dig-node-core/src/download.rs (forward_on_miss_enabled/resolve_forward_on_miss) and crates/dig-node-core/src/seams/dig_peer/forwarded_ask.rs (FORWARDED_ASK_FANOUT), not taken from the ticket alone:
  • Default OFF; unset/empty/any value other than on/1/true/yes (case-insensitive) fails closed — a typo cannot enable it.
  • On a miss with it enabled, the node also asks its connected pool peers.
  • One admitted 64 KiB frame at redirect_depth: 0 can fan out to roughly 1,360 outbound dials and 1,360 DHT walks (16 → 64 → 256 → 1024 fan-out, relay token 1:4).
  • Enabling it discloses to every recruited peer what content you're looking for, not just the one peer you originally asked.

Blast radius checked

Docs-only change, no code touched. Impact scoped to:

• docs/protocol/peer-network.md (source) — one bullet inserted after the existing FETCH-THROUGH bullet in §9a.
• 13 i18n mirrors of the same file, same insertion point.
• No other page references DIG_NODE_ON_MISS/FORWARD_ON_MISS (grepped docs/ + SPEC.md).
• static/openrpc*.json were regenerated by npm run build as a build-time side effect and reverted — out of scope for this change.

Test plan

• npm run build — full Docusaurus build, all 13 locales + source built successfully (exit 0), verified dist/<locale>/docs/protocol/peer-network/ exists for every one of the 13 locales plus the English source.
• git diff --stat shows a bounded +6 lines per file across 14 files (84 insertions, 0 deletions) — no CRLF/whole-file rewrite.
• No internal ticket numbers, SYSTEM.md/CLAUDE.md references, or "we decided" commentary in the added prose (§4.3).

Closes #75
Related epic: https://github.com/DIG-Network/dig_ecosystem/issues/3128

🤖 Generated with Claude Code

[MichaelTaylor3d]

PASS — single correctness gate (docs-only, behaviour-preserving)

Head reviewed: ed8af39e814ac3cf45d41b29d52b9e23fc49d620 (resolved from gh pr view 76 --json headRefOid, matches the dispatched SHA).

Gate tier: one correctness leg, per the change being documentation-only with no code touched.

1. Every documented fact verified against dig-node's source (not the ticket)

Claim in the doc	Source	Verdict
accepted set is exactly on/1/true/yes, case-insensitive	download.rs:246-251 — matches!(v.map(|s| s.trim().to_ascii_lowercase()).as_deref(), Some("on") | Some("1") | Some("true") | Some("yes"))	correct
unset / empty / unrecognised fails closed	same — an allowlist matches!, so fail-closed is structural, not a branch that could be inverted	correct
default OFF	download.rs:239-240, gated at the call site download.rs:1154	correct
on a miss it also asks connected pool peers, merged into the redirect	download.rs:1147-1154 + seams/dig_peer/forwarded_ask.rs	correct
~1,300+ dials/DHT walks per admitted 64 KiB frame at redirect_depth: 0	forwarded_ask.rs:57-71 — 1:4 token ratio, 16 → 64 → 256 → 1024 = 1,360	correct, see §2

The two facts flagged as most damaging if wrong are the two that hold most firmly. The accepted-value set matches character for character, and fail-closed is guaranteed by construction rather than asserted — there is no "unrecognised" branch to get wrong, because anything outside the allowlist falls through matches!.

The upstream test is not vacuous. download.rs:2403-2434 (the_forwarded_ask_is_off_unless_explicitly_enabled) exercises the allowlist in both directions — seven truthy spellings including ON and " True ", six falsy inputs including None, "" and "off" — plus two standalone assertions for the two properties that matter (None is OFF; "enable" fails closed). Reverting the resolver to a permissive default would fail it. The property is named, not just the outcome.

2. The number does not understate

Source says "roughly 1,360" and shows its own arithmetic (16+64+256+1024). The doc's "on the order of 1,300+" is a true lower bound below the source figure, so an operator sizing capacity off this page is not given an optimistic number. The source's own warning — that quoting the 4^4 = 256 leaf count understates by ~5x — is exactly the mistake the doc avoids.

3. §4.3 compliance — clean, line by line

No SYSTEM.md / CLAUDE.md / internal-file reference, no ticket number, no agent or process detail, no "we decided", no drift narration. The rationale sentences ("which is why the setting defaults off") state a property of the system in positive normative voice rather than recounting a decision. Self-contained and authoritative.

4. Mirrors genuinely identical; no CRLF flip

All 14 added blocks hash identically (md5 over the + lines of each file's diff: f4a24702424d9e358635bac6c6bdb257 × 14) — byte-identical, no subtle divergence. git diff --stat and git diff --ignore-cr-at-eol --stat both report 14 files changed, 84 insertions(+), so there is no whole-file line-ending rewrite hiding behind the stat.

5. No build artifacts, no scratch files

git diff --name-only returns exactly the 14 markdown files. static/openrpc*.json, dist/ and .docusaurus/ appear nowhere in the diff.

The two reported-and-unfiled items

Locale staleness — acceptable, not misleading. Not blocking. The 13 mirrors are indeed stale (i18n/de/... has zero occurrences of PROXY, and lacks the newer "An operator-level setting" wording). I checked the insertion context rather than assuming: in the mirrors the new bullet lands after FETCH-THROUGH instead of after PROXY, and it reads coherently there — it does not reference PROXY, so it introduces no dangling cross-reference and no internal contradiction. A synchronized bullet on a stale base leaves those pages less stale than before, and the alternative (withholding the amplification and disclosure warning from 13 locales until a full retranslation lands) is strictly worse for the operator who reads one of them. The pre-existing drift is a separate, larger unit of work and is out of this PR's radius.

npm run build regenerating static/openrpc*.json — does not contaminate this PR. The regenerated files were reverted and the diff carries none of them. The build's nondeterminism is a real repo annoyance but it is out of radius and left no residue here.

Non-gating notes (posted inline, resolved by me so they do not bar merge)

Two cosmetic/precision observations, neither worth a round-trip. Details on the inline threads.

[MichaelTaylor3d]

Version bump: 0.16.0 → 0.16.1 (patch). Type is docs, no behaviour change, no capability added — patch per the §2.4 SemVer table. Only version file in this repo is package.json (no Cargo.toml). HEAD is now fb0cb81.

Check version increment confirmed SUCCESS by name via check-merge-preconditions.sh; build + a11y/SEO tests still IN_PROGRESS on this commit, will confirm once it returns. Staying DRAFT.

[MichaelTaylor3d]

All three required checks now SUCCESS by name (Lint commit messages, Check version increment, build + a11y/SEO tests), mergeStateStatus=CLEAN, 0 unresolved threads. HEAD fb0cb81. Staying DRAFT for merge.