refactor: complete Tier A+B API surface cleanup

CHANGELOG.md

@@ -11,11 +11,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - A supported `snstr/testing` subpath now owns the Node-only `NostrRelay` test Relay and framework-neutral Relay test-double types without leaking Jest into published application declarations.
 - Canonical NIP-01 client and Relay wire-message tuple types now provide one authoritative protocol definition.
 - Repository tooling now enforces npm 9.8.1 as the release package manager, Bun as a pinned compatibility runner, and explicit routine, slow, and complete test lanes.
+- ADR 0003 records the planned next-major Public Facade consolidations and Compatibility Alias kill-list without removing 0.x aliases yet.
+- NIP-42 module README documents the public Relay auth helpers.
 
 ### Changed
 - Relay event storage, Nostr Relay registry management, NIP-47 protocol codecs and dispatch, NIP-46 request machinery, NIP-57 client behavior, and ephemeral Relay transport/session/filter responsibilities now live behind smaller internal modules while preserving their public 0.x facades.
 - Production diagnostics now use one compatible logger policy across Nostr, Relay, RelayPool, NIP-46, NIP-47, NIP-57, and stateless protocol helpers.
 - Structural regression tests now prefer public behavior and owned testing seams over private implementation shapes.
+- Agent run session dumps are archived under `docs/agents/runs/archive/` with durable ledgers kept in the runs index.
+- Root and browser entry points now export the public NIP-01 type surface through explicit allowlists instead of star re-exports.
+
+### Deprecated
+- NIP-57 `ZapClient` is deprecated in favor of the canonical `NostrZapClient` facade.
+- NIP-46 `SimpleNIP46Client` and `SimpleNIP46Bunker` are deprecated in favor of the full `NostrRemoteSignerClient` and `NostrRemoteSignerBunker` facades.
+- NIP-46 boolean validators are renamed to `isValidNip46*`, with the previous `validate*` names retained as Compatibility Aliases.
 
 ### Fixed
 - NIP-44 decryption now rejects unsupported legacy payload versions and malformed v2 nonce sizes through the public decrypt path.
@@ -26,6 +35,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Security
 - NIP-46 connection secrets, private keys, decrypted payloads, and untrusted error text are excluded from diagnostic output.
 - Generic key, wire-format, and resource-limit validation now has canonical ownership so NIP-specific policies cannot silently drift.
+- NIP-46 `isValidNip46PrivateKey` (and its deprecated `validatePrivateKey` alias) now rejects keys outside the secp256k1 curve order, matching canonical key-validation.
 
 ## [0.5.0] - 2026-07-18
 

CONTEXT.md

@@ -23,3 +23,11 @@ _Avoid_: Query, search parameters
 **NIP**:
 A Nostr Implementation Possibility that defines a protocol behavior or interoperable extension.
 _Avoid_: Plugin, feature spec
+
+**Public Facade**:
+The supported public class or function that callers should use for a capability when multiple wrappers exist.
+_Avoid_: Primary API, recommended entrypoint (use this term instead)
+
+**Compatibility Alias**:
+A deprecated public export retained for 0.x consumers until the next major release removes it.
+_Avoid_: Legacy shim, soft export

README.md

@@ -422,6 +422,8 @@ The project is organized with detailed documentation for different components:
 - **[NIP-17](src/nip17/README.md)**: Gift wrapped direct messages
 - **[NIP-19](src/nip19/README.md)**: Bech32-encoded entities
 - **[NIP-21](src/nip21/README.md)**: URI scheme for nostr links
+- **[NIP-29](src/nip29/README.md)**: Relay-based groups
+- **[NIP-42](src/nip42/README.md)**: Client authentication to relays
 - **[NIP-44](src/nip44/README.md)**: Versioned encryption
 - **[NIP-46](src/nip46/README.md)**: Remote signing protocol
 - **[NIP-47](src/nip47/README.md)**: Nostr Wallet Connect

docs/adr/0003-plan-public-facade-removals.md

