feat(canvas): add version history with atomic restore

[wpfleger96]

🤖 Adds append-only channel canvas history, restore, and relay-authoritative optimistic concurrency so stale edits cannot silently replace a newer canvas.

What this adds

• Desktop history and restore — browse revisions with author, timestamp, preview, and diff; restore an older revision as a new signed head after explicit confirmation. Persisted empty canvases remain reachable, mutation outcomes are announced accessibly, and focus moves to a stable destination after save or restore.
• CLI history and restore — buzz canvas history --channel …, buzz canvas get --channel … --revision <id>, and buzz canvas restore --channel … --revision <id> use keyset pagination over the retained revision stream.
• SDK canvas builders — optional expected-revision tags, bounded ancestry classification, and shared timestamp discipline keep first-party writes ahead of the head they read without propagating poisoned future timestamps.

Authoritative concurrency contract

Tagged canvas writes use compare-and-swap semantics in the relay and database:

• expected-revision=none succeeds only when no live canvas exists.
• An event ID succeeds only when it names the canonical live head.
• A byte-identical replay succeeds only when that event is already the canonical live head.
• A successful candidate must sort strictly ahead of the current head under created_at DESC, id ASC.
• Malformed preconditions and stale or non-advancing writes are rejected before event rows, mentions, or fan-out are committed.

The database serializes tagged writes, unconditional kind 40100 writes, and canvas soft deletion on the same (community, kind, channel) advisory key. Untagged buzz canvas set remains an unconditional write, but participates in that serialization boundary so it cannot race a tagged save or deletion. Deletion classification is derived inside the datastore transaction; unrelated event kinds do not take the canvas lock.

Read and timestamp consistency

Precondition and post-write ancestry reads request strong consistency from /query, pinning them to the writer when replica routing is enabled. Display-only history remains replica-eligible.

First-party canvas writers stamp created_at = max(now, head + 1) with a conservative client skew limit. The relay applies a canvas-specific future-timestamp ceiling before persistence, preventing an accepted boundary head from making subsequent first-party writes invalid while preserving the broader ingest limit for other event kinds.

Durable outcomes and recovery

After an accepted publish, a failed verification read is reported as durable success with verified: false rather than a failed save. Desktop and CLI preserve the new event ID and direct users to History when verification is unavailable. A successful read walks the bounded, cycle-guarded expected-revision ancestry chain so transitive descendants are not misclassified as supersession. Canvas caches invalidate for every settled mutation outcome, including a retained but superseded revision.

The 409 reconciliation path in cmd_restore_canvas now separately establishes persistence evidence from ancestry classification. canvas_write_survived checks reachability only; a secondary writer-pinned IDs lookup distinguishes "A absent" from "A present but superseded by a legacy write." The four-way outcome (survived / persisted-but-superseded / genuinely-absent / read-fail) is now correct for all lost-response shapes including unconditional legacy writes.

[wesbillman]

Carl, an automated reviewer, commenting via Wes’s GitHub account.

Two blockers at bc07f7c10ef84b2798b28702399e7cf553aace98:

1. Reset canvas UI state when channelId changes. ChannelCanvas keeps isEditing, draft, editBaseRevision, and showHistory in component-local state, but the same unkeyed component instance receives a new channelId when the still-mounted management sheet switches channels. The query and mutation correctly retarget to the new channel, while the editor state does not. A concrete disclosure path is: start creating canvas A, type A-specific text, switch to canvas-less channel B, then save. The retained draft is submitted through B's mutation with the retained "none" precondition, so A's text becomes B's canvas. Key the subtree by channel or synchronously reset/close edit, draft, base revision, history selection, and mutation state on channel changes; add a switch-while-creating regression.

2. Do not collapse an accepted publish and a failed verification read into one generic failure. Desktop submits successfully and obtains result.event_id, then propagates any error from current_canvas_head_ancestry; CLI restore similarly has our_id after accepted submit, then can fail its head re-read before printing it. Desktop invalidates canvas/history only on mutation success and leaves the editor open on error, so retrying after reconnect encounters a stale-precondition conflict against the already-accepted write with no surfaced recovery ID. Preserve the durable accepted state: return/print the known event ID, invalidate/refetch, and expose an explicit “published, verification unavailable” outcome. Cover a successful submit followed by a failed verification query.

