Skip to content

3C-A: curation-store OPFS/native byte adapter - #141

Merged
PhysShell merged 5 commits into
mainfrom
claude/curation-store-3c-a-opfs
Jul 19, 2026
Merged

PhysShell merged 5 commits into
mainfrom
claude/curation-store-3c-a-opfs

Conversation

@PhysShell

Copy link
Copy Markdown
Owner

What

The browser (and native) persistence adapter for the merged curation_store
domain model — step 3C-A of the OPFS curation flow, the analog of the CLI's
curation_fs (3B2) but for the cockpit. New module cockpit/src/curation_io.rs.

It reads and writes the store's canonical bytes — the same
encode_store/decode_store the CLI's native adapter uses (ADR-0027 §3, no
browser-specific wire schema
) — to a single OPFS file, curation/store.json.
Only the byte transport is per-target; the Missing-vs-malformed classification
and the format live in core. There is deliberately no trait abstracting this
over the native adapter — the shared contract is core's encode/decode, which
both call directly.

Shape

  • classify(StoreBytes) -> Result<StoreOnDisk, CurationStoreError> — the pure
    seam: Missing → typed absence (StoreOnDisk::Missing); Present(bytes) →
    decode_store, so a malformed store is a typed Decode refusal, never an
    empty store.
  • native (std::fs, desktop cockpit): load_store (NotFound → Missing,
    other read errors → Io) / write_store.
  • wasm (#[cfg(target_arch = "wasm32")]): opfs_load_store /
    opfs_write_store over OPFS curation/store.json, mirroring the existing
    opfs_save call sequence. An absent directory or file reads as
    StoreBytes::Missing; the write creates the dir + file and closes the writable
    stream.

Scope

Adapter only — no session, event minting, timestamps, or UI. Those are 3C-B
(the cockpit vertical flow). This slice is the storage seam it will sit on.

Validation

  • cargo test -p griff-cockpit --lib — 150/150 (5 new curation_io tests:
    missing→absence, valid→same store, malformed→typed refusal, canonical
    round-trip, native fs write/load/absence).
  • cargo clippy --workspace --all-targets + cargo fmt --check — clean.
  • wasm arm compile-verified for wasm32-unknown-unknown (a nix/clang build
    compiles griff-cockpit to object code; two real wasm-only bugs — a ? on an
    infallible Blob::text() Promise, and a redundant JsCast import — were
    caught and fixed this way). The residual zstd-on-wasm link is the guitarpro
    dependency's, handled by CI's cockpit-web-test, not this code.

3C-B (session + accept/reject UI + Playwright end-to-end) remains to come.

🤖 Generated with Claude Code

PhysShell and others added 2 commits July 19, 2026 06:24
The browser (and native) persistence adapter for the merged curation_store
domain model, as failing tests against stub bodies:

- a missing store location is StoreOnDisk::Missing, a typed absence;
- present valid bytes decode to the same store;
- present malformed bytes are a typed Decode refusal, never an empty store;
- canonical bytes survive a decode->encode round trip;
- native (std::fs) write-then-load round-trips and absence reads as Missing.

The adapter reads/writes the SAME encode_store/decode_store canonical bytes as
the CLI's native adapter (ADR-0027 §3, no browser-specific wire schema); only
the byte transport is per-target. classify + the native arm are stubs, so the
behavioral tests fail; the wasm OPFS arm and the real bodies land in green.

thiserror added to cockpit for the typed CurationStoreError.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NkqJUU6d1sW1RAfvyHrqVM
Implement the adapter so all five behavioral tests pass:

- classify: a missing location is StoreOnDisk::Missing (typed absence); present
  bytes decode through core::decode_store, so a malformed store is a typed
  Decode refusal, never an empty store.
- native (std::fs) load_store / write_store for the desktop cockpit: NotFound is
  Missing; any other read error is Io; a written store round-trips.
- wasm OPFS arm: opfs_load_store / opfs_write_store read and write
  curation/store.json in the Origin Private File System, mirroring the existing
  opfs_save call pattern. An absent directory or file reads as StoreBytes::Missing
  (the Missing-vs-malformed split stays in classify). The write creates the dir
  and file and closes the writable stream.

The store is the SAME encode_store/decode_store canonical bytes as the CLI's
native adapter — one wire format, two transports. No trait over the two adapters.

The wasm arm was compile-verified for wasm32-unknown-unknown (a nix clang build
reaches the link stage; the residual zstd-on-wasm link is the guitarpro dep's,
handled in CI, not this code).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NkqJUU6d1sW1RAfvyHrqVM
@coderabbitai

coderabbitai Bot commented Jul 19, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

@PhysShell, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 20 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: eb5004bd-504c-40ae-ada7-ff0010f92a57

📥 Commits

Reviewing files that changed from the base of the PR and between e3f3c1f and b4f513b.

📒 Files selected for processing (3)
  • cockpit/Cargo.toml
  • cockpit/src/curation_io.rs
  • cockpit/src/lib.rs
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch claude/curation-store-3c-a-opfs

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

PhysShell commented Jul 19, 2026 •

Copy link
Copy Markdown
Owner Author

Review verdict: HOLD — 3C-A needs one corrective

The placement and slice boundary are right: only cockpit/ changes, no StorageBackend trait, no 3C-B state/UI, and present bytes are decoded through core. Awaiting writable close() is also the correct completion boundary.

Four load-bearing issues remain:

1. OPFS lookup failures fail open as Missing

curation_dir(false) maps every rejected getDirectoryHandle to None, and opfs_load_store maps every rejected getFileHandle to StoreBytes::Missing.

That masks SecurityError, InvalidStateError, permission/storage failures, and implementation errors as “first launch; create an empty store.” Only a DOMException whose name == "NotFoundError" may become Missing; every other rejection must remain a typed storage/read error.

Required proof: a pure/testable classifier for JS lookup errors showing NotFoundError -> Missing and at least SecurityError -> error.

2. Blob::text() is not a byte transport

The store contract is canonical bytes, including the requirement that malformed bytes reach decode_store unchanged. Blob::text() decodes as UTF-8 and can replace invalid sequences; .as_string().unwrap_or_default() can additionally turn an unexpected JS value into empty bytes. Both mutate/collapse the evidence before core sees it.

Read with Blob::array_buffer() (or equivalent), copy the resulting Uint8Array to Vec<u8>, and propagate conversion failures. No lossy text conversion and no empty fallback.

Required proof: byte-seam test/helper demonstrating non-UTF-8 input is preserved byte-for-byte rather than normalized.

3. The write API bypasses encode_store

The module claims the browser adapter calls the same encode_store/decode_store contract as 3B2, but it imports only decode_store. Native write_store(path, bytes) and wasm opfs_write_store(String) accept already-produced payloads, so invalid/noncanonical bytes can be persisted through the public adapter API.

The public semantic write boundary must accept &CurationStoreV1, call encode_store, and expose a typed Encode(StoreEncodeError) distinct from transport failure. A private raw-byte transport helper is fine. The wasm helper must write those encoded bytes without converting them through a second JSON/text representation.

Required proof: invalid store is refused before transport; valid store writes the exact bytes returned by core encode_store.

4. The native cockpit arm creates a second, weaker native backend

std::fs::write truncates/writes the canonical file in place. That loses the pre-commit guarantees frozen in 3B2 and creates another native curation backend with weaker crash semantics. “No shared trait” did not authorize “duplicate native adapter, but less safe.”

3C-A is browser persistence. Remove the public native persistence arm (the pure classify seam can still be tested natively), or provide an explicit design that reuses the already-accepted 3B2 behavior without making cockpit depend on the CLI and without moving filesystem I/O into core. Do not retain fs::write as production desktop semantics.

Corrective scope

Keep it to cockpit/src/curation_io.rs unless dependency features are needed:

  1. classify only NotFoundError as absence;
  2. read/write raw bytes, no Blob::text()/String transport;
  3. semantic write calls core encode_store and returns typed Encode vs storage error;
  4. remove the weaker native production backend;
  5. add pure tests for DOM error classification and byte preservation, plus encode-before-write coverage;
  6. update docs/PR body to match the actual browser-only guarantee.

The local zstd linker issue is not a blocker for this corrective: exact-head cockpit-web-test is the authoritative full wasm link. 3C-B remains frozen until 3C-A is accepted and merged.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f914e8c0e3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

///
/// # Errors
/// [`CurationStoreError::Decode`] when bytes are present but do not decode.
pub fn classify(read: StoreBytes) -> Result<StoreOnDisk, CurationStoreError> {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Split the TDD commits

AGENTS.md at the repo root requires the red/green split and says Never commit new pub fn / pub struct implementation in the same commit as the tests that cover it. This commit adds the new public curation adapter implementation here and the covering curation_io tests in the same commit, so reviewers cannot verify the mandated red phase; split the failing tests and green implementation into separate commits.

Useful? React with 👍 / 👎.

Comment thread cockpit/Cargo.toml
serde_json = { workspace = true }
# Typed errors for the curation-store persistence adapter (3C-A), mirroring
# core's curation_store and the CLI's native adapter.
thiserror = { workspace = true }

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Commit the lockfile update for thiserror

This new workspace dependency is not reflected in Cargo.lock; after resolving this manifest, Cargo wants to add thiserror 2.0.18 to the griff-cockpit lockfile entry. Builds that use the checked-in lockfile (cargo ... --locked) cannot build this package from the commit as-is, so commit the generated Cargo.lock change with the manifest change.

Useful? React with 👍 / 👎.

Comment thread cockpit/src/curation_io.rs Outdated
let opts = web_sys::FileSystemGetFileOptions::new();
let handle = match JsFuture::from(dir.get_file_handle_with_options(FILE, &opts)).await {
Ok(handle) => handle.dyn_into::<web_sys::FileSystemFileHandle>()?,
Err(_) => return Ok(StoreBytes::Missing),

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Propagate non-missing OPFS load errors

getFileHandle can reject for real access/type errors as well as a missing file (MDN lists NotAllowedError and TypeMismatchError in addition to NotFoundError: https://developer.mozilla.org/en-US/docs/Web/API/FileSystemDirectoryHandle/getFileHandle#exceptions). In those cases, such as curation/store.json being a directory or OPFS read permission being denied, this returns StoreBytes::Missing, causing callers to bootstrap an empty store instead of surfacing that the existing store is inaccessible; inspect the DOMException name and only map NotFoundError to missing.

Useful? React with 👍 / 👎.

Comment thread cockpit/src/curation_io.rs Outdated
/// # Errors
/// [`CurationStoreError::Io`] if the write fails.
#[cfg(not(target_arch = "wasm32"))]
pub fn write_store(path: &Path, bytes: &[u8]) -> Result<(), CurationStoreError> {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Publish native store writes atomically

On native desktop, saving over an existing curation store with fs::write truncates the destination before writing the new bytes. If the process is interrupted or the write returns an error after truncation (for example, disk full), the previous decision store can be replaced by partial or empty JSON and the next load_store will hit Decode; stage to a sibling and rename, as the CLI curation adapter does, instead of writing the canonical file directly.

Useful? React with 👍 / 👎.

PhysShell and others added 3 commits July 19, 2026 06:46
…r (3C-A)

Corrective for the PR #141 review, testable half: a `encode` seam that routes a
store through core's canonical `encode_store`, so a write can never carry
non-canonical or invalid bytes. The stub serializes directly instead, so:

- encode_produces_the_canonical_bytes_not_a_second_serializer fails (a plain
  serializer keeps input order; the canonical encoder sorts/dedups);
- encode_refuses_an_invalid_store passes as a regression guard.

Also lands the scaffolding the green step needs: a typed Encode error variant,
the `DomException` web-sys feature (to tell a NotFoundError absence from any
other reject), and removal of the native production load_store/write_store —
that std::fs arm wrote straight to the canonical file, silently dropping the
crash/pre-commit guarantees the frozen 3B2 adapter provides; 3C-A is a browser
persistence slice, so the pure seam and its native tests stay while the weaker
native backend goes. The OPFS transport rewrite (NotFound-only absence, lossless
array_buffer read, encode-in-write) lands in green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NkqJUU6d1sW1RAfvyHrqVM
…C-A)

Resolve the four PR #141 correctives.

1. OPFS lookups no longer swallow every reject as absence. is_not_found checks
   DomException.name == "NotFoundError"; only that is StoreBytes::Missing. A
   SecurityError, InvalidStateError, or any other reject becomes a typed
   CurationStoreError::Io (with the DOMException message), never a silent
   bootstrap of an empty store.

2. The read is a real byte transport: Blob::array_buffer -> Uint8Array -> Vec<u8>,
   not Blob::text(). A UTF-8 text decode could rewrite malformed bytes before
   decode_store sees them, and the old unwrap_or_default() could turn an
   unexpected value into an empty store; both are gone.

3. The public write is semantic and validated: opfs_write_store takes
   &CurationStoreV1 and routes it through `encode` -> core encode_store, so an
   invalid store is a typed Encode error before any I/O and the transport only
   ever carries canonical bytes (write_with_u8_array over the encoded bytes).

4. The weaker native fs::write backend is gone (removed in red): it wrote
   straight to the canonical file, silently dropping 3B2's crash/pre-commit
   guarantees. 3C-A is browser persistence; the pure `encode`/`classify` seam
   stays native-tested, the degraded native backend does not.

The wasm arm was compile-verified for wasm32-unknown-unknown (nix/clang build
reaches the linker with no rustc errors; the residual zstd-on-wasm link is the
guitarpro C dep miscompiled to x86 by nix's clang-wrapper, unrelated, and links
in CI).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NkqJUU6d1sW1RAfvyHrqVM
…ve-arm removal

The header still described a native std::fs arm that green removed. State what the
module now is: a browser-only OPFS transport plus the pure encode/classify seam,
with durable native persistence left to the CLI's frozen curation_fs (3B2).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NkqJUU6d1sW1RAfvyHrqVM
@PhysShell

Copy link
Copy Markdown
Owner Author

Corrective for all four (RED 3937279 → GREEN 9fa673a, doc b4f513b)

1. OPFS lookups no longer swallow every reject as absence

is_not_found checks DomException.name == "NotFoundError" (new DomException
web-sys feature); only that is StoreBytes::Missing. A SecurityError,
InvalidStateError, or any other reject on the dir/file lookup becomes a typed
CurationStoreError::Io (carrying the DOMException message), never a silent
empty-store bootstrap.

2. The read is a real byte transport

Blob::array_buffer() → Uint8Array → Vec<u8>, not Blob::text(). A UTF-8
text decode could rewrite malformed bytes before decode_store sees them, and
the old unwrap_or_default() could turn an unexpected value into an empty store
— both gone. The bytes reach classify verbatim.

3. The public write is semantic and validated

opfs_write_store(&CurationStoreV1) routes through a new pure encode →
core encode_store, so an invalid store is a typed CurationStoreError::Encode
before any I/O; the transport only ever writes canonical bytes
(write_with_u8_array). New native tests:
encode_produces_the_canonical_bytes_not_a_second_serializer (RED→GREEN — a
plain serializer keeps input order, the canonical encoder sorts/dedups) and
encode_refuses_an_invalid_store.

4. The weaker native backend is gone

The std::fs::write arm wrote straight to the canonical file, silently dropping
3B2's crash/pre-commit guarantees. Removed. This is a browser persistence slice;
the pure encode/classify seam stays native-tested, the degraded backend does
not. The module doc was corrected to match.

On the wasm build

The rewritten arm was compile-verified for wasm32-unknown-unknown (a
nix/clang build reaches the linker with zero rustc errors on griff-cockpit,
exercising DomException, array_buffer, Uint8Array, write_with_u8_array).
As you noted, the residual zstd-on-wasm link is out of scope here — and it turns
out to be nix's clang-wrapper miscompiling the guitarpro C dep to x86 objects,
not this code; CI's toolchain links it.

Validation

  • cargo test -p griff-cockpit --lib — 151/151 (6 curation_io).
  • cargo clippy --workspace --all-targets + cargo fmt --check — clean.

Still HOLD — not merging.

@PhysShell
PhysShell merged commit 1631d49 into main Jul 19, 2026
15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant