signed/docs/repo-state-plan.md

Repository state and panel flow plan

Status: phases 1-2 implemented, phase 3 next (2026-09-13)

Builds on docs/backend-rearchitecture.md, especially §7 (notify audit), §11 (split independently-observed state), §12 (one debounce at the source) and §13 (merge the repo listing files, not the entities).

Scope: signed_state::{repo, repos}, workspace::views::{repo, issues, pull_requests, inbox}.

Goal

1. Open an issue or PR directly, from any surface (inbox entry, notification, future deep link), without walking Explore -> repository panel first.
2. One per-repository entity that spans both identities: the local git repository and the NIP-34 announcement, instead of today's separate LocalReposStore entry / Option<Announcement> + Option<Entity<RepoStore>> view state.

What the code does today (verified against the current tree)

1. Item panels are cached and never observe their store

The dock renders the active panel through panel.cached(...) (crates/dock/src/tab_panel.rs:777-795), so a panel re-renders only when its own entity notifies. Cross-entity reads are not reactive.

RepoDetailView observes its store (views/repo/store.rs:35-43), but the panels that read the same store do not:

• IssueDetailView (views/issues/detail.rs:79-85) renders placeholder("Issue not found", cx) when the issue is absent, with no observer. When a directly opened store's first pass lands later and notifies, nothing re-renders the panel: it stays on "Issue not found".
• PullRequestDetailView::load runs once from cx.defer_in (views/pull_requests/detail.rs:88-91) and caches error = "Pull request not found" when the store is empty (:124-133). It can never recover.
• IssuesView / PullRequestsView memoize rows behind (store.version(), filter) (views/issues/mod.rs:324-351, views/pull_requests/mod.rs:334-369) but nothing re-renders them when the version changes, so an open list does not see new events either.
• NewPullRequestView reads store.head / the announcement in new, so a late first pass does not reach its defaults.

The normal flow hides this because the repository panel is opened first: by the time the issues list or an item panel is created, the store has already applied its first pass. Opening an item directly is the case where the store is still empty at construction.

2. The initial pass waits on a timer the backend already provides

RepoStore::new defers refresh (signed_state/src/repo.rs:130-141), and refresh always waits REFRESH_DEBOUNCE = 300 ms (repo.rs:25-26, :230-242) before the local database query. RepoListStore has the same timer (repos.rs:120-123, :270-281) plus a separate refresh_initial that skips it (:257-268).

Both stores only refresh on Backend events:

• NostrUpdate is already batched by the notification pump with its own PUMP_DEBOUNCE = 200 ms (backend.rs:37, :112-166). Per backend-rearchitecture.md §12, the per-store timers were to be dropped once the pump absorbed the bursts.
• Published and Synced are one-off events; RefreshGate already folds them into an in-flight run.

The timers are therefore pure added latency for these two stores: ~300 ms (batched updates) to ~500 ms (pump window + store window) before local data appears.

3. Opening an item requires a hydrated Announcement

repo_store(announcement) (views/repo/actions.rs:216-219) and the inbox's lookup in RepoListStore (views/inbox.rs:384-404) need the announcement in hand and silently no-op when it is missing (RepoListStore not synced yet, deleted repo, inbox section without a matching list entry). The store itself can load the announcement from the local database; run_refresh already queries filters::announcement(&addr) (repo.rs:251-261).

4. Local and announced repositories have no shared identity

• LocalReposStore holds scan paths; RepoListStore holds announcements; CheckoutsStore joins them (checkouts.rs:211-213, :569-609).
• RepoDetailView encodes both modes in three option fields: initial: Option<Announcement>, store: Option<Entity<RepoStore>>, local_path: Option<PathBuf> (views/repo/mod.rs:74-85), with apply_announcement moving between them (views/repo/store.rs:13-31). The invalid combinations and the initial fallback in announcement() (views/repo/mod.rs:322-331) are the cost of the missing per-repo entity.

Design

1. Panels observe, derive into local state, notify on change

Every panel that reads a store keeps a local snapshot of exactly the slice it renders, updates it in an observer, and calls cx.notify() only when the slice changed. This is the pattern RepoDetailView::refresh_statuses (views/repo/store.rs:88-101) and SidebarPanel::refresh already use; the item panels are missing the observer half.

View	Observed entity	Local snapshot
IssueDetailView	Entity<RepoStore>	root issue, status, comments
PullRequestDetailView	Entity<RepoStore>	root PR, description, tip, base, clone urls
IssuesView	Entity<RepoStore>	visible_issues, counts, item_sizes, cache_key
PullRequestsView	Entity<RepoStore>	visible_prs, counts, item_sizes, cache_key
NewPullRequestView	Entity<RepoStore>	announced head, default base

Sketch, matching the existing idiom:

