Relay Manager implementation plan
Current direction
Relay-advertised NIP-11 information (approved)
Display compact Relay info disclosures in Relays and Extra fetch sources only. Show name/description, linked software/version, advertised NIPs, supplied limits, retention/authentication/payment requirements, fetched time and per-relay Refresh. Keep advertised metadata separate from actual query outcomes and storage evidence.
Approved presentation follow-up: place Relay info on its own full-width row below the relay controls, with a short readable summary and nested Full NIP-11 JSON.
- Separate disclosure expansion from the control-column row.
- Replace individual JSON blocks with one complete pretty-printed document.
- Verify structure/schema and update presentation documentation.
Presentation verification: targeted ESLint passed. An isolated renderer check confirmed a full-width seventh grid child below the six relay control cells, separate settings/source disclosures, concise name/version, nested pretty JSON without truncating an unknown field exceeding 8,000 characters, refresh actions and the shared WebNode schema. Authenticated visual review remains pending.
- Add persistent per-URL caching, bounded/coalesced NIP-11 requests and automatic background refresh; retain last successful information when refresh fails.
- Add a scoped manual refresh command and compact settings/source disclosures.
- Verify retrieval/cache/error handling and rendering, update docs/registration.
- Authenticated browser review.
Verification: targeted ESLint and plugin TypeScript checks passed; registration generation completed. In-memory/mock-HTTP checks covered idempotent schema setup, normalized endpoints/Accept headers, cache/coalescing/force refresh, cached failures and last-success preservation, response caps, non-object JSON rejection, five-request batching and extra sources. Structured refresh command checks confirmed configured URL scoping and rejection without fetching unrelated URLs. Renderer checks passed the shared WebNode schema for settings/source disclosures, account/view-preserving refresh actions, safe software links, missing/stale labels and successful-fetch timestamps. No production database or live relays were modified during validation. Backend restart is user-initiated outside the active chat.
Relay-scoped history rechecks (approved)
- Add
backup --history --relay <url>for one configured fetch source, with fresh beginning-through-now bounds and no implicit resume of an older range. - Add relay-header Coverage actions and finished single-destination Sync shortcuts; determine destinations from the complete delivery snapshot, not a visible page.
- Make completion/retry guidance scope-aware; retain global history rechecks, archive kind/year/month grouping and saved-range Refetch/Resume semantics.
- Verify isolated relay/range scope and UI wiring, update docs and registration.
- Authenticated browser/live relay review.
Verification: targeted ESLint passed, changed-module TypeScript diagnostics were zero and registration generation completed. An in-memory/mock-transport check exercised the structured backup command, URL normalization, fresh relay-only bounds, other-source checkpoint isolation, invalid scope/source rejection, global history and unchanged saved-range Refetch/Resume settings. A separate in-memory UI/sync check covered full destination scope across 50-row outcome pages, single/multi-relay shortcuts, account/relay action arguments, busy/removed-source disabling, multi-relay count aggregation, clean/retry/stop guidance and the shared WebNode schema. No live relay or production data was used. Backend restart is user-initiated outside chat.
Widget-wide tree controls (approved)
- Coordinate card-header Collapse all/Expand all across independent trees using shared Web UI state, with per-tree toolbar registration/cleanup.
- Save descendant expansion state even beneath collapsed/unmounted parents and prevent stale per-tree bulk requests from overriding state on remount.
- Verify shared renderer changes and document refresh/state-scope behavior.
- Authenticated browser review of multi-tree collapse/reopening/refresh.
Implementation belongs to the generic Web renderer; no Relay Manager-specific client branches or changes to the plugin's tree layout are required.
Verification: targeted ESLint passed and TypeScript reported no diagnostics in the
four changed shared renderer modules. An in-memory state check covered hidden
descendants, independent sibling/nested trees, saved refresh state, manual reopening,
tree-local controls and isolation. Repo-wide lint was attempted and is blocked by
unrelated unused variables in plugins/nr/db/evaluation-queue.ts (NostrEvent) and
plugins/translate/service.ts (settings). Authenticated browser review remains
pending. The renderer change is frontend-only and requires no backend restart.
Archive selection and JSONL export (approved)
- Fix the export-button
Missing required argument: pubkeyfailure by forwarding structured invocation payloads frominit.tsand parsing their arguments/options. - Verify full/selected exports through the command adapter and preserve CLI parsing.
Export-button fix verification: targeted ESLint passed. An isolated in-memory adapter invocation using the button's structured payload confirmed full and selected JSONL exports, unchanged CLI fallback, and required-pubkey validation. The plugin now consumes structured arguments/options rather than discarding them. Authenticated browser download review remains pending; backend restart is user-initiated outside chat.
- Enable Fetch selection at kind/year/month/event levels, including collapsed branches and unloaded pages; retain selection in this account's view state.
- Add Select all/Clear selection and full-archive/selected JSONL export using
relays_backup_${timestamp}.jsonl, preserving original signed event values. - Add a reusable command-backed browser download action; keep export local/read-only.
- Verify selection, account scoping, JSONL fidelity and download wiring; update docs.
Verification: targeted ESLint passed, changed-module TypeScript diagnostics were zero, and registration generation completed. An in-memory check covered scope/child overrides, unloaded pages, parent tri-state, account boundaries, overlap deduplication, full-history export, empty selection rejection, and original signed JSONL values including embedded newlines/Unicode. It checked the filename, menu/button wiring, view-state preservation and shared WebNode/download schemas. A mocked DOM/Blob check confirmed download click, content, anchor removal and object-URL cleanup; command errors are not downloaded as files. Authenticated browser download review remains pending. No production data was changed by export validation.
Publish-only Sync follow-up (approved)
Sync publishes original events and records acknowledgements; the user runs Recheck history afterward to update Coverage. This supersedes automatic per-event read-back and the 200-copy manual stopping point in the earlier milestones.
- Remove read-back requests from Sync, including Resume; retain previous delivery records.
- Automatically continue bounded batches until all pending copies have been attempted, keeping Stop/Resume and avoiding repeated retries within one invocation.
- Treat Accepted as publication completion, not verified storage. Show awaiting-recheck copies separately until a later applicable fetch/comparison updates their evidence.
- Update command/UI wording and documentation; verify continuous batching, Resume, cancellation, acknowledgement-only evidence and scoped subsequent rechecks.
Verification: targeted ESLint passed, plugin TypeScript diagnostics were zero, and registration generation completed. An isolated 201-copy transport check proved automatic chunk continuation, no read-back requests, one attempt per pass, separate rejection/uncertain outcomes, explicit retries without resending accepted copies, Stop/Resume, and preservation of older Accepted/Verified records. It also checked that acknowledgements yield Awaiting recheck rather than stored presence, recent Fetch leaves older copies pending, and Recheck history updates Coverage. Updated compact progress/awaiting-recheck output passed the generic WebNode schema. Live relay/authenticated UI review remains pending; existing queued runs can Resume after the backend is restarted outside the active chat.
Approved clean reset
The user requested a complete Relay Manager reset, including account/relay settings, and removal of the old backup implementation. This supersedes the legacy-preservation and legacy-resume requirements below; historical completion records remain historical.
- Remove the 500-event split-window runner, legacy option/button and old operation display.
- Remove obsolete presence migration/projection tables and unused scaffold CRUD.
- Reset only this plugin's SQLite database, after checking active operations.
- Verify fresh-schema initialization, current fetch/evidence/UI contracts and empty data; regenerate registration and reconcile current documentation.
Completed: reset plugins/relays/db.sqlite in place in an immediate SQLite
transaction after confirming no running operations. Removed the one configured
account, 1,055 events, the partial old backup, relay checks and all metadata/evidence.
All 12 current tables were verified empty; obsolete tables are absent. SQLite
integrity/foreign-key checks passed and WAL was checkpointed successfully.
Verification: targeted ESLint passed, plugin TypeScript diagnostics were zero,
and bun run plugin:generate completed. An isolated fresh-database check confirmed
repeat initialization, current paging/NIP-77 evidence and positive supersession,
shared work exclusion/cancellation, and legacy-free command metadata/UI schema.
The backend needs a user-initiated restart outside the active chat before re-adding accounts.
The approved Fetch / Coverage / Sync design is the source of truth for the implementation. It supersedes the earlier 500-event split-window strategy, one-hour presence expiry, global Coverage table, and proposed mandatory per-ID existence-check stage. The active milestones describe current delivery; the historical sections preserve the earlier implementation record.
- Record the Q&A decisions, UI flow, persistence direction, migration constraints, and deferred scope in the design document.
- Reconcile README/architecture links and the active implementation backlog.
- Implement the runtime milestones and verify the local persistence/transport/UI contracts below. Live relay and authenticated timeline review remain pending.
Runtime status
Implemented: account/relay settings, metadata/socket checks, NIP-65 publication, signature-verified archive, preferred NIP-77/fallback paging, incremental checkpoints, query/range history, non-expiring comparison, range Coverage, explicit eligible publish-only missing-copy Sync, subsequent history rechecking, outcome paging, and cancellation. Legacy code is removed under the approved clean reset above. Individual event browsing adds lazy month pages, read-only JSON inspection, hierarchical selection and full/selected JSONL export. Pending: live relay/authenticated browser review and the deferred scope below.
Implementation milestones
1. Evidence, query history, and migration
- Add additive per-account/relay cursor, range/attempt, query-log, and range-event evidence persistence around the existing archive and operation identities.
- Separate known Found IDs from validated archived bodies for reconciliation.
- Record exact scope/strategy/limit, sent/completed times, EOSE/NEG completion, NOTICE messages, errors, timeouts, disconnects, and counts per query/attempt.
- Replace TTL-based coverage with a provenance-backed latest-applicable-evidence projection. Failed queries retain prior facts; invalid observation metadata is reported separately instead of silently becoming Unknown.
- Initial legacy preservation/migration implemented; subsequently removed under the user's complete-reset decision. No old checkpoints are reinterpreted as current work.
Exit: repeat-safe initialization creates only the current schema; an event can have independent observations in multiple ranges/runs; partial and newer unrelated scopes do not overwrite older evidence; projection can be rebuilt from recorded provenance.
Progress: evidence.ts provides normalized ranges, query/evidence records,
comparison projection, and delivery snapshots. The clean reset removed old presence
migration and the legacy runner. Targeted lint/TypeScript
checks passed. Current in-memory checks confirmed repeat-safe fresh initialization, scoped historical
absence, positive supersession, and non-expiring evidence. Query details distinguish
attempt start from actual wire-send time, including unsent/cancelled attempts.
2. Ordinary paging and incremental fetching
- Add configurable page size, default 100, saved with each run.
- Replace normal split-window backfill with inclusive-earliest
untilpaging, boundary-ID deduplication, and explicit stalled-page detection. - Persist history completion, fixed run bounds, latest successful forward boundary, active paging cursor, and request outcomes independently per relay.
- After history completes, default to
since = successful boundary - 10sand a fixed current run-startuntil; advance only after the full interval completes. - Resume unfinished work with its original bounds/settings; leave failed or saturated scopes partial without skipping same-timestamp events.
- Add Recheck history and scoped Refetch as new observations of previous scopes.
- Replace ambiguous received totals with distinct Found/Fetched/newly archived counts; keep repeated delivery counts in query details.
Exit: repeated runs avoid unnecessary full backfills; interrupted snapshots resume without jumping forward; timestamp overlap does not duplicate archive bodies; rechecking can discover newly imported old events; short-page completion records its relay-limit assumptions rather than claiming universal completeness.
Verification: stub transport confirmed ordinary paging fallback, ten-second recent intervals, disconnect recovery, unchanged Resume limits, same-second stall without false completion, and a later completed history run superseding old partial work. NIP-11 max_limit guides the saved effective limit; no hostname-specific fallback.
3. NIP-77 reconciliation
- Select a compatible Negentropy implementation and assess dependency/runtime integration before adding it to this independent plugin.
Selected: existing nostr-tools 2.24.1 root nip77 export, with raw WebSocket
handling to preserve NEG-ERR reasons and bound negotiation. No new dependency.
- Implement bounded NEG-OPEN/NEG-MSG/NEG-CLOSE negotiation and record NEG-ERR, unsupported responses, version negotiation, timeout, and cancellation outcomes.
- Compare local matching archived timestamp/ID sets for the exact selected scope; persist remote-only/common/local-only evidence with run/range provenance.
- Download and validate remote-only bodies through REQ. Never upload to extra sources or automatically publish during Fetch.
- Use ordinary paging for unsupported/failed negotiation. Failed reconciliation cannot establish absence; fragmented/scoped reconciliation must record completeness.
- Share range/cursor/UI contracts between NIP-77 and fallback strategies.
Exit: differences in both directions are correctly attributed; common bodies are not redownloaded unnecessarily; same-timestamp IDs reconcile; unsupported relays still fetch; partial/error scopes never generate unsupported missing conclusions.
Verification: stub relay responses exercised common, remote-only, and local-only IDs, unsupported fallback, same-timestamp reconciliation, policy-excluded bodies, and cancellation. Limits are 60 kB binary outgoing payloads (hex-encoded on wire), 128 kB incoming JSON frames, 100 rounds, 250,000 local/difference IDs, and a 15-second negotiation timeout. A bounded failed scope falls back independently; no partial fragment is considered a full inventory.
4. Range Coverage and automatic comparison
- Replace the global state table with relay -> range -> kind/date/evidence tree.
- Display Beginning/date bounds, unique Found count, Fetched/Not fetched count where relevant, Complete/Partial status, and checked-at/attempt details.
- Put Refetch/Resume in each range's
⋮menu with active-run disabled states. - Expose Recheck history separately from default recent Fetch.
- Automatically recompute Sync candidates after committed applicable evidence; no additional Compare button and no automatic publication.
- Use completed comparison scopes to establish absence; never infer it from a limited page, failed query, age, or an unrelated incremental interval.
Exit: the same UI works for both transports; scope history remains inspectable; partial scopes are not displayed as complete empty ranges; multiple overlapping observations do not inflate the unique archive total.
Verification: populated generic WebNode output passed the shared schema; range menus, query attempts, Found/Fetched distinction, checked times, scope forms and distinct delivery outcomes were inspected. Authenticated visual review is pending.
5. Eligible missing-copy Sync and verification (initial iteration)
The automatic verification and manual 200-copy budget below record the initial implementation. They are superseded by the approved publish-only follow-up above.
- Define replay eligibility for deletion requests, expiration, superseded replaceable/addressable events, and private/ephemeral exclusions.
- Render per-write-relay missing-copy groups by kind/year/month; default to all eligible confirmed-missing copies with optional relay/kind/date narrowing.
- Snapshot selected candidates/scopes and persist resumable event/relay deliveries.
- Publish unchanged signed events only on explicit Sync; distinguish Pending, Accepted/already stored, Rejected, Verified, and Unverified with reasons.
- Read back corresponding IDs, validate bodies, and append verification evidence. Resume unfinished delivery/verification without resending verified copies blindly.
Exit: extra/read-only sources receive no sync uploads; one event missing on two destinations counts as two deliveries; acknowledgement alone is not verification; rejection and inconclusive read-back are separate; archive-only historical versions are not accidentally replayed as current events.
Verification: in-memory signed-event checks covered deletion, expiry and no revival of superseded versions. Stub transport confirmed write-only uploads, per-destination copy counts, positive read-back superseding old absence, and separate Rejected, Unverified/accepted, and Verified outcomes. A 201-copy queue check confirmed the 200-copy invocation budget, pending-first Resume, fair retries, and no resend of Verified copies. Accepted/Unverified Resume retries read-back; new explicit Sync can resend still-missing copies. Outcomes page in groups of 50 without event bodies.
6. Integration review and documentation
- Update command metadata, registration, README, and current architecture as each milestone becomes implemented; keep remaining items unchecked.
- Perform targeted lint/static verification and narrowly scoped isolated checks appropriate to migrations, paging boundaries, reconciliation, and delivery state.
- Obtain user review of live relay behavior and the timeline/range/overflow UI. Browser checks require an explicitly confirmed authenticated context.
Final local verification: targeted ESLint passed; the relay plugin had zero
TypeScript diagnostics; bun run plugin:generate completed. In-memory and stub
transport checks described above passed. A signed-body check also confirmed integer
timestamp/kind validation and invalidation of cached signature validation when the
stored body changes. No test files or test-suite commands were added/run. Real
relay and authenticated browser review are the remaining integration check.
No new test files or test-suite runs are included unless requested by the user.
Event browsing follow-up (approved)
- Lazy-load paged event rows beneath kind/year/month in archive, Coverage and Sync.
- Show timestamp and shortened ID without row actions or full-ID hover.
- Add ⋮ Copy ID, Copy JSON and Open JSON; disable body actions for Not fetched IDs.
- Open pretty-printed original JSON in the shared modal without a separate full-ID heading.
- Use explicit
Kind 0 · 1 eventlabels; verify queries/UI contracts and update docs.
Verification: targeted ESLint passed and plugin TypeScript diagnostics were zero.
An in-memory check confirmed lazy initial output, disjoint 50-row pages and page
clamping, range membership, eligible missing-copy filtering, cross-account JSON
lookup rejection, body-less IDs, preserved page state, exact row menus, non-clickable
rows, original JSON modal content, and explicit kind/count labels. Web output passed
the shared schema; bun run plugin:generate completed. Authenticated visual/clipboard
review remains pending.
Selection and JSONL export are implemented in the follow-up above; import remains deferred.
Deferred scope
- Specialized-relay explicit-kind fallback/capability policy (postponed by user).
- JSONL import.
- Relay authentication and optional preferred-signer references.
- Creation of deletion requests, media-file backup, and unattended scheduling.
Historical implementation record
First timeline iteration
- Persist accounts as independently validated JSON documents keyed by public key.
- Keep archive facts and relay observations independent of presentation.
- Replace
listscaffold with compact account, relay, event tree, and operations sections. - Support account/relay edits, profile and NIP-65 discovery, and measured connection checks.
- Initial sample design mode was provided, then removed during UI iteration.
- Update documentation, regenerate command registration, and lint changed files.
- User review of the rendered timeline design and real relay network behavior in authenticated AppWeaver.
Verification: targeted ESLint passed; TypeScript reported zero diagnostics in the plugin; a one-off in-memory check validated empty/preview/populated WebNode schemas, npub account creation, normalized relay updates/removal, invalid URL rejection, account deletion, and preview non-persistence. No browser or live relay checks were run.
Subsequent iterations
Account selection convenience
- Add browser-authenticated and named bunker public-key choices to Add account, alongside manual npub entry.
- Verify the reusable select source and update documentation.
Verification: targeted ESLint passed; changed-file TypeScript checks reported zero
diagnostics; a one-off schema check confirmed the dynamic public-key picker and
independent manual npub form in list. Authenticated browser review remains pending.
Compact layout iteration
- Remove Reload accounts and add-account Cancel; use + Account to toggle the section.
- Put account selection/manual input and their submit buttons on shared rows.
- Align relay headers/body with explicit element cells on identical grid tracks.
- Remove design-preview controls, command option, fixtures, and sample sync/progress renderers.
- Update docs/registration and verify changed files.
Verification: targeted ESLint and changed-file TypeScript checks passed; registration generation completed. A one-off in-memory schema/layout check verified empty/populated list output, six element cells per header/body row, inline account submit controls, and removal of the preview command option and render paths. Visual review in authenticated AppWeaver remains pending.
Account actions and automatic refresh
- Move account removal beside + Account.
- Move fetched-list, JSON configuration, and extra recovery sources to Sync.
- Automatically refresh profile/NIP-65 snapshots and relay connection observations in the background, coalescing concurrent requests and caching results.
- Update documentation and verify the new layout and refresh lifecycle.
Verification: targeted ESLint passed; plugin TypeScript diagnostics were zero. A one-off in-memory check with stubbed network responses validated concurrent refresh coalescing, five-minute cache reuse, URL-change invalidation, profile and connection observations, preservation of local settings, polling stop on completion, DM list without networking, and visible control placement. Live relay and browser review remain pending.
Account label and alignment cleanup
- Remove the fixed Watch-only identity label and use Add account wording.
- Center controls in both add forms and the account selector to prevent Open stretching.
- Verify the renderer and update the UI documentation.
Verification: targeted ESLint passed; static inspection confirmed the identity label removal and centered flex alignment for account add/selector forms.
Agreed fetch / coverage / sync structure
- Separate Relays, Extra fetch sources, Fetch, Coverage, Sync, and Operations in
list. - Derive fetch sources from configured NIP-65 write relays plus extras; derive sync destinations from write relays only.
- Add timestamped present/missing/unknown persistence with an additive migration of existing positive observations.
- Query per-relay coverage and missing relay/kind/year/month groups without counting unknown/stale records as missing.
- Render missing event copies per destination relay and move shared JSON configuration to account settings.
- Update docs and verify persistence/query and renderer contracts.
Verification: targeted ESLint passed and plugin TypeScript diagnostics were zero. A one-off in-memory SQLite check validated additive/repeated migration, existing account/archive retention, write-only scopes, per-relay duplicated-copy counting, stale/future/unknown classification, monotonic observation writes, independent source/relay edits, and the ordered WebNode section/tree schema. No live relay or authenticated browser checks were run.
The initial UI and presence-query foundations were arranged here. The archive and NIP-65 publication actions were implemented in the following section. Their next fetching/coverage changes are tracked in the active milestones above.
Enable publication and backup actions
- Enable Publish NIP-65 using the generic signer picker restricted to the selected account.
- Validate signed relay lists server-side and publish with per-relay acceptance/error results.
- Prevent older discovery responses from overwriting newer published snapshots.
- Rename Load published relay list to Reset to published relays and explain the local replacement.
- Implement signature-verified public-event backup with bounded windows, durable checkpoints, partial recovery, and resume.
- Display real operation progress and archive counts with polling while running.
- Verify isolated signing/publication and archive flows; update docs/registration.
Verification: targeted ESLint passed, changed-module TypeScript diagnostics were zero, and command registration generation completed. A one-off in-memory check using actual signed events and stubbed relay transport verified invalid-signature/ wrong-author/private-kind filtering, archive deduplication, observed presence, partial backup resume, concurrent-run rejection, interrupted-run recovery, selected-account signer restrictions, signed-list/config validation, per-relay publication outcomes, stale snapshot protection, and enabled widget actions. Live relay and authenticated browser review remain pending.
Initial event-engine backlog (superseded by active milestones)
- Archive public authored events from configured NIP-65 write relays plus extra fetch sources with bounded/resumable fetching and signature validation.
- Kind/year/month lazy browsing and archive selection were subsequently delivered in the browsing/export follow-ups above; sync scope narrowing is tracked in milestone 5.
- Mandatory per-ID presence queries are superseded by completed NIP-77/range comparisons. ID requests remain useful for downloading bodies.
- Current missing-copy publication is tracked in the publish-only follow-up; the initial delivery/read-back work is recorded in milestone 5. Automatic age expiry is superseded by provenance-backed observations in milestone 1.
- JSONL export was subsequently delivered above; import remains deferred.
- Integrate authenticated/bunker account selection for NIP-65 signing and publication.
- Relay authentication/preferred-signer references remain deferred.
- Replay semantics are tracked in milestone 5; creating deletion requests remains deferred.
The historical sections above describe the earlier iterations. Current Fetch, Coverage and Sync status is recorded in the active milestones; individual event selection/export are recorded in their follow-ups; JSONL import remains deferred. No dock widget registration. Runtime restart must be done by the user outside the active chat.