Skip to content

Commit f264c62

Browse files
Add verified Inbox evidence and exact edit closure (#495)
Signed-off-by: tulsi <[email protected]>
1 parent 78cdfd9 commit f264c62

9 files changed

Lines changed: 2552 additions & 3 deletions

File tree

‎docs/inbox.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
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

Comments
 (0)