@@ -0,0 +1,29 @@
+# Plan Public Facade consolidations and Compatibility Alias removals
+
+SNSTR will keep Compatibility Aliases through the remaining 0.x line and remove them deliberately in the next major release. Each dual Public Facade gains one canonical replacement now; deprecated aliases stay exported and documented until that major bump. This preserves downstream imports while making the supported surface intentional for agents and humans.
+
+## Kill list (planned next major)
+
+| Compatibility Alias / dual | Canonical replacement | Notes |
+| --- | --- | --- |
+| `ZapClient` | `NostrZapClient` | NIP-57 Public Facade |
+| `SimpleNIP46Client` / `SimpleNIP46Bunker` | `NostrRemoteSignerClient` / `NostrRemoteSignerBunker` | Simple is demo/compat only |
+| `initializeCrypto` (root/web NIP-17 alias) | `initializeNIP17Crypto` | Already `@deprecated` |
+| `nip19.validateRelayUrl` | `isValidRelayUrl` from NIP-19 secure helpers | Already `@deprecated` |
+| `RelayInformation` | `RelayInfo` | Already `@deprecated` |
+| NIP-47 `LogArgument` / logger type aliases | Root `DiagnosticLogArgument` / `DiagnosticLogger` | ADR 0002 |
+| NIP-02 `Logger` warn-only alias | `WarningLogger` / root diagnostics | ADR 0002 |
+| NIP-46 `getPublicKey` | `getUserPublicKey` | Already `@deprecated` |
+| NIP-46 boolean validators named like `validateEventContent` / `validatePrivateKey` / overlapping peers | NIP-specific `isValidNip46*` names | Keep old names as aliases until major |
+
+## Considered Options
+
+- Remove Compatibility Aliases immediately in 0.x. Rejected because it breaks consumers without a major version signal.
+- Keep dual Public Facades indefinitely without deprecation. Rejected because agents and docs treat both as first-class and the surfaces drift.
+
+## Consequences
+
+- 0.x work may deprecate and document, but must not delete listed aliases.
+- New code and examples should prefer the canonical Public Facade.
+- Simple NIP-46 must not gain new capabilities; Full is the production path.
+- Root/web type exports should be explicit allowlists that still include listed aliases until the major removal.

docs/agents/runs/README.md

