feat: retain local conversation context and reviewed side notes

[BunsDev]

Summary

Finish the preserved local-continuity work: exact-scope drafts, remembered selections and anchors, bounded UTC chapter navigation, and retained local side notes with reviewed imports. Side notes support close/reopen/discard; imports remain inert user notes with atomic stale-review checks and idempotent retry handling. Integrates #212 across narrow and landscape layouts.

Review corrections

• Explicitly represent out-of-page/unavailable remembered familiars without mislabeling their transcripts.
• Surface not-ready chapters, invalidate stale chapter caches on either close path, remember anchors inside the history viewport, and refresh after late successful conversation creation.
• Offer retry after side-note metadata failures. Distinguish guaranteed no-commit stale reviews from uncertain acknowledgements; only the former can prepare a fresh reviewed operation.
• Maintain an operation-key index and use compatible IndexedDB v2 indexes, keyed atomic preconditions and a shared mutation revision. Cold hydration/external changes still load history; unchanged write admission avoids full-store scans.

Boundaries

No new native commands, fabricated replies, canonical remote writes, SDK publication changes, conformance-lock changes or vendored-source changes. Canonical chapter transport remains unsupported by the frozen SDK and is disclosed as such. #86 and protected release gates remain parked.

Evidence

The review corrections passed 131 affected unit cases and all 36 browser cases, plus typecheck, lint and production build. Two optional unit cases were skipped, not claimed as executed evidence. Real IndexedDB browser cases cover v1 migration, concurrent writes, cross-store operation-key collisions, rollback and uncertain acknowledgements. At both 50 and 20,000 retained messages, the bounded-write journey uses zero full-store reads. Independent read-only review found no significant issues in the correction. Final exact-head CI and GitHub follow-up review are pending.

All 54 historical validation artifacts are excluded from the PR and preserved byte-for-byte. After merge, retire the clean branch/worktree with verified history bundles and move those historical outputs intact into session storage.

[Copilot]

🟡 Changes recommended

Eight unresolved moderate findings affect error handling, stale state, continuity restoration, and local-history performance.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds session-scoped conversation continuity, retained local side notes with reviewed imports, UTC chapter navigation, and responsive layout support while preserving Cave’s read-only boundary.

Changes:

• Persists scoped drafts, selections, anchors, and familiar context.
• Adds atomic, idempotent side-note lifecycle and import handling.
• Adds chapter UI, documentation, and unit/E2E coverage.

Review findings:

• Moderate: src/chat-chapters.tsx needs explicit not_ready handling and stale-cache invalidation on Escape.
• Moderate: src/chat-shell.tsx needs container-based anchor visibility and sidebar refresh after late conversation creation.
• Moderate: src/chat-side-conversations.tsx needs distinct stale-review conflict handling and non-blocking load-error states.
• Moderate: src/lib/local/chat-store.ts and src/lib/local/indexeddb-backend.ts need to avoid full-history scans for imports and writes.

File summaries