Evidence: ChannelCanvas.tsx, ChannelManagementSheet.tsx, canvasHooks.ts, canvas.rs, and channels.rs.

[wesbillman]

Carl, an automated reviewer, commenting via Wes’s GitHub account.

One blocker at 37601b9b5e624c75918e9fab69b6674825a6f506:

Invalidate canvas caches when an accepted write is reported as superseded. set_canvas publishes the event first, then returns CANVAS_SUPERSEDED if its verification read sees an unrelated head. That revision is durable and recoverable from history, but useSetCanvasMutation invalidates channel-canvas and channel-canvas-history only in onSuccess. The supersession marker rejects the shared save/restore mutation, so neither cache is invalidated and the UI can keep stale current/history data precisely when it tells the user to reload and restore the retained revision.

Move invalidation to onSettled, or explicitly invalidate this recognized durable-supersession outcome. Add regression coverage where setCanvas rejects with the supersession marker after publication and assert that both query keys invalidate/refetch for the save and restore paths.

The two blockers from the prior head are fixed: channel changes now remount the canvas subtree, and a failed post-write verification read now returns durable success with verified: false. The security/trust pass found no blocker.

Evidence: canvas.rs, canvasHooks.ts.

[wesbillman]

Carl, an automated reviewer, commenting via Wes’s GitHub account.

Changes requested at 5db94ff72dc8d6aa3f85714fea379068e46f8e84. The append-only history, keyset pagination, timestamp discipline, edit-start snapshot, create guard, channel-switch remount, and settled-outcome cache invalidation are sound. Three user-facing gaps remain:

1. [Medium] Preserve the accepted-but-unverified outcome on restore. Normal save inspects SetCanvasResult.verified and shows the recovery notice, but CanvasHistoryPanel.handleRestore discards the same result and collapses the selected row. Reproduction: the relay accepts the restore, then the post-write head query fails. The restore is durable, but the user gets no confirmation or History guidance; if cache refetch also fails, the old canvas can remain visible and invite a retry. Surface verified: false non-destructively for restore just as save does, and add a causal restore regression mirroring the unverified-save test.

2. [Medium] Do not report a transitive descendant as supersession. canvas_write_survived recognizes only our event or a head whose direct expected-revision is ours; Desktop and CLI each pass only that one parent tag (Desktop, CLI). If accepted writes A (ours), B (expected-revision=A), then C (expected-revision=B) all land before A's verification read, C is a legitimate transitive descendant but A is reported as CANVAS_SUPERSEDED / CLI exit 5. That tells the user to recover a save which remains in the accepted chain. Traverse ancestry with an explicit bound/cycle guard, or otherwise make classification and user guidance truthful; cover A→B→C at the Desktop and CLI seams.

3. [Medium, accessibility] Announce mutation outcomes and restore focus. Loading, error, unverified-save, and restore states are inserted as plain <p> elements without status/alert semantics (save, restore). Successful save/restore also removes the focused control. A keyboard or screen-reader user can receive neither an announced result nor a useful focus destination. Add appropriate live-region semantics and move focus to the resulting canvas/history notice, with interaction coverage. This is required by the repository's WCAG 2.1 AA product target.

[wesbillman]

Carl, an automated reviewer, commenting via Wes’s GitHub account.

Changes requested at 599cac2cf5b6f1ea854dea7e5171f6a7aa0699bb. The earlier restore-verification, transitive-ancestry, cache-invalidation, and accessibility/focus gaps are fixed. One UI recovery defect remains:

1. [Medium] Reset a rejected save before opening the next edit session. handleStartEditing resets the draft/base/notice but not setCanvasMutation. TanStack Query retains the mutation's error, and the editor renders that error whenever it opens (lines 172–177). Reproduction: let a save reject (stale/superseded/network), click Cancel, then Edit canvas. The prior alert immediately reappears before the user attempts the new session. CanvasHistoryPanel already avoids the analogous cross-selection leak with restoreMutation.reset(). Reset this mutation when starting a new canvas edit session, and cover reject → cancel → re-edit.

[wesbillman]

Carl, an automated reviewer, commenting via Wes’s GitHub account.

Changes requested at e18a8c292df72e2b689fc6955b51538d69d410dc. The append-only revision model, deterministic pagination, timestamp discipline, ancestry classification, durable-unverified handling, cache invalidation, and prior recovery fixes are sound. Two blockers remain:

1. [High] Pin conflict and post-write verification reads to the writer. Desktop now reads the head before publishing and reads ancestry immediately afterward through generic query_relay (canvas.rs lines 75–99); CLI restore does the same (channels.rs lines 417–466). That endpoint routes catch-all /query reads through query_events_routed (bridge.rs lines 1421–1429), which may serve the read replica when bounded-staleness routing is enabled. The DB contract explicitly says reads influencing a write must use the writer (buzz-db/src/lib.rs lines 1254–1289). Reproduction: enable replica routing with ordinary replication lag, save or restore a canvas, and let the immediate verification query hit the replica before the accepted event arrives. The successful query returns the old ancestry, so classify_post_write reports CANVAS_SUPERSEDED even though no competitor exists. A stale pre-write read can likewise validate against the wrong head. Add a writer-pinned/fenced query path for preconditions and read-after-write verification, and cover a lagging-replica sequence. Display-only history can remain routed.

2. [Medium] Confirm before restore overwrites the shared head. Expanding an old revision exposes “Restore this revision,” and its first activation immediately calls the shared write mutation (CanvasHistoryPanel.tsx lines 89–105, lines 188–211). An accidental mouse, touch, or keyboard activation while inspecting the adjacent diff changes the channel-wide canvas for everyone. History makes recovery possible, but only by finding the displaced head and performing another shared write. Require an explicit confirmation that identifies the selected revision and says it will become current, or provide an equivalent reversible undo flow. Update the E2E journey, which currently codifies immediate mutation (channels.spec.ts lines 3185–3195).

CI is green for this exact head. Per the automation’s read-only policy, I did not execute PR code locally.

[wesbillman]

Carl, an automated reviewer, commenting via Wes’s GitHub account.

Changes requested at exact head a0fb8e8a2df43e7f0080f8f4f362db008a112ffc. The prior writer-pinning, restore-confirmation, channel-switch, cache-invalidation, and accessibility issues are fixed. Two blockers remain:

1. [High] Keep persisted empty canvases reachable for read-only members. ChannelManagementSheet defines existence from trimmed content and only renders the Canvas ingress when hasCanvas || canEditNarrative (ChannelManagementSheet.tsx lines 307–312, lines 819–829). A persisted empty revision still exists and has history, but a member without edit permission loses the only ingress and cannot view that shared state or its history. This occurs after intentionally saving or restoring an empty revision. Determine existence from eventId !== null for ingress while retaining content-based preview behavior, and cover the read-only empty-canvas case.

2. [High] Do not advance an accepted boundary timestamp beyond the relay’s ingest ceiling. The SDK accepts a head exactly at client_now + 900 and returns head + 1 (builders.rs lines 632–640); its boundary test explicitly expects now + 901 (lines 3125–3137). The authoritative relay rejects timestamps more than 900 seconds from relay time (ingest.rs lines 2224–2230). An authenticated writer can therefore publish an accepted head at the ceiling, after which first-party save/restore immediately constructs a rejected event; refreshing the boundary head can keep writes unavailable, and ordinary client/server skew worsens it. Make the relay authoritative for head advancement, or reserve advancement plus clock/network margin in the client limit, and add an ingest-level boundary regression.

Current exact-head CI is otherwise green. Review used GitHub metadata, diff, and exact-head source only; no PR code was executed.

addressed

[wesbillman]

Carl, an automated reviewer, commenting via Wes’s GitHub account.

Review clear for the agreed corrective scope. The remaining CLI restore-recovery blocker from review 5097047079 is resolved at a2a138f357b94c374aa1f917216e44c0d6764140 (base 7a9a5233d9d755e715be0c585cf7850e935d28cf). No actionable blockers found in this source-only re-review.

• cmd_restore_canvas now returns accepted JSON when the submitted revision survives in the live head’s ancestry. Otherwise, a separate writer-pinned ID lookup distinguishes retained-but-superseded history from a genuinely rejected write. Failed reconciliation preserves an explicit unknown outcome and the submitted revision ID (crates/buzz-cli/src/commands/channels.rs:480–533, 614–632).
• Traced the production transport, strong-read routing, SDK ancestry, and relay/DB CAS integration. The previously reviewed canvas CAS, legacy serialization, desktop mutation handling, and ancestry semantics remain intact across the rebase. The command-level regression fixtures cover descendant success, legacy supersession, absence, both reconciliation-read failures, and the exact strong-consistency ID filter (channels.rs:4005–4184, 4297–4547).
• Validation was immutable source and test-text inspection only, with independent regression and backend integration reviews. No checkout, build, tests, or PR code execution. The descendant-output test checks JSON field presence rather than exact values; production currently emits the correct values. This is not a runtime/CI pass or an approval.

[wesbillman]

Carl, an automated reviewer, commenting via Wes’s GitHub account.

Review clear for the merge delta

No actionable introduced/regressed defect found at head 57c4b8b2d09dccb6a1bc92cd7d5d6aa23984d3b1 against base/merge-base a61239f0d8036aff58176f5c0ce7f080c66e21b7.

• Previously cleared behavior is preserved. Since review 5121883622 at a2a138f357b94c374aa1f917216e44c0d6764140, the branch adds two main merges and no non-merge commits outside main. The CLI restore-reconciliation fix, SDK ancestry/timestamp helpers, native canvas commands, desktop history/confirmation/pending-operation handling, and settled-outcome invalidation are byte-identical to that reviewed head.
• The merge seams were reviewed, not merely assumed safe. The production conflict resolution retains canvas CAS and unconditional legacy writes alongside workflow deletion; the new workflow arm requires kind 5 and cannot capture kind 40100. The shared query dispatch still routes first-party canvas write-influencing reads to the writer. Inspected DB integration, command registrations/closed sets, and both test-gate resolutions; the SDK and ACP test steps are both retained. No broader redesign or renewed hardening gate is requested.
• Validation is source-only. Exact-object comparison, conflict-resolution inspection, and test-source review ran on the pinned Blox host, with an independent metadata lane. No checkout, build, test execution, or live workflow was performed. The one-time exact-head CI snapshot recorded 55 successful checks, 27 skipped, and one cancelled Codex Security Review job, with none pending/failing. The cancelled job is a validation limitation, not an all-green claim.

This is a clear corrective review, not a GitHub approval or runtime certification.

[wesbillman]

Carl, an automated reviewer, commenting via Wes’s GitHub account.

Review clear for the corrective delta, with one non-blocking note

No merge-blocking defect found at HEAD 5147bb3b24cf2329562c71364368c3da643278a9 against BASE 77729abfb692b25a0f4ec4a69add86af2e32c0dd. This review covers the correction and merge interactions since the prior clear review at 57c4b8b2d09dccb6a1bc92cd7d5d6aa23984d3b1, preserving the established append-only history, atomic restore, legacy-write compatibility, writer-consistent reconciliation and durable-outcome contract.

• The HTTP correction reaches its consumer. The three canvas CAS rejection outcomes become CanvasConflict, HTTP returns 409 with the original conflict text, and the existing CLI 409/“canvas changed” reconciliation path is reachable. WebSocket rejection semantics and conformance classification remain unchanged. Reviewed the router-driven PostgreSQL regression and the merge's opt-in read-state snapshot routing; normal canvas query routing is preserved. Canvas DB storage, SDK, native/desktop and CLI feature implementations are byte-identical to the previously cleared head.
• [P3, non-blocking] Log the actual conflict status. The new 409 response uses SubmitOutcome::Rejected, whose terminal attribution branch still hard-codes status = 400u16. Submit a canvas with a stale expected revision: the client correctly receives 409, but the corresponding HTTP bridge request log records 400. This misclassifies conflict requests during operational triage; it does not break wire behavior, reconciliation or persistence. Derive the logged status from the existing response tuple rather than adding another status owner. The new regression asserts the wire status/body, not this attribution field.
• Validation is source-only. Exact-object comparison, changed producer/consumer tracing, merge-seam review and test-source inspection ran on the pinned Blox host with independent source and metadata lanes. No checkout, build, test execution or live workflow was performed. The single exact-head CI snapshot at 2026-09-22T17:02:12Z was nonterminal: 40 successful, 26 skipped and 6 in progress, none failed. No CI reruns or monitoring.

This is a clear corrective review, not a GitHub approval, all-green CI claim or runtime certification.