Explore a read-only FUSE projection over verified CAS content

[flyingrobots]

Outcome

Determine whether Keep can expose an admitted durable snapshot as a read-only FUSE filesystem while preserving the core law: every byte returned for a content identity is exact, or the read refuses.

Why this could matter

A filesystem projection would let ordinary tools navigate and read verified CAS content without teaching each consumer the Keep API. The useful product is a narrow compatibility adapter, not a mutable POSIX storage layer.

Dependencies

• Blocked by Build the durable crash-injection and recovery matrix #17: mounts require crash-safe opening and one explicit admitted recovery state.
• Blocked by ADR: define retention roots, release, and GC liveness #18 and Implement retention namespace generation transitions #19: mounted objects need explicit retention roots and release semantics so GC cannot invalidate a live mount.
• Informed by Implement precise verification reports and corruption refusal #20: FUSE error mapping must preserve precise verification and corruption refusals.

Required design questions

• Define the namespace: identity-addressed files, manifest/layout trees, named retained roots, or a deliberately limited combination.
• Prove how random reads satisfy the full-file BlobId contract; the existing narrower range-read receipt must not be silently upgraded into whole-blob verification.
• Define stable inode, size, timestamp, permission, and directory-order semantics without clocks, host-order iteration, or identity aliases.
• Bind every open handle to one immutable catalog and retention snapshot.
• Specify kernel page-cache and invalidation behavior across verification failure, recovery, retention release, and unmount.
• Preserve bounded memory and streaming reads; no hidden whole-blob materialization.
• Map missing, corrupt, ambiguous, and unsupported state to deterministic typed adapter errors and appropriate FUSE status codes.
• Audit the FUSE dependency, platform support, privilege model, unmount/recovery behavior, and crash surface.

Acceptance criteria

• A written ADR decides whether the adapter is viable and names its authority and verification boundaries.
• A read-only namespace contract has no writable, rename, truncate, link, metadata-mutation, or repair operations.
• Deterministic tests prove exact namespace ordering, inode stability, snapshot pinning, short/random reads, verification refusal, and unmount cleanup against a fake FUSE port.
• A Linux-only proof mounts a fixture when the environment supports FUSE and remains skippable without weakening normal CI.
• Benchmarks measure lookup latency, read throughput, verification work, allocations, and page-cache effects.
• No mount is exposed until durable recovery and retention pins are implemented.

Non-goals

• A writable filesystem.
• Treating paths, inode numbers, or kernel cache presence as content identity.
• Silent repair, partial trust, network filesystems, or cross-platform claims without dedicated evidence.

[coderabbitai]

🔗 Related PRs

#26 - Implement M1 Golden File Worldline identity [merged]
#54 - Define the durable segment store protocol [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!