File	Description
src/lib/sdk/query-adapter.ts	Adds chapter querying and source identity.
src/lib/sdk/connection-controller.ts	Extends the chapter read-client contract.
src/lib/local/side-conversations.ts	Defines side-note and import validation.
src/lib/local/side-conversations.test.ts	Tests retention, retries, and concurrency.
src/lib/local/memory-backend.ts	Adds in-memory revisions and CAS checks.
src/lib/local/local-query-adapter.ts	Exposes local side-note and import metadata.
src/lib/local/indexeddb-backend.ts	Adds atomic preconditioned persistence.
src/lib/local/chat-writer.ts	Adds local side-note write APIs.
src/lib/local/chat-store.ts	Implements side notes and reviewed imports.
src/lib/local/chat-store-complexity.test.ts	Tests large-history behavior.
src/lib/local/chat-records.ts	Extends persisted record schemas and validation.
src/lib/chat-continuity.ts	Stores scoped drafts, anchors, and reviews.
src/lib/chat-chapters.ts	Builds and validates UTC chapters.
src/chat-side-review.test.tsx	Tests review persistence and cancellation.
src/chat-side-conversations.tsx	Implements side-note UI and imports.
src/chat-shell.tsx	Integrates continuity, anchors, chapters, and side notes.
src/chat-shell.test.tsx	Tests shell behavior and conversation fixtures.
src/chat-shell.css	Adds chapter and side-note styling.
src/chat-continuity.test.tsx	Tests source and thread continuity.
src/chat-composer.tsx	Adds scoped drafts and receipt validation.
src/chat-chapters.tsx	Implements chapter browsing and fallback states.
src/chat-chapters.test.tsx	Tests chapter validation and paging.
src/app.tsx	Integrates asynchronous conversation creation.
README.md	Documents continuity and local side notes.
e2e/local-continuity.spec.ts	Covers multi-viewport continuity flows.
e2e/helpers/local-continuity.ts	Provides local continuity helpers.
e2e/app.tauri-mock.spec.ts	Expands mocked Cave and local-flow coverage.
e2e/app.smoke.spec.ts	Makes demo URL assertions baseURL-aware.

Review details

Suppressed comments (5)

src/chat-chapters.tsx:112

