Spec: Complete the high-impact cleanup chain

[AustinKelsay]

Problem Statement

The staging branch is green, but nine concentrated maintenance risks still make sensitive diagnostics unsafe, leak test tooling into the published type surface, fragment logging and protocol implementations, complicate lifecycle correctness, slow the default feedback loop, couple tests to private shapes, and leave a large testing utility internally monolithic. These risks compound: the duplicated NIP-46 stacks make redaction and test speed harder, direct console usage prevents consistent diagnostic policy, and private-shape tests make safe refactoring unnecessarily expensive.

Solution

Deliver nine independently verifiable cleanup slices in impact-first order. Each slice uses its own branch and non-draft pull request into staging; staging is updated between slices so every later branch starts from the latest integrated baseline. Preserve the 0.x public API while creating deeper internal modules, one canonical diagnostic policy, explicit lifecycle behavior, public-seam tests, and a faster routine test lane. No release or production promotion is included.

User Stories

1. As a library consumer, I want NIP-46 connection secrets and decrypted payloads excluded from diagnostics, so that enabling logs cannot expose signing authority.
2. As a maintainer, I want redaction behavior covered at public diagnostic seams, so that future changes cannot silently reintroduce secret leakage.
3. As a TypeScript consumer, I want the published declarations to typecheck without Jest installed, so that test tooling does not become an accidental runtime contract.
4. As a test author, I want test-only relay helpers available from the dedicated testing entrypoint, so that production types remain focused.
5. As an integrator, I want Relay, RelayPool, and stateless protocol helpers to use the shared logger, so that one policy controls diagnostic output.
6. As an existing 0.x consumer, I want warning and error behavior to remain compatible while diagnostics move behind the shared seam.
7. As a wallet-service operator, I want initialization to be idempotent and concurrent-safe, so that repeated setup cannot create duplicate subscriptions.
8. As a wallet-service operator, I want a disconnected service to initialize cleanly again, so that lifecycle recovery is predictable.
9. As a zap client consumer, I want both public facades to share one internal implementation, so that cache, filter, and statistics behavior cannot drift.
10. As a zap client consumer, I want explicit limit values preserved, including zero, so that filter construction honors caller intent.
11. As a remote-signing consumer, I want simple and advanced NIP-46 APIs to retain their public behavior while sharing protocol machinery, so that fixes apply consistently.
12. As a maintainer, I want request correlation, encryption, timeout, and lifecycle behavior owned once, so that the NIP-46 implementations stop diverging.
13. As a contributor, I want the routine test loop to finish substantially faster, so that small changes receive prompt feedback.
14. As a release owner, I want slower security and performance coverage retained in an explicit lane, so that speed does not remove assurance.
15. As a refactorer, I want behavioral tests to use owned public seams, so that internal reorganizations do not trigger unrelated test rewrites.
16. As a testing-entrypoint consumer, I want the ephemeral Relay API to stay small and compatible, so that its internal split is non-breaking.
17. As a maintainer, I want connection, session, and filter-matching responsibilities separated internally, so that the ephemeral Relay utility is easier to reason about and change.
18. As a project owner, I want every slice reviewed, verified, and merged into staging before the next begins, so that the repository stays continuously releasable.

Implementation Decisions

• Execute the work as nine serial Feature Dev runs, one approved cleanup item per branch and pull request.
• Start every branch from the latest integrated staging; use a linear blocker chain to make the integration order explicit.
• Preserve existing public 0.x exports and facade classes unless the slice explicitly removes an accidental test-only declaration dependency.
• Make the shared core logger the canonical diagnostic seam while retaining compatibility aliases required by the existing diagnostics ADR.
• Redact by diagnostic field/policy rather than scattered call-site string manipulation.
• Move test-only ownership to the existing testing entrypoint.
• Model wallet service lifecycle explicitly enough to make concurrent initialization, repeated initialization, disconnect, and restart deterministic.
• Consolidate NIP-57 behavior behind one internal implementation while retaining both public adapters.
• Consolidate NIP-46 only after diagnostic redaction is established, so the deeper engine inherits the safe policy.
• Improve test speed by removing avoidable wall-clock waits and separating genuinely slow coverage explicitly, without weakening CI assurance.
• Replace private-shape testing incrementally with behavior observed at the highest owned public seam.
• Split the ephemeral Relay internally only; do not broaden its testing entrypoint contract.
• Grok 4.5 is the exclusive delegated sidecar. CodeRabbit remains the required review gate. Codex owns final decisions and repository mutations.
• No production deployment, release, or promotion to main.

Testing Decisions

• Diagnostic redaction is tested through configured logger/output seams with sentinel secrets and plaintext that must never appear.
• Published-type purity is tested by packing the library and compiling a consumer fixture that does not install Jest types.
• Shared diagnostics are tested through the public logger configuration and existing Relay, RelayPool, and protocol behavior.
• Wallet lifecycle is tested through the service API for sequential initialization, concurrent initialization, disconnect, and restart.
• Zap consolidation is tested through both public facades, cache-observable collaborator behavior, filter semantics, and statistics results.
• NIP-46 consolidation is tested through both simple and advanced public APIs, including correlation, timeouts, encryption/decryption, and lifecycle.
• Test-loop work is verified with deterministic focused tests plus measured default and explicit slow lanes.
• Test-seam cleanup preserves behavior while removing casts to private implementation shapes.
• Ephemeral Relay splitting is tested through the existing testing entrypoint and its observable Relay/session/filter behavior.
• Tests should assert external behavior, use independent expected values, and avoid private methods or internal collaborator mocks unless the owned testing entrypoint is itself the public seam.
• Each ticket runs focused tests during TDD and the complete repository suite once before delivery.

Out of Scope

• Public API redesign or removal of supported 0.x facades.
• Splitting cohesive NIP modules solely because of file length.
• Removing logger compatibility aliases protected by the diagnostics ADR.
• Release version changes, publishing, production deployment, or promotion to main.
• Unrelated stale issue cleanup.

Further Notes

The ordering is optimized for security and low-risk wins first, followed by lifecycle and consolidation work, then feedback-loop and structural cleanup. The owner has explicitly approved all nine slices, their testing seams, their dependency order, and autonomous execution through integration into staging.

[AustinKelsay]

Cleanup chain complete. Issues #131–#139 were delivered serially and merged into staging through PRs #140–#148. Every slice started from the latest staging baseline and passed its scoped reviews and verification; the final staging merge commit is 9c9e14c. No release or promotion to main was performed.