Spec: Complete Tier A+B API surface and maintenance cleanup

[AustinKelsay]

Problem Statement

After multiple cleanup waves on staging, triage still contains eleven shipped-but-open July issues, agent run dumps drown durable ledgers, NIP-42 lacks a README, dual Public Facades confuse callers (NIP-57 ZapClient vs NostrZapClient, NIP-46 Simple vs Full), overlapping NIP-46 validator names risk silent security drift against canonical validators, and root/web entries still dump types via export *.

Solution

Deliver eight AFK tracer-bullet tickets on one feature branch (feature/cleanup-tier-ab-api-surface) against staging. Preserve every Compatibility Alias through 0.x; document planned 1.0 removals; deprecate dual facades toward one canonical Public Facade each; rename/align NIP-46 validators without removing old names yet; replace type star-exports with an explicit allowlist that still exports the same public names.

User Stories

1. As a maintainer, I want shipped July issues closed, so triage no longer invites duplicate work.
2. As a consumer, I want a published 1.0 kill-list, so Compatibility Alias removals are predictable.
3. As an agent, I want agent-run dumps archived behind an index, so ledgers remain discoverable.
4. As a NIP-42 integrator, I want a README for the auth helpers, so the module matches other NIPs.
5. As a zap consumer, I want one canonical Public Facade (NostrZapClient), with ZapClient clearly deprecated.
6. As a remote-signing consumer, I want Full NIP-46 marked production and Simple marked demo/compat + deprecated for 1.0.
7. As a security maintainer, I want NIP-46 validators named distinctly and private-key checks routed through canonical key validation.
8. As a TypeScript consumer, I want an explicit root/web type allowlist that preserves 0.x names while making the supported surface intentional.

Implementation Decisions

• Base: staging. One branch for the whole feature.
• ADR 0003 records Public Facade + Compatibility Alias removal planning.
• ADR 0002 still governs logger aliases: no removals in this PR.
• NostrZapClient is canonical; deprecate ZapClient; export both only via nip57 barrel for root.
• NostrRemoteSigner* is the production Public Facade; deprecate SimpleNIP46* for 1.0; stop growing Simple.
• NIP-46 boolean validators get NIP-specific names; old names remain deprecated aliases until 1.0.
• Private-key boolean validation in NIP-46 routes through canonical key-validation semantics.
• Root and web replace export * from types/nostr with explicit exports of the same public names (including Compatibility Aliases).
• Archive pre-ledger session/review/coderabbit dumps under docs/agents/runs/archive/; keep *-ledger.md, final audits, and README.md.

Testing Decisions / Seams

Confirmed under owner full-autonomy grant:

• Public deprecation markers and README guidance (type/JSDoc/@deprecated).
• Export/typecheck: Node + web entries still expose listed names; pack/verify green.
• NIP-46 validator public behavior through existing validator/input-validation suites after rename/aliases.
• NIP-57 public client suites still green for both facades.
• Command/package verifiers green after archive + docs changes.
• No private-shape casts; prefer public barrels and documented Compatibility Aliases.

Out of Scope

• Removing Compatibility Aliases (1.0 only).
• Tier C god-module splits (relay.ts, nostr.ts, NIP-47 facade splits).
• Enum→map migrations, class→function mass refactors.
• Promoting/releasing to main / npm.

Alignment

• Owner granted full autonomy to lock seams, ticket graph, and product decisions.
• Glossary: Public Facade, Compatibility Alias added to CONTEXT.md.

[AustinKelsay]

Implementation complete on PR #163. Tickets #155–#162 done. Will close this spec when the staging PR merges.

[AustinKelsay]

Merged to staging via PR #163. Tier A+B cleanup complete.