Skip to content

pr-context-storage-matrix.md

Latest commit

 

History

History
132 lines (87 loc) · 5.54 KB

pr-context-storage-matrix.md

File metadata and controls

132 lines (87 loc) · 5.54 KB
Raw

PR Context Storage Matrix

How @knighted/develop stores pull request context across browser storage.

This guide focuses on PR-context ownership only.

PR context is stored in one place:

  1. IndexedDB (IDB): workspace snapshots used by the Workspaces drawer.

See the full storage ownership docs for non-PR keys:

Storage Surfaces

IndexedDB

  • Database: knighted-develop-workspaces
  • Object store: prWorkspaces
  • Relevant fields in each workspace record:
    • prContextState: inactive | active | closed
    • prNumber: number | null
    • prTitle, base, head
    • repo

localStorage

  • Not used for PR context state.
  • No legacy PR-context migration/cleanup path is supported.

Status Matrix

Use this matrix as the source of truth when debugging UI/storage mismatch.

Scenario IDB prContextState IDB prNumber localStorage PR fields Notes
A. Local workspace only, no PR context inactive null none No connected PR context.
B. Workspace is for an active, open PR active PR number none Push mode in PR controls.
C. Workspace is for a PR closed on GitHub closed closed PR number none Historical context retained for debugging/reference.
D. Active PR immediately after push commit active PR number none Committed tabs persist clean baseline (isDirty=false, syncedContent=content) and remain clean after reload.

Current Workspace Selection On Load

When the app loads, workspace restore scope depends on whether a repository is selected.

  • If a repository is selected: use repository-scoped records only (repo match).
  • If no repository is selected: evaluate all stored workspace records.

If a repository is selected and no repository-scoped records are found, restore falls back to evaluating all stored workspace records.

Selection order:

  1. Load candidate records using the scope above.
  2. Compute preferred candidates from in-memory state:
  • Preferred by id: existing in-memory active record id when available.
  • Preferred by workspace key: current repository + head (workspaceKey).
  1. If preferred-by-id or preferred-by-key exists and is active, select it.
  2. Otherwise select the first active record in candidates.
  3. Otherwise select preferred-by-id or preferred-by-key if present.
  4. Otherwise fall back to the first candidate by recency (lastModified descending).

Notes:

  • No active workspace pointer is stored in localStorage.
  • Restore behavior is intentionally derived from IDB workspace records + in-memory runtime state.
  • This avoids cross-storage drift between localStorage and IndexedDB.

PR Drawer Persistence Boundary

PR drawer field edits are treated as draft input.

  • Editing PR base/head/title in the drawer does not persist workspace record metadata by itself.
  • Workspace PR metadata is committed by explicit successful workflow outcomes (for example: successful Open PR, successful Push Commit, or successful Close PR/verified closed updates).

This keeps workspace records aligned to verified workflow outcomes instead of intermediate form state.

Active Record Model

Multiple active PR workspaces may exist for the same repository.

  • The model does not enforce a single-active-record-per-repository invariant.
  • Restore selection still follows the algorithm above and picks one workspace to load into the current runtime.

Why PR Context Lives In IDB Only

PR workflow state is part of workspace state.

Storing it only in IDB avoids drift between storage systems and keeps a single source of truth for restore behavior.

Debugging Checklist

When the UI does not match expected PR state:

  1. Check the IDB workspace record currently selected/opened and inspect:
    • prContextState
    • prNumber
    • repo, head, prTitle
  • committed tab fields: isDirty, syncedContent, content, syncedAt, lastSyncedRemoteSha
  1. Compare against the matrix above.
  2. If the PR is still open on GitHub, expect PR controls to return to Push mode and the workspace record to transition back to active.
  3. If the PR is no longer open, expect Open PR mode to remain and status messaging to explain verification results.

Console Snippets

IndexedDB (all workspace records):

indexedDB.open('knighted-develop-workspaces').onsuccess = event => {
  const db = event.target.result
  db.transaction('prWorkspaces').objectStore('prWorkspaces').getAll().onsuccess = e => {
    console.log(e.target.result)
  }
}

Close Behavior

Close archives PR-linked context in IDB and clears active PR context in runtime.

  • Matching workspace records for that PR context are persisted as closed.
  • Close does not force an automatic fresh-local-workspace handoff.
  • Workspace switching remains an explicit Workspaces action.