// new()
let subscription = cx.observe(&store, |this, store, cx| this.sync(store, cx));

// Copy the slice; notify only when it changed.
fn sync(&mut self, store: &Entity<RepoStore>, cx: &mut Context<Self>) {
    let store = store.read(cx);
    let issue = store.issues.iter().find(|issue| issue.id == self.issue_id).cloned();
    let comments: Vec<Event> = store.comments_of(&self.issue_id).cloned().collect();
    let status = issue.as_ref().map(|issue| store.status_of(issue));

    if self.issue != issue || self.comments != comments || self.status != status {
        self.issue = issue;
        self.comments = comments;
        self.status = status;
        cx.notify();
    }
}

PullRequestDetailView needs its one-shot load split in two:

• bind finds the root PR in the store and snapshots description, tip, base and clone urls. Re-runnable on every store version change.
• load_diff does the async patch/git work. Runs once bound, and again when the bound tip changes (a PR update arriving late).

2. One debounce, at the backend pump

Delete the REFRESH_DEBOUNCE timers from RepoStore and RepoListStore. Their triggers all come from Backend; the pump batches relay traffic and RefreshGate folds one-off events into an in-flight run. Keep RefreshGate exactly as is, used without a timer:

pub fn refresh(&mut self, cx: &mut Context<Self>) {
    if self.refresh.request() != RefreshRequest::Schedule {
        return;
    }
    self.run_refresh(cx);
}

RepoListStore::refresh_initial collapses into refresh; the new-time cx.defer call becomes the initial load, with no timer.

Add pub loaded: bool to RepoStore, set when the first pass applies. It separates "no data yet" from "genuinely empty": panels render a loading state while !loaded, and "not found" only after loaded.

CheckoutsStore and InboxView keep their timers in this plan. Their refresh request sources are not only the backend pump (checkout requests, settings and scan observations), so the same argument does not hold unchanged; revisit separately if measurements show the timers redundant.

3. RepoStore is the one per-repository entity

Keep the name RepoStore (Repository collides with gix::Repository, already imported in views/repo/loading.rs). Shape:

pub struct RepoStore {
    /// NIP-34 address. `None` while the repository is local-only.
    addr: Option<RepoAddr>,
    /// Latest announcement. Seeded from the open-time hint, replaced by the
    /// database's latest on the first pass. `None` while local-only.
    pub announcement: Option<Announcement>,
    /// Local working copy: the scan path for a local repo, an associated
    /// checkout for an announced one. A snapshot; `CheckoutsStore` stays the
    /// authority for the full list of checkouts.
    pub path: Option<PathBuf>,
    /// The first local pass has been applied.
    pub loaded: bool,
    // issues, patches, pull_requests, comments, status_by_root, head, flags...
    _subscription: Option<Subscription>,
}

addr is required in addition to announcement: (announcement: None, path: Some(_)) is otherwise ambiguous between "local-only" and "announced, first pass pending", and the store needs the address to run its query.

Constructors and the state transition:

impl RepoStore {
    /// Announced repository. Resolves `path` from `CheckoutsStore` if the
    /// user already has a checkout.
    pub fn new(addr: RepoAddr, hint: Option<Announcement>, cx: &mut Context<Self>) -> Self;

    /// Local repository discovered by the scan, not announced yet.
    pub fn new_local(path: PathBuf, cx: &mut Context<Self>) -> Self;

    /// Local -> NIP-34 in place. Keeps `path`, so the panel keeps its worktree.
    pub fn announce(&mut self, announcement: Announcement, cx: &mut Context<Self>);

    pub fn addr(&self) -> Option<&RepoAddr>;
}

• new: subscribes to Backend, seeds announcement from the hint, defers remote subscribe/connect, runs the local pass immediately.
• new_local: no Backend subscription, loaded = true, path set.
• announce: sets addr, announcement, keeps path; installs the Backend subscription, connects the announced relays and refreshes. Called from apply_announcement, which loses its field surgery.
• Nostr-side actions (push_repository, clone_to_folder, open_issue/open_pull_request, status changes) already have action_error("Repository announcement is not loaded yet") (repo.rs:1368-1378); they now also handle addr == None the same way.
• announce should also CheckoutsStore::record(path, addr) for the scan path, so the association exists immediately instead of waiting for the origin/EUC match in resolve_associations. Optional, verify behavior.

RepoDetailView then holds store: Entity<RepoStore> plus explorer state only. initial and local_path are deleted; announcement() reads the store; local-mode checks become store.read(cx).addr().is_none(); load_repo opens path when not announced, and keeps today's cache-mirror flow for announced repositories.

4. Opening a repository or item needs only a RepoAddr