• When a chapter page is stale, the toggle click invalidates the query cache before closing, but the Escape path only collapses the panel. Reopening via keyboard can therefore reuse the cached stale root page and keep showing the old index. Invalidate the chapter query here as well.

        if (event.key === 'Escape' && expanded) {
          event.preventDefault();
          setExpanded(false);
          toggle.current?.focus();

src/chat-side-conversations.tsx:189

• A conflict here is also how bringBack reports a stale preconditions check before any commit. Moving that case to uncertain disables the editor and tells the user to retry the same stale payload, which will deterministically fail again; distinguish stale-review conflicts from acknowledgement/commit uncertainty and return to a re-reviewable state.

        reviewEntry.update({
          phase: 'uncertain',
          notice:
            result.status === 'ok'
              ? 'The receipt did not match the exact parent. Retry to reconcile.'

src/chat-side-conversations.tsx:86

• When capability.get returns an error, this returns without setting ready. The render gates all controls and the final notice on that flag, so the component stays in the loading branch forever and offers no retry or creation path. Mark the load as finished while retaining the notice (and apply the same treatment to the list error below).

        if (info.status !== 'ok') {
          setNotice(failure(info));
          return;

src/lib/local/chat-store.ts:516

• Every import or retry currently flattens all message buckets and scans the entire local history to find one operationKey. Long retained notes are explicitly supported by this change, so repeated imports allocate and traverse unrelated messages; keep an operation-key index (updated during hydration and writes), or otherwise avoid a full flat() scan on this path.

        const previousImport = [...messagesByConversation.values()]
          .flat()
          .find((entry) => entry.broughtBack?.operationKey === input.operationKey);

src/lib/local/indexeddb-backend.ts:111

• Every append and side-state/import change supplies expectedConversations, so this branch executes getAll() on both stores before each write. A normal local send therefore materializes and scans the entire message history in a readwrite transaction, making writes O(total messages) and causing large retained histories to block on full scans. Use keyed reads for expected-conversation CAS and a dedicated operation-key lookup/tombstone mechanism instead of loading both stores wholesale.

      if (change.expectedConversations || change.absentOperationKey) {
        void Promise.all([
          requestAsPromise(conversationStore.getAll()),
          requestAsPromise(messageStore.getAll()),
        ])

• Files reviewed: 28/28 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[BunsDev]

The exact-head CI run succeeded, but I am holding this PR as draft while verifying the additional review findings. The next pass will cover chapter/error states, scroll-container anchoring, late-create refresh, recoverable stale-review conflicts, and bounded local-storage lookups without weakening atomicity or retry safety. Historical validation artifacts and the current candidate are already preserved; no merge will occur merely because CI is green.

[BunsDev]

All eight additional findings were verified and addressed in a789b3d, now included in head a89029c with the main .gitignore update. One clarification: the side-note load-error notice was already visible; the missing recovery was an explicit retry, now added without enabling mutation controls before metadata loads.

The five review-summary items are covered: stale Escape invalidation; definitive stale-review rejection with fresh re-review versus immutable uncertain retries; metadata retry; an operation-key index retained through hydration/writes/discard; and keyed transactional IndexedDB admission with v1 migration and a shared revision. Atomic collision/rollback and real durable bounded-read regressions pass, along with all 36 browser cases and 131 affected unit cases. Independent read-only follow-up found no significant issues. Awaiting final-head CI and GitHub re-review before merge.

[Copilot]

🟡 Changes recommended

Six unresolved moderate findings remain across error handling, retry state, lookup complexity, timestamp ordering, and chapter validation.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (4)

src/chat-side-conversations.tsx:251

• When an idempotent create resolves to a discarded tombstone, this leaves createKey.current pointing at that permanently unusable operation. Every subsequent click retries the same key and returns the same discarded note, so this mounted parent can never create a new side note. Clear the key after surfacing the tombstone so the next explicit create gets a fresh operation key.

        if (created.side.state === 'discarded') {
          setNotice('This creation request refers to a discarded note.');
          return;

src/chat-side-conversations.tsx:26

• failure is used for metadata reads at lines 90 and 98 as well as mutations, so a failed get/list is reported as an unsaved change and tells the user to retry an operation key that does not exist. Split read and write formatting (and the state-transition path) so retry guidance describes the actual failed operation.

function failure(result: Exclude<WriteResult<unknown>, { status: 'ok' }>): string {
  if (result.status === 'unsupported') return result.reason;
  if (result.code === 'conflict')
    return 'This operation conflicts with its earlier request. Retry the unchanged review to reconcile, or cancel explicitly.';
  if (result.code === 'not_found')
    return 'The exact parent, side note, or selected message is unavailable.';
  return 'The local change could not be saved. Retry uses the same operation key.';

src/lib/local/chat-store.ts:477

• Unlike appendMessage, this state transition writes updatedAt directly from the wall clock. A clock rollback can make a recently closed/reopened note sort before older notes in listSideConversations, producing incorrect ordering and cursor paging; keep the state-change timestamp monotonic relative to the previous updatedAt.

          updatedAt: new Date(now()).toISOString(),

src/lib/sdk/query-adapter.ts:419

• Chapter validation hard-caps a page at 50 headers, but this method uses the generic pagination normalizer whose accepted maximum is 100. A caller requesting listChapters(id, { limit: 100 }) can therefore receive a page that ChatChapters always rejects as invalid_response; enforce the chapter-specific limit here or raise the validation bound consistently.

    listChapters(conversationId: string, readOptions?: PageOptions) {
      const normalized = normalizeBoundedPageOptions(readOptions);
      if (normalized.status === 'error') return Promise.resolve(normalized.result);
      const page = normalized.options;

• Files reviewed: 29/29 changed files
• Comments generated: 2
• Review effort level: Lite

[BunsDev]

Exact-head CI is green again. The follow-up review identified six additional edge cases, so this remains held from merge while they are verified: create-error messaging, side-create replay lookup/tombstone recovery, operation-specific error guidance, monotonic side-note timestamps and a consistent chapter page limit. Previously answered inline findings remain resolved; the new findings will receive explicit dispositions.

[BunsDev]

The six follow-up findings are addressed in 476279a. The two new inline threads are answered. The four summary items now have explicit recovery/contract behavior: confirmed discarded creation replay releases its old key for a subsequent explicit create; errors and thrown acknowledgements retain the key; read/create/state/prepare/import failures have distinct accurate guidance; side-state and subsequent append timestamps remain monotonic on clock rollback; chapter requests above 50 are rejected consistently while other pagination retains 100.

Qualification on the chapter finding: current UI callers already use the safe default of 50. This fixed an exposed adapter/validator contract mismatch, not a currently emitted 100-header UI request.

The correction passed 144 affected unit cases and 18 relevant browser cases, including real IndexedDB lost-ack and cross-window discarded-creation recovery. Two optional unit cases were skipped. The complete final-head CI run and re-review remain pending; all historical validation artifacts and each candidate history are preserved.

[Copilot]

🟡 Changes recommended

Three unresolved moderate issues remain in chapter pagination, side-note retry identity, and import timestamp ordering.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

src/chat-chapters.tsx:199

• When the chapter service returns a page with status: 'unavailable', the component suppresses the chapter navigation but still renders Load more chapters whenever that page carries cursor.hasMore. Clicking it can continue paging an index that was explicitly declared unavailable, and a later page can re-enable anchors. Do not offer pagination for unavailable results (or reject such cursors during validation).

          {result.status === 'ok' && result.data.cursor?.hasMore ? (
            <button
              className="chat-shell__load-more"
              type="button"

• Files reviewed: 30/30 changed files
• Comments generated: 2
• Review effort level: Lite

[BunsDev]

The latest CI run passed. Re-review has narrowed the remaining findings to three: pending side-create identity across navigation, the import timestamp's parent-clock floor, and pagination of an explicitly unavailable chapter index. These are being verified and covered before merge, with session-only continuity versus full-reload reconciliation kept explicit rather than overstated.

[BunsDev]

All three latest findings are addressed in 5062fd4. The creation retry and import-clock threads are answered with their precise contracts. Explicitly unavailable chapter root and continuation pages are now terminal even when they advertise a cursor: neither pagination controls nor handler calls can continue them or re-enable anchors.

The correction passed 156 affected unit cases and 20 relevant browser cases; two optional unit cases were skipped. Coverage includes lost-ack parent navigation, durable-list reconciliation after reload, scope isolation, late acknowledgement fencing, empty-parent clock rollback and unavailable continuation pages. Final-head CI and follow-up review are requested before merge; every candidate and all historical artifacts remain recoverable.

[BunsDev]

The latest three review items are dispositioned in 932b66c, with a coupled startup-error correction in a060b19.

• Confirmed commits are not misclassified as unsaved merely because their records were later removed. Availability is explicit, missing saved content remains copyable until dismissal, and nothing is resubmitted.
• Startup carries a revision sampled before its snapshot; the first write no longer reloads unchanged history. Concurrent changes and unsupported revision providers remain conservative.
• Explicit familiar continuations are empty terminal pages; the singleton UI root still advertises no continuation.
• Initial revision/snapshot failures now reach an explicit Retry local storage UI, not an unhandled rejection/spinner or empty-history fallback. Failed factory-owned openings close their connections; injected backends remain available for retry.

242 affected unit cases and 50 browser cases passed for the review correction; two optional unit cases were skipped. Startup follow-up passed 68 targeted cases (one optional benchmark skipped), typecheck, lint and build. Existing history, exact receipt guards, frozen authority and all historical artifacts are preserved. Final-head CI and re-review are pending.

[BunsDev]

Main advanced through the separately owned Windows staging/diagnostic integrations while these UI corrections were being completed. I am integrating that accepted main history without rewriting its authority bindings before the next final-head run; the active #220 investigation is not part of this feature. The validated UI/storage changes and historical artifacts remain preserved.

[BunsDev]

Current main 37e6984 is integrated in 1a22dcd with its Windows authority ancestry and all 15 upstream files preserved exactly. Validated UI/storage bytes are unchanged from a060b19. The merge passed 212 targeted authority guards and typecheck; unchanged browser coverage was not rerun solely for the upstream merge.

The known-commit/current-availability disposition is complete, startup storage failures have explicit retry, and all answered inline threads can be considered resolved. Awaiting CI and re-review on this exact integrated head before merge and reversible worktree/branch retirement.

[Copilot]

🟡 Changes recommended

Four unresolved findings remain, including one critical issue.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (3)

src/lib/local/chat-records.ts:132

• String(value.side.state) makes this type guard accept boxed or otherwise non-string values such as new String('discarded'), even though the returned object is then treated as a StoredConversation with a non-literal state. A malformed persisted tombstone can therefore remain visible and be exposed as an object-valued Cave status instead of being dropped by sanitization. Check the three literal values directly.

        ['open', 'closed', 'discarded'].includes(String(value.side.state)))) &&

src/lib/local/chat-store.ts:349

• The revision check and loadAll() are separate operations, so another window can commit after currentRevision is sampled but before the snapshot is loaded. In that race this code marks the stale snapshot with the old revision and notifies observers, leaving the active UI unaware of the other window's write until a later mutation; re-read the backend revision after hydration and retry the refresh when it changed, as reconcileWrite already does.
  src/lib/local/side-conversations.ts:74
• Legacy imports hydrated without broughtBack.preconditions can never be replayed: sameImport returns false, so an unchanged retry with the persisted operation key falls into the conflict path instead of returning the existing receipt. This breaks idempotent retries for data written before the precondition field was added; treat a missing stored precondition as compatible after the operation key and other receipt fields match (or explicitly version these receipts as unreplayable).

• Files reviewed: 45/45 changed files
• Comments generated: 1
• Review effort level: Lite

[BunsDev]

The latest review cases are being verified before merge: active uncertain-review key release, exact persisted state validation, a competing revision during refresh, and legacy receipt replay. The fixes will preserve read-only compatibility without allowing unchecked new imports, and will not introduce an unbounded refresh loop or claim continuous synchronization.

[BunsDev]

The latest four findings are addressed in d28df3d, now integrated with main's quota-reproduction tests/docs in e9b7f45.

Persisted side states require exact literals. Detected refreshes attempt at most three coherent snapshots, fail explicitly if still unstable, and never rewrite a committed receipt during retry; this is not continuous synchronization. Legacy receipt replay remains read-only after mandatory valid request proof and exact key/target/source-ID/excerpt matching; historical missing proof never admits a new mutation or rewrites provenance.

197 targeted unit cases and 32 browser cases passed (one optional benchmark skipped), with typecheck/lint/build. The six upstream test/doc files match main exactly; their changed guard passed 76 cases with 19 existing skips. Validated UI/storage bytes, all parent safeguards and all 54 historical artifacts remain intact. Final-head CI and re-review are pending.

[Copilot]

🟡 Changes recommended

Unresolved recovery, persistence, IndexedDB, and test issues must be addressed before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (2)

src/lib/local/memory-backend.test.ts:78

• This repeats the same matcher mistake: .rejects is given a function, not the Promise from an invoked operation, so the conflict assertion cannot run. Use a synchronous toThrow assertion (or invoke an async wrapper) for backend.commit.
  src/lib/local/memory-backend.test.ts:137
• The conflict test again passes an uninvoked async function to .rejects, so Vitest never executes the synchronous backend.commit call. This makes the new backend test fail independently of the precondition behavior; switch it to toThrow or invoke a Promise-producing wrapper.

• Files reviewed: 47/47 changed files
• Comments generated: 4
• Review effort level: Lite

[BunsDev]

Final disposition: all review threads are resolved. The focused independent review found no substantive issues in 1061c31 or the test-only readiness correction 1fbdf23. Exact-head CI 34630520550 succeeded (web, E2E, desktop, canary and Unix supervisor); push duplicate 34630515559 was cancelled by configured branch concurrency. Native/protected lanes remain outside this UI change and were skipped, not counted as conformance acceptance. Local full-suite authority timeouts remain explicitly qualified; no authority code or timeouts were changed. The final branch bundle and all 54 historical artifacts are preserved and verified before normal merge and reversible worktree/branch retirement.

[BunsDev]

Merged as 4d7de7a. The merged worktree and local/remote feature branch have now been removed through guarded retirement (no forced worktree removal or branch -D). Full branch history is retained in a verified recovery bundle, and all 54 historical validation artifacts were archived, hash-verified and moved intact before removing the clean checkout. No active SDK/native integration worktrees were touched.