@@ -0,0 +1,22 @@
+# Agent run artifacts
+
+Durable Feature Dev / cleanup run ledgers live in this directory. Verbose per-issue session dumps, review packets, and CodeRabbit round logs are archived under [`archive/`](./archive/).
+
+## Current ledgers
+
+| File | Run |
+| --- | --- |
+| [`feature-cleanup-tier-ab-ledger.md`](./feature-cleanup-tier-ab-ledger.md) | Tier A+B API surface cleanup (#154) |
+| [`cleanup-1-9-ledger.md`](./cleanup-1-9-ledger.md) | High-impact cleanup 1–9 (#130) |
+| [`deep-cleanup-1-8-ledger.md`](./deep-cleanup-1-8-ledger.md) | Deep cleanup 1–8 (#111) |
+| [`deep-cleanup-final-audit.md`](./deep-cleanup-final-audit.md) | Final staging audit after deep cleanup |
+| [`feature-cleanup-runtime-debt-ledger.md`](./feature-cleanup-runtime-debt-ledger.md) | Runtime debt cleanup (#100) |
+| [`feature-cleanup-1-8-ledger.md`](./feature-cleanup-1-8-ledger.md) | Earlier cleanup 1–8 feature ledger |
+| [`feature-cleanup-1-3-ledger.md`](./feature-cleanup-1-3-ledger.md) | Earlier cleanup 1–3 feature ledger |
+| [`feature-collapse-event-validation-ledger.md`](./feature-collapse-event-validation-ledger.md) | Event validation collapse |
+
+## Policy
+
+- Prefer updating the active run ledger over creating new session dumps at the top level.
+- If a full issue session record is required by the Feature Dev loop, store it under `archive/` once the issue is closed, or keep only the ledger row with the commit SHA.
+- Do not delete archived evidence; move it.

docs/agents/runs/archive/tier-ab-coderabbit-local.md

@@ -0,0 +1,8 @@
+# CodeRabbit local gate — Tier A+B
+
+- Command: `coderabbit review --agent --type all --base staging`
+- Result: unavailable / silent after >4 minutes with no stdout (process terminated)
+- Fallback: fresh standards + spec code-review against staging (Feature Dev unavailable-fallback)
+- Fallback outcome: worthy findings fixed (NIP-42 README accuracy, NIP-46 README API block, curve-order CHANGELOG Security entry, SimpleNIP46 docblock wording, examples note)
+- Ignored: remaining boolean peers not renamed (`validateRequestPayload`, etc.) — judgement call; ADR kill-list covers colliding names; further rename deferred
+- Checks after fixes: tsc clean, lint clean, routine Jest 1076 passed, pack/commands/package-manager verify OK

docs/agents/runs/feature-cleanup-tier-ab-ledger.md

@@ -0,0 +1,83 @@
+# Goal Ledger: Tier A+B API Surface Cleanup
+
+## Run
+
+- Run ID: `snstr-cleanup-tier-ab-20260728`
+- Loop: feature-dev
+- Target repo: `snstr`
+- Base branch: `staging`
+- Feature branch: `feature/cleanup-tier-ab-api-surface`
+- Human owner: plebdev
+- Started: 2026-07-28
+- Current status: non-draft PR #163 open into staging; local CodeRabbit unavailable with fallback recorded
+- Skill setup status: present and verified
+
+## Goal
+
+Complete Tier A and Tier B cleanup end to end: close stale shipped issues, publish a 1.0 deprecation kill-list, archive agent run dumps, add NIP-42 docs, collapse/deprecate dual public facades (NIP-57 Zap clients, NIP-46 Simple vs Full), align overlapping NIP-46 validators with canonical security paths, and replace root `export *` type dumps with an explicit allowlist — then open a non-draft PR into `staging`.
+
+## Durable Artifacts
+
+- CONTEXT updates: Public Facade, Compatibility Alias
+- ADRs: `docs/adr/0003-plan-public-facade-removals.md`
+- Prototype source branch, if any: none
+- Spec issue: [#154](https://github.com/AustinKelsay/snstr/issues/154)
+- Tickets: #155–#162
+- Ticket sessions: orchestrator-driven under full-autonomy grant (no separate parked HITL)
+- Agent briefs: Grok/Opus bounded review sidecars for standards/spec; implementation on orchestrator + Opus sidecar
+- Review packets: inline standards/spec review in this run; worthy findings fixed
+- Local CodeRabbit report: `docs/agents/runs/archive/tier-ab-coderabbit-local.md` (unavailable fallback)
+- PR URL: https://github.com/AustinKelsay/snstr/pull/163
+
+## Commands
+
+- Install: `corepack prepare npm@9.8.1 --activate`; `npm ci`
+- Typecheck: `npx tsc --noEmit -p tsconfig.json`; `npx tsc --noEmit -p examples/tsconfig.json`
+- Test: `npm test -- --runInBand` (1076 passed)
+- Build: `npm run lint && npm run build && npm run build:examples && npm run pack:verify`
+- Visual verification: not applicable
+
+## Ticket Ledger
+
+| Issue | Type | Status | Review thread | Fixes needed | Verified |
+| --- | --- | --- | --- | --- | --- |
+| #155 Close stale issues | AFK | closed | n/a (gh-only) | none | yes |
+| #156 Kill-list ADR | AFK | implemented | standards/spec | none after ADR+changelog | yes |
+| #157 Archive runs | AFK | implemented | standards/spec | README index | yes |
+| #158 NIP-42 README | AFK | implemented | standards/spec | fixed wrong export names + structure | yes |
+| #159 ZapClient deprecate | AFK | implemented | standards/spec | none | yes |
+| #160 SimpleNIP46 deprecate | AFK | implemented | standards/spec | examples note + docblock wording | yes |
+| #161 NIP-46 validators | AFK | implemented | standards/spec | changelog Security for curve-order | yes |
+| #162 Type allowlists | AFK | implemented | standards/spec | NIP-11 duplicate export resolved | yes |
+
+## Parked HITL Slices
+
+| Issue | Why parked | Blocks | Required human action | Final PR decision |
+| --- | --- | --- | --- | --- |
+| None | — | — | — | — |
+
+## Issue Session Ledger
+
+| Issue | Fixed point | Worker session | Commit | Review result | Checks |
+| --- | --- | --- | --- | --- | --- |
+| #155 | staging | orchestrator | (gh-only) | n/a | issues closed |
+| #156–#162 | staging | orchestrator + Opus implement | `2195805` | standards/spec findings fixed | tsc, lint, 1076 routine, pack/commands verify |
+
+## Open Questions
+
+- None. Owner granted full end-to-end autonomy.
+
+## Alignment Decisions (locked)
+
+1. Close `#82`, `#88–91`, `#93–98` as shipped.
+2. Keep Compatibility Aliases through 0.x; document 1.0 removals in ADR 0003.
+3. `NostrZapClient` canonical; deprecate `ZapClient`.
+4. `NostrRemoteSigner*` production; deprecate `SimpleNIP46*` for 1.0.
+5. NIP-46 boolean validators → `isValidNip46*`; private-key uses canonical key-validation.
+6. Explicit root/web type allowlists including Compatibility Aliases.
+7. Archive session dumps; keep ledgers.
+8. Out of scope: Tier C splits, alias removals, release to main.
+
+## Escalations
+
+- None.

examples/nip46/README.md

@@ -16,6 +16,10 @@ See [ARCHITECTURE.md](./ARCHITECTURE.md) for diagrams and a visual explanation o
 
 ## Examples
 
+> **Note:** Prefer `NostrRemoteSignerClient` / `NostrRemoteSignerBunker` for production.
+> Examples that still use `SimpleNIP46*` are demo/compat only; those classes are
+> Compatibility Aliases deprecated for the next major release (ADR 0003).
+
 ### Unified Example (`unified-example.ts`) - RECOMMENDED
 
 A single comprehensive example that shows the core functionality:

src/entries/index.web.ts

@@ -25,7 +25,59 @@ export type {
 } from "../nip01/nostr";
 
 // Export types
-export * from "../types/nostr";
+// Explicit allowlist instead of a star export so the public type surface stays intentional (ADR 0003).
+export {
+  RelayEvent,
+  RelayStatus,
+  NostrKind,
+  WebSocketReadyState,
+  RelayErrorType,
+  NIP20Prefix,
+} from "../types/nostr";
+export type {
+  NostrEvent,
+  EventTemplate,
+  NostrFilter,
+  Filter,
+  Subscription,
+  RelayReceivedEvent,
+  RelayEventCallbacks,
+  RelayEventHandler,
+  PublishOptions,
+  PublishResponse,
+  SubscriptionOptions,
+  SubscriptionResponse,
+  FeeSchedule,
+  RelayFees,
+  RelayLimitation,
+  RelayInfo,
+  RelayInformation,
+  RelayStats,
+  RelayGroup,
+  ReconnectionStrategy,
+  RelayCapabilities,
+  MetricsCollectorOptions,
+  RelayMessageStats,
+  ProfileMetadata,
+  RelayDebugOptions,
+  RelayError,
+  RelayInterface,
+  ValidationOptions,
+  EventOfKind,
+  MetadataEvent,
+  TextNoteEvent,
+  RecommendRelayEvent,
+  ContactsEvent,
+  DirectMessageEvent,
+  DeletionEvent,
+  RepostEvent,
+  ReactionEvent,
+  BadgeAwardEvent,
+  TaggedEvent,
+  TagValues,
+  EventTags,
+  ParsedOkReason,
+} from "../types/nostr";
 
 // Export utilities
 export {
@@ -98,13 +150,7 @@ export {
 } from "../nip11";
 export { fetchRelayInformation as getRelayInfo } from "../nip11";
 
-// Export NIP-11 types
-export type {
-  RelayInfo,
-  RelayLimitation,
-  RelayFees,
-  FeeSchedule,
-} from "../nip11";
+// NIP-11 relay-information types are the canonical `types/nostr` declarations exported above.
 
 // Export NIP-44 utilities
 export {
@@ -279,10 +325,7 @@ export {
   createQuoteTag,
   parseThreadReferences,
 } from "../nip10";
-export type {
-  ThreadPointer,
-  ThreadReferences,
-} from "../nip10";
+export type { ThreadPointer, ThreadReferences } from "../nip10";
 
 // Export signer utilities
 export {
@@ -324,15 +367,12 @@ export type {
   ZapStats,
 } from "../nip57";
 
-export {
-  NostrZapClient,
-  ZapClient,
-} from "../nip57/client";
+export { NostrZapClient, ZapClient } from "../nip57";
 export type {
   ZapClientOptions,
   ZapInvoiceResult,
   ZapFilterOptions,
-} from "../nip57/client";
+} from "../nip57";
 
 export {
   fetchLnurlPayMetadata,
@@ -365,10 +405,7 @@ export {
   getWriteRelays,
   RELAY_LIST_KIND,
 } from "../nip65";
-export type {
-  RelayListEntry,
-  RelayListEvent,
-} from "../nip65";
+export type { RelayListEntry, RelayListEvent } from "../nip65";
 
 // NIP-66: Relay Discovery and Liveness Monitoring
 export {