• repo_store(addr: &RepoAddr, hint: Option<&Announcement>, cx) -> Entity<RepoStore>.
• open_repo_item(dock_area, addr: &RepoAddr, item, window, cx).
• Inbox passes its already-parsed address (signed_core::InboxItem.address, the root event's a tag) and drops the RepoListStore lookup.
• open_upstream no longer polls the list; it opens the panel by address and the store fills it in (Phase 2).
• RepoItem::Patch behavior is unchanged.

Phases

Phase 1 - make item panels react to the store (fixes the reported flow)

Status: implemented, except step 6.

1. signed_state/src/repo.rs: REFRESH_DEBOUNCE and the timer spawn are gone; refresh runs immediately. loaded was added and is set in the apply closure. A first pass notifies even when it found nothing, so views leave their loading state and show the empty result.
2. signed_state/src/repos.rs: same timer removal; refresh_initial folded into refresh.
3. views/issues/detail.rs: observes the store and re-renders; loading placeholder while !store.loaded().
4. views/pull_requests/detail.rs: observes the store; sync/sync_missing bind the root and load_diff does the async work, keyed to a PrBinding and guarded by a generation so late results are discarded. Loading vs not found is decided by store.loaded().
5. views/issues/mod.rs, views/pull_requests/mod.rs: observe the store; rebuild recomputes rows/counts/item sizes and sync notifies on change. Filter buttons call rebuild before notifying.
6. views/pull_requests/new.rs: not done. Its store-derived inputs are defaults for the compare/base selectors; re-applying them on a late store pass would clobber a selection the user already made. Left for a follow-up once the defaults can be derived without resetting the selectors.

Phase 2 - entry points by identity

Status: implemented.

1. views/repo/actions.rs: repo_store(addr, hint, cx) seeds the store's relays from an optional hint but needs nothing else; the store loads the announcement itself. open_repo_item(addr, hint, item, window, cx) takes the address, not a hydrated announcement.
2. views/inbox.rs: open passes its already-parsed address and the RepoListStore lookup with its silent early-return is gone. An inbox row opens whether or not the repository is in the list yet.
3. open_repo_panel and RepoDetailView::new take an address plus an optional hint, so a repository panel opens from a RepoAddr alone. This pulls the address-based constructor forward from Phase 3 step 2.
4. RepoDetailView::attach_store adopts the store's first announcement when initial is still empty and calls load_repo, so a panel opened by address fills in instead of waiting for the caller to have the announcement.
5. open_upstream: the 60 x 250 ms poll and the pending_upstream field are gone. It opens the panel by address; the store's subscribe_remote fetches the announcement from the bootstrap relays and step 4 loads the explorer.

Phase 3 - one entity for local and NIP-34

1. signed_state/src/repo.rs: addr/path options, new_local, announce, Option<Subscription>, action guards.
2. views/repo/mod.rs: single store field; new_local; header, display name, load_repo, open_init_dialog derive from the store. The address-based new is already in place from Phase 2.
3. views/repo/store.rs: always observe; refresh_statuses returns false when not announced.
4. views/repo/actions.rs, header.rs, banners.rs: drop Option<Entity<RepoStore>> guards, guard on addr() instead.
5. LocalReposStore stays as the scan index; CheckoutsStore stays the association authority.

Phase 4 - deferred, only if duplicate stores become a problem

One store per address via HashMap<RepoAddr, WeakEntity<RepoStore>> inside RepoListStore, so an item panel opened while the repository panel is open shares the same store and its subscriptions. Not needed for correctness once Phase 1 lands; each open then loads from the local database immediately.

Non-goals

• No per-store debounce; the pump is the one debounce (§12). RepoStore and RepoListStore must not grow timers again.
• No new global store, and no merging LocalReposStore, RepoListStore and CheckoutsStore into one entity (§13).
• Views never query the database directly; RepoStore stays the single projection so status/comment derivation is not duplicated.
• Explorer state (tree, refs, commits, scroll) stays in RepoDetailView.
• No Repository rename.

Validation

• cargo check -p signed_state -p workspace, then clippy.
• Manual scenarios:
  1. Fresh database, never open Explore: click an issue in the inbox. Panel shows a loading state, then the issue with comments and status.
  2. Same for a PR, including the patch diff loading once the root binds.
  3. Open the issues list, then receive a new issue (second client or publish); the row appears without reopening.
  4. Local repo: open from the sidebar, Init, panel keeps the worktree and gains the nostr header; reopening from Explore shows the same data.
  5. Existing flows: Explore list, ready-to-contribute and ready-to-push banners, new issue/PR dialogs.

Open questions

1. Should an announced repository with an associated checkout browse that checkout instead of the cache mirror? Today the panel always mirrors. RepoStore.path makes this a one-line decision later.
2. Store sharing (Phase 4): worth it only if duplicate subscriptions show up in practice.