Historical Folio plan review and completion audit #
Reviewed on 2026-09-27. Main artifact: implementation plan.
Historical audit: this review records the 2026-09-27 plan, not the current implementation. The 2026-10-11 replacement plan uses a remote snapshot plus at most one local base/value edit per record. It removes retained alternatives, publication states, and staged/sealed imports, and defers the stronger recovery guarantees discussed below. The old verdict, findings, numbered-section references, and verification evidence are preserved as history; they do not approve or verify the revised model.
Repository scope clarified on 2026-10-03: the store mirrors data the user can write to, within the user's repositories, and data the user cannot write to, outside those repositories. The user can have one public repository and a repository in each Space. Other users' accessible public and Space repositories are mirrored for reading. A repository is identified by its author's DID and optional Space URI; a shared Space spans separate author repositories, potentially on different PDSes. Local writes target only the authenticated user's repositories, with publication further limited by the app's granted permissions. Read-only replicas still receive local storage commits when remote data is pulled. The 2026-10-03 plan placed other authors' public replicas in 0.3 and Space replicas in 0.4 while keeping Pixl's first release focused on the user's public repository; those version assignments are historical. The historical review approvals below do not certify these later changes.
Verdict #
The plan is ready to implement. Three independent review tracks approved the final design: sync architecture/correctness, Pixl integration/API simplicity, and protocol/platform/release accuracy. The lead review checked the combined document for consistency and incorporated the user's final instruction to favor clearly defined actions over caller-managed validation and limits.
Approval applies to the plan. Browser performance, Wasm dependency compatibility, storage behavior, deployed PDS contracts, and installable language packages must still pass the release gates. No engine implementation, release, deployment, or live-account mutation was performed.
Findings resolved #
| Review finding | Final decision |
|---|---|
A client with put(key, value, ifVersion) exposes bookkeeping and makes normal concurrency a retry error. |
Use create, update(recordSnapshot, value), delete(recordSnapshot), and resolve(conflictSnapshot, choice). Folio owns versions and saves stale proposals durably. |
| One base/local/remote tuple loses an older editor's distinct base when a newer local edit already exists. | Retain the current sync edit and each proposal's own read snapshot/candidate inside the record conflict. Preserve all unresolved alternatives and return which outcome was saved. |
| Repeated editing would need a new read after every save. | Successful create/update returns the new snapshot; a conflicted save returns its conflict snapshot. Publication acknowledgements do not stale an unchanged visible record. |
| Record-only CAS allows a delayed A→B request to become valid after retry succeeds and the user undoes B→A. | Freeze the repository commit guard on every public attempt and preserve it across retries. Test the delayed original after retry and undo. |
| Lost responses, committed-then-500, and malformed success bodies can be mistaken for failed writes. | Preserve an uncertain attempt; reconcile before guarded retry. No exactly-once claim. |
| Clearing an accepted overlay too early exposes the older replica; a stale pull can falsely retire it. | Require a verified post-write pull with sufficient revision or tested authoritative read-after-write semantics. Keep the overlay if that pull cannot complete. |
| Deletion undo conflicts with snapshot-based update and ordinary absent reads. | create(key, restoredValue) follows the existing pending deletion/attempt, coalescing unsent work or waiting behind the in-flight outcome. Test delete→create and create→delete→create. |
| Async transaction callbacks do not map safely to IndexedDB/FFI. | Short internal compare-and-commit storage operations; no public callback transaction. |
| The proposed batch API added limits, pending-dependency errors, and group-resolution complexity before Pixl needed it. | Defer public atomic groups. Preserve the complete future design, including immutable operands and whole-group resolution, outside release prerequisites. |
| Strict Space creates do not supply the same delayed-request protection as public commit guards. | Expose supported actions/policy at setup and weaker uncertain-outcome behavior explicitly; never claim missing CAS protection. |
| Local metadata does not imply offline photos or offline navigation. | Stage photo bytes, preview locally, and add an app-owned offline shell at the Pixl-ready milestone. Remote-only thumbnails remain explicitly outside the first offline promise. |
| Saved conflict proposals could outlive their staged blob bytes. | Atomically pin available dependencies for both working edits and unresolved proposals. |
| React context cannot span Pixl's independent Astro islands. | One gallery/upload/delete React island with one Folio and QueryClient. |
| The first gallery migration could leave React paired with direct DOM removal/page reload. | Keep server actions temporarily but call them through React handlers and request a Folio pull after success. |
| Event/read races and missed tab hints can leave Query results stale indefinitely. | Subscribe first, track internal revisions, invalidate affected collections, and repair after resume. Live keyset pagination avoids stale-cursor errors. |
| Migration, key rotation, and storage upgrades were gated after writes already shipped. | Move identity recovery and uncertain-write tests before the first writable release; test every persistent schema upgrade. |
| A candidate Rust repository library was easy to mistake for a complete Wasm verifier. | Require an early real browser/dependency spike; explicitly verify signatures, bounded CAR handling, and runtime/Send compatibility. |
Requirement-by-requirement audit #
| Objective | Evidence in the saved plan |
|---|---|
| Consolidate the discussion | Sections 1–7 define the user's public/Space repositories for local writes and other users' replicas for reading, the local-first model, traits/bindings, four sync operations, persistent conflicts, React Query, blobs, identity, and recovery. Repository scope reflects the 2026-10-03 clarification; sections 10–11 record simplifications and deferred transactions. |
| Ground it in current code | Section 2 links the actual Folio skeleton and Pixl source, including the existing server OAuth, public image Lexicon, pagination gap, UI behavior, and baseline tests. |
| Reach Pixl quickly | Section 8 ships browser feasibility, cached gallery, safe single-record writes/deletes, then offline photos before Spaces or native packaging. |
| Provide clear implementation steps | Steps 1–25 are sequential, assigned to releases, and paired with observable consumer outcomes. The immediate task is steps 1–3. |
| Constrain the API through meaningful actions | Section 4 carries read/review context in immutable snapshots. No caller-managed CAS options, batch-limit knobs, stale-cursor recovery, or general query language. |
| Handle synchronization rough edges | Sections 5–6 and the section 9 scenario matrix cover crashes, late responses, uncertainty, undo, conflicts, missing coverage, migrations, identities, pages, and access. |
| Preserve ordinary ATProto compatibility | Canonical ordinary records and existing APIs; no mandatory CRDT schema, lock collection, Folio server, or app-specific merge contract. |
| Cover web, Node, Rust, Swift | Current crates remain; Wasm/IndexedDB first, SQLite/native Rust and Node next, Swift/UniFFI after, with package and behavior tests. |
| Adversarially review and simplify | Findings above were incorporated. Architecture, Pixl/API, and protocol reviewers all gave explicit final approval with no remaining blockers. |
| Store in Codex | Both Markdown artifacts are saved in the Folio workspace. Opening the main plan in this chat's Codex file panel was requested; the app returned queued. |
Evidence and verification boundary #
- Inspected the current Folio manifests/source and Pixl's actions, components, routes, configuration, installed auth boundary, and image Lexicon.
- Checked primary ATProto schemas/implementations at public
7a857989751ae31518509d69ab7194a922064f3dand Spaces787a730fcd22ed7791e2636beb509a943017ba1c, plus official browser, bindings, Astro, and TanStack documentation. Relevant source links are in the plan. - Pixl's read-only baseline test run: 10 passing, 3 failing. Failures are a contradictory null-alt assertion and two outdated MIME-message expectations. No fix was made during planning.
- Checked numbered steps, balanced code fences, trailing whitespace, local source links, and external source links. All source URLs checked returned HTTP 200.
- Verified the 14 preexisting Folio source/manifest/README files against hashes captured before writing the plan. They are unchanged. The added artifacts are documentation only.
- Did not run implementation/browser/live-PDS tests, generate Lexicons, change product code, install packages, commit, push, or deploy. Runtime tests in the plan are future acceptance requirements, not completed checks.