|
| 1 | +# Inbox: in-progress port |
| 2 | + |
| 3 | +Inbox is currently a bundled placeholder page (`buzz.inbox/inbox`). This |
| 4 | +stacked PR's session evidence is not displayed until the dependent Inbox UI PR. |
| 5 | +No new navigation behavior is part of this evidence slice. |
| 6 | + |
| 7 | +## Evidence slice (stacked with Inbox UI) |
| 8 | + |
| 9 | +PR3 adds no Inbox UI. The subsequent Inbox page uses `session.unread.inbox()` as |
| 10 | +its single conversation projection and `session.inboxFeed` as bounded addressed |
| 11 | +history demand. These changes are one launch batch, not a separately shippable |
| 12 | +backend feature. Ordinary channel and thread readers, read-state storage and |
| 13 | +outbox retain their existing ownership. No projects, approvals or reminders. |
| 14 | + |
| 15 | +## Ownership and limits |
| 16 | + |
| 17 | +`session.unread.inbox()` / `subscribeInbox()` own retained verified unread |
| 18 | +evidence and read actions. `session.inboxFeed` owns finite, verified addressed |
| 19 | +history demand and exact incomplete-target metadata, not a row cache. Finite |
| 20 | +results and live arrivals, edits and deletions use the existing session admission |
| 21 | +and shared unread fold, so own/deleted messages stay absent and unresolved roots |
| 22 | +never become duplicate conversations. Current membership gates the feed's |
| 23 | +completeness targets and unread's rows; joining alone does not materialize |
| 24 | +pre-membership history without fresh shared admission. Inbox renders those shared |
| 25 | +conversation rows directly; there is no second project/approval row merge or |
| 26 | +feed-owned reconciliation buffer and deletion-count abort. PR4 owns only |
| 27 | +presentation, filtering and selection. No parallel signing or persistence is |
| 28 | +added. Optional profile enrichment belongs to PR4; access, cache clear and |
| 29 | +session retirement fence these projections. Opening Inbox does not mark rows |
| 30 | +read; selecting an unread row does. Canonical Messages keeps its own reading |
| 31 | +behavior. |
| 32 | + |
| 33 | +DM read clears the channel through its newest retained evidence. Thread read |
| 34 | +advances the thread prefix, including earlier unshown replies, plus individually |
| 35 | +represented top-level mentions and local message marks, but not unrelated |
| 36 | +messages. Participation follows the shared unread owner's direct-parent policy, |
| 37 | +including its existing bounded lookups for replies whose membership is undecided. |
| 38 | +Fetched roots and participation witnesses remain structural, never extra Inbox rows. |
| 39 | +A lookup-only root uses the existing exact-message manual-unread target until counted |
| 40 | +root evidence arrives; its known root still supplies grouping and read-through. |
| 41 | +Relevant replies remain thread activity even when the root cannot be fetched. |
| 42 | +Multiple steps are not atomic: failures leave remaining evidence retryable. Manual unread is local to this device. Hosts without frontier-sync |
| 43 | +disable read mutations. Saved frontiers are not proof of remote reconciliation. |
| 44 | + |
| 45 | +This is **bounded recent evidence**, not a complete historical inbox. Unread |
| 46 | +retains at most 4,096 events / 8 MiB, observing up to 500 recent events per |
| 47 | +128-channel roster batch. A lazy addressed query returns up to 50 kind-9/40002 |
| 48 | +messages. For those exact IDs and unresolved failed targets, general `#e` |
| 49 | +queries page signed kind-40003 edits and kind-5/9005 deletions, then deletions |
| 50 | +of the edits; `include_aux` on an ordinary `#p` query is not a supported relay |
| 51 | +contract. Both auxiliary stages must finish before the feed is ready. Retained |
| 52 | +unread evidence can be provisionally admitted between queries, but exact target |
| 53 | +IDs are marked incomplete **before** unread subscribers are notified. The |
| 54 | +consumer must not show their body as current while incomplete; failures retain |
| 55 | +that metadata and offer retry. This is a completeness signal, not atomic content |
| 56 | +admission or a second message fold. A target outside the latest 50 addressed |
| 57 | +rows is not discovered; if a failed target falls outside a later page its |
| 58 | +bounded auxiliary check still runs before its incomplete flag is cleared. |
| 59 | +Incomplete obligations survive disconnect and unrelated access revocation while |
| 60 | +the corresponding readable unread evidence survives; full cache/session retirement |
| 61 | +clears both. Tombstone checks include retained author edits even if a later relay |
| 62 | +query omits their soft-deleted rows. If reference visibility withholds an auxiliary |
| 63 | +event, the finite attempt stays failed/incomplete rather than treating the filtered |
| 64 | +page as exhausted history. Explicit Retry can settle it once existing shared |
| 65 | +readers have admitted the missing reference; Inbox adds no reference-resolution loop. |
| 66 | +Auxiliary reads cap retained results at 2,000 events / 4 MiB per stage; the shared reader |
| 67 | +keeps its existing per-request deadline and cancellation. Missing roots, |
| 68 | +participation or older activity can omit rows; an empty Inbox does not prove |
| 69 | +complete history. No polling, independent row source or channel window is |
| 70 | +opened for the feed. Access/cache/disconnect/disposal fence pending reads; local |
| 71 | +read intent remains with unread. Packaged/native acceptance and human visual |
| 72 | +feedback remain separate. |
| 73 | + |
| 74 | +Reminders and their NIP-ER lifecycle are **not included** in this change. |
| 75 | +The unfinished reminder prototype is preserved separately for later work, |
| 76 | +not shipped in the Inbox source or broker routes. Follow/mute Inbox policy, |
| 77 | +full backlog discovery and nonchat activity are outside this slice. Project and |
| 78 | +approval queries, grouping, routing and detail presentation are deliberately |
| 79 | +excluded rather than presented as partial parity. Native/ACP packaged acceptance and human visual feedback |
| 80 | +remain open. Do not treat this as the full OG Inbox port. |
| 81 | + |
| 82 | +## Verification status |
| 83 | + |
| 84 | +`inbox-feed.test.ts` exercises the real session reader/visibility/unread owners |
| 85 | +with signed ephemeral events, including the first-admission subscriber ordering, |
| 86 | +held edit and tombstone reads, failure/retry, reentrant access removal and cache |
| 87 | +reset, root regrouping, and an edited addressed target older than 500 ordinary |
| 88 | +messages. `unread.test.ts` retains the current main read/catch-up behavior and |
| 89 | +adds Inbox projection/read-state cases. Neither file establishes browser paint, |
| 90 | +real relay persistence or packaged/native acceptance. PR4 must cover the |
| 91 | +per-row pending/failed presentation contract and exact inline previews. |
| 92 | + |
| 93 | + |
| 94 | +### Review repairs |
| 95 | + |
| 96 | +Incomplete obligations now survive lifecycle changes that retain readable evidence. |
| 97 | +Closure includes retained author edits omitted by later relay queries and fails |
| 98 | +visibly on withheld auxiliary evidence. Shared unread remains the sole row owner; |
| 99 | +the unused feed row copy and its 70-deletion abort were removed with explicit |
| 100 | +approval. A prepared channel-read intent lets the dependent UI retry the original |
| 101 | +cutoff and manual-clear keys. Tests retain all prior scenarios, distinguish both |
| 102 | +finite retention guards, and prove 71 admitted author deletions do not resurrect |
| 103 | +rows or require a second reconciliation buffer. |
| 104 | + |
| 105 | +Prior local tests and review cover the repairs on the combined tree; this PR's |
| 106 | +updated head requires its own checks. No human/live/native acceptance or shipping |
| 107 | +readiness is claimed. |
0 commit comments