Follow-up: spec doc updates for PR #4005 (FROST shadow mode, HKDF+CSPRNG, opaque DKG handle, error taxonomy)

[piotr-roslaniec]

Context

PR #4005 (multi-agent review report at agent-docs/reviews/pr-4005/report.md) applies 7 in-scope decisions that change the contract the spec documents describe. The spec docs need a coordinated update after the implementation lands.

Spec docs to update

1. docs/roast-coordinator-seed-derivation.md (Decision 2)

• Replace the Go-port description with the new HKDF+CSPRNG derivation:
  ShuffleKey_i64 = HKDF-SHA256(salt="FROST-ROAST-COORDINATOR-V1", ikm=AttemptSeed32 || AttemptNumberLE)
• Bump the documented COORDINATOR_SHUFFLE_VERSION to 0x02.
• Update the normative-derivation section to match the new implementation.
• Drop the "mirror" framing; the implementation is no longer a Go mirror.

2. docs/roast-phase-5-security-rollout-gates.md (Decision 1)

• Add a "FROST shadow mode" section:
  • Mode values: advisory_only (default), internal_canary, production.
  • When each mode is appropriate: production only after audit + TEE + proof-carrying-blame.
  • Operator procedure for transitioning modes.
• Update the testnet canary section to reflect the shadow-mode posture.

3. docs/phase-7-interactive-session-spec-freeze.md §4 (Decision 5)

• Extend the "no secret material transits the Go/Rust interface" claim to cover DKG via the opaque DkgSessionHandle.
• Document the new dkg_session_run / dkg_session_advance FFI surface.
• Document the consumption-marker pattern for DKG sessions.

4. docs/roast-phase-0-spec-freeze.md §8 (Phase 0 error taxonomy addendum)

• Add consumed_nonce_replay (Phase 7 §4) and interactive_attempt_already_aggregated (Phase 7 §5) to the Phase 0 error taxonomy.
• Add wallet_deadline_exceeded (Decision 8) as a new terminal error class.
• Add interactive_rate_limit_exceeded and interactive_round1_rate_limit_exceeded (Decision 7) as policy-rejection codes.
• Add frost_shadow_mode_advisory audit signal (Decision 1).

5. docs/permissioned-signer-hardening-rfc.md P0-M3 (Decision 7)

• Extend the rate-limit specification to cover InteractiveSessionOpen and InteractiveRound1 per-(sender, key_group) and cross-operator caps.

6. README.md (doc drift)

• Remove "Current scope" mentions of RunDKG, StartSignRound, FinalizeSignRound — these were removed from the codebase.
• Update ABI version to 4.0 (matches TBTC_SIGNER_ABI_MAJOR in pkg/tbtc/signer/src/lib.rs).

Acceptance criteria

• All 6 spec docs updated and cross-referenced.
• A diff summary: what changed in each doc, which decision it implements.
• The phase-0-spec-freeze.md §8 addendum is published as a separate ADR-style note (docs/adr/) so the spec-freeze can be amended via the standard ADR process.
• The README updates are committed to the same branch as the implementation work (i.e., folded into PR feat(tbtc/signer): Rust FROST/ROAST signer (distributed DKG, interactive-only signing, FFI ABI 2.0) #4005).

Related

• PR feat(tbtc/signer): Rust FROST/ROAST signer (distributed DKG, interactive-only signing, FFI ABI 2.0) #4005 gap-inventory: agent-docs/gap-inventory.md Decision 1, 2, 5, 7, 8
• Multi-agent review report: agent-docs/reviews/pr-4005/raw/contrarian.md, spec-compliance-A.md

[linear]

ENG-748