Relays architecture

This document describes current code. The approved Fetch / Coverage / Sync design and active implementation milestones record the implemented direction and verification status. Live relay and authenticated timeline review remain pending.

Entrypoints

Persistence

Initialization uses CREATE TABLE IF NOT EXISTS for the current schema. The approved complete development-data reset removed old tables and migration code; there is no legacy importer or split-window runner. Normal account removal leaves archive facts intact. Tree kind/year/month grouping is derived in UTC; it is not stored as a UI hierarchy.

Event operations boundary

list renders persisted accounts, relay observations, and archive groups. Design-preview mode and sample data have been removed. Fetch, comparison, Sync, NIP-65 publication, archive selection and JSONL export are active; import remains deferred. The header owns account removal and JSON editing. Relays owns NIP-65 read/write configuration, connection status, and published-list application. Extra fetch sources is independent. Fetch browses the unique archive, Coverage displays per-source ranges, and Sync groups eligible missing deliveries by relay/kind/date.

accountRelayScope derives fetch sources from configured write relays plus extras; sync destinations are configured write relays only. A URL may exist in both lists; editing either list does not silently edit the other. The source union is deduplicated.

Comparison is rebuilt from query observations and completed applicable range inventories, ordered by query completion time and query sequence for ties. An unrelated/failed recent scope cannot overwrite older evidence. Age alone does not erase observations; invalid/future observation metadata is distinct from undetermined coverage. Only applicable completed absence enters the eligible Sync tree. Per-range Found counts are not summed as unique account totals. Socket checks and publication acknowledgements never establish verified event storage.

An Accepted EVENT query newer than old missing evidence yields an Awaiting recheck publication overlay, not a positive query_evidence row. Its query ID breaks equal-timestamp ties. Coverage/Sync expose the pending-recheck count separately and exclude it from missing candidates. A later applicable completed comparison can establish absence again; actual positive observations establish presence. Unrelated recent scopes, failed queries and acknowledgements do not erase stored-presence facts.

Network boundary

fetch queries configured and environment bootstrap relays using nostr-tools signature-verified event subscriptions and selects the newest replaceable events. The published NIP-65 snapshot is separate from local configuration. check measures socket establishment only; NIP-42 authentication/relay permissions are future work. No account private keys or bunker secrets are persisted.

backup uses configured write relays plus extras, not discovery bootstrap relays. NIP-77 negotiates a complete timestamp/ID comparison, then REQ downloads bodies. It is bounded to 60 kB outgoing binary payloads (hex-encoded on wire), 128 kB incoming JSON frames, 100 rounds, 250,000 IDs and 15 seconds. Failures are logged before independent ordinary fallback; partial NEG fragments never establish absence. The root nip77 export is used because this nostr-tools version has no exported nostr-tools/nip77 package subpath.

Fallback pages backward from a fixed run-start bound, inclusively retaining the earliest timestamp and deduplicating boundary IDs. Requested size defaults to 100; advertised NIP-11 caps lower the saved effective size. REQ is bounded to eight seconds and 100 pages per source/invocation. Literal EOSE plus a short unrestricted response completes under relay semantics; invalid responses and saturated seconds remain partial. Resume preserves strategy, cursors, limits, and original scope.

Completed initial history enables per-source recent intervals with a ten-second overlap and fixed new upper bound. Only a finished interval advances the forward boundary. Recheck history starts a new full historical observation; Refetch repeats exact old bounds. Range Resume resumes that range; default Fetch resumes the latest compatible unfinished full-source operation.

Sync snapshots eligible missing-copy evidence and original bodies, with optional relay/kind/date narrowing. It drains 200-copy chunks continuously and prioritizes Pending deliveries. processing_attempts is now a last-pass marker: selecting a row marks it with the invocation's marker, preventing repeated retries in later chunks. Stop/Resume retains the snapshot and skips Accepted/historical Verified deliveries. Older accepted-but-unverified rows are normalized on Resume without losing query history. Role/eligibility checks still prevent invalid uploads. Rejected/uncertain copies can be retried explicitly on Resume; neither path performs read-back.

Accepted counts as publication completion, not retained storage. The user invokes Recheck history afterward to update Coverage. Existing runs/signed bodies are preserved; no schema reset is needed. Compact operation progress is visible while delivery details stay collapsed, and Stop remains available in the summary.

Publishing uses generic nostr.signEvent immediate signing with allowedPubkeys. The selected account's author/signature and exact current tags are revalidated by the plugin before publication. Client signing alone never counts as publishing. The renderer polls only while metadata refresh or an operation is running.

Progress: implementation plan. Core contracts: plugin system and Web renderer.