Use Git-backed canonical workspaces for invisible history, undo, and recovery

[robinbraemer]

Outcome

Use real Git as the source of truth for every Flect app while keeping the default experience as simple as one-click Undo and a quiet visual history. Git must protect the work, not become a review gate the user has to operate.

Dependencies

Builds on the live canvas in #32 and the canonical persistent workspace in #33. Import, sharing, and provenance features consume this contract.

Required behavior

• Keep one canonical source workspace shared by the agent, compiler, running canvas, history, and export.
• Create an automatic checkpoint after every valid change that becomes visible on the running canvas.
• Keep the last-known-good checkpoint active when a patch or build fails; failed attempts remain diagnostic context, not visible history entries.
• Present history as prompt/summary, time, and optional visual preview. Diffs and commit details are progressive disclosure.
• Make Undo, Redo, and Restore immediate and safe without asking the user to choose branches, stages, commits, or reset modes.
• Give the agent bounded Git tools for status, diff, checkpoint, restore, and export.
• Preserve an ordinary repository that can be opened with normal Git tooling at any time.
• Handle stale edits, concurrent tabs, storage quota, interrupted writes, and corrupt history without losing the last-known-good state.
• Internal refs, receipts, and recovery metadata may exist, but stay out of the main editing flow.

Acceptance criteria

• Fifty consecutive successful UI edits produce fifty ordered, recoverable checkpoints without blocking the composer or canvas.
• A failed edit leaves the running app and latest good checkpoint unchanged while giving the same agent actionable diagnostics.
• Undo and Redo update the running canvas in under 100 ms on the reference fixture without a full reload or state loss.
• History is understandable without Git vocabulary and opens directly to the relevant visible change.
• Restoring any of the last fifty checkpoints produces the exact source, assets, dependencies, and preview state recorded for it.
• The agent and running canvas always report the same workspace revision; stale tool results are rejected.
• Reload, offline reopen, multi-tab contention, quota pressure, and interrupted checkpoint tests preserve recoverability.
• Exported work opens as a normal Git repository with readable commits and no proprietary source format.
• No ordinary edit requires Keep, Reject, Review, Reset, branch management, or a manual commit.

Non-goals

• Exposing the full Git command model in the default UI.
• Requiring review approval before a valid local UI change appears.
• Replacing Git with a proprietary history database.
• Automatically pushing or sharing work without explicit user intent.

[robinbraemer]

Implemented and verified the first canonical OPFS/Git slice in the active worktree:

• pinned wasm-git@0.0.17 (libgit2 1.9.4) with locally bundled Asyncify Worker/Wasm and no runtime CDN/system Git dependency;
• Effect-owned, schema-decoded Git service with bounded paths/commands/files/archive sizes and scoped Worker lifetime;
• atomic guarded checkpoint/read transactions under Web Locks, with OPFS-to-MEMFS refresh before ref checks;
• accepted and proposal branches plus protected activation receipt; legacy revision-journal migration removes the old shadow snapshot;
• schema-safe Worker failure frames (Error subclasses cannot cross structured clone intact);
• protected UI action to export the complete ordinary repository including .git; and
• production Chromium proof for persistence/reload, branches, diff, conflict, rollback, export + native git fsck, actual Flect candidate persistence, and a two-page ref race where exactly one writer succeeds and the stale writer fails closed.

Still open: best-available Wasm variant selection, independently inspectable last-known-good ref, repository status/diff/history/repair in controller+AXI, role-bound git and OPFS filesystem brokerage in agent Bash, adversarial corruption/quota/symlink coverage, native packaged-app dogfood, import/round-trip, and final docs/gates.

Plan: docs/superpowers/plans/2026-08-01-flect-opfs-git-workspace.md.

[robinbraemer]

Progress proof (2026-08-01):

• Role-owned just-bash working mirrors now persist under isolated OPFS namespaces through the pinned Rifty VFS; production Chromium proved write, page restart, and read for the same role. OPFS unavailability retains the bounded memory fallback.
• The mirrors expose neither the canonical OPFS root nor .git, reject traversal and links, and retain separate App, Preview App, and Shaper namespaces.
• Added a schema-validated, expected-ref/guard-checked full source snapshot operation in the sole Git Worker. The real Wasm/libgit2 race diagnostic now reads back the winning checkpoint source while the stale page receives stale-ref.
• Added unshadowable, authenticated, role-bound embedded git inspection: status, branch, rev-parse, and log. Production Chromium proved Shaper observes its actual proposal branch and 40-character OID.
• Updated architecture, trust, README, implementation plan, and dated verification evidence.

Still open before this issue can close: bounded mirror-to-checkpoint diff/add/commit/restore; deletion and stale-parent semantics; adversarial quota/corruption/config/symlink coverage; repair UI/AXI; packaged macOS restart/offline proof; and import/round-trip continuation. Mutating or unsupported embedded Git commands continue to fail explicitly with exit 126.

[robinbraemer]

Browser-native authoring update (2026-08-01): Flect now persists isolated App, Preview App, and Shaper role mirrors in Rifty OPFS; exposes an unshadowable role-bound Git surface; and proves Shaper status, guarded add/commit on flect/authoring, restore, proposal propagation, acceptance, and ordinary-Git export in production Chromium. App Agent mutation remains denied. The exported accepted source and flect/authoring ref match. Patch-producing git diff remains explicitly open: the pinned wasm-git build accepted the command but emitted an empty patch in the browser proof, so the command was not exposed. Focused result: typecheck passed, 9 unit tests passed, and the real Chromium authoring/export test passed.

[robinbraemer]

New recovery edge found while proving compiled-capsule persistence (2026-08-01): after a page/worker restart, a previously persisted candidate and its shaping proposal restore correctly, but accepting that restored proposal can remove proposal metadata in the activation receipt without advancing the expected accepted snapshot commit. The pinned wasm-git@0.0.17/libgit2 build can leave the changed snapshot staged while git commit returns without moving the branch. Accept-before-reload works; accepted compiled-capsule reload/export and restored-candidate review/rejection are independently proven. Keep this acceptance path open under #25 until an observable regression reproduces the worker-restart sequence and proves protected activation either advances the accepted ref atomically or fails closed without consuming proposal state.

[robinbraemer]

2026-08-01 verification update:

First repository load now establishes a real built-in commit with matching accepted, last-known-good, and protected activation state before returning the workspace. This prevents an untouched reload from being misclassified as ref/receipt corruption while retaining fail-closed reconciliation. Real Chromium now proves Git-backed checkpoint, reload persistence, stale-writer rejection, full history export, and the corrected blank reload.

Full gate: 563 unit/integration tests (+1 intentional skip), 58 production-Chromium tests, 18 Rust tests, and successful local .app bundling. Broader adoption/export and packaged-host criteria remain open.