alkfs/docs/research/phase-0.md

---
status: draft
last_updated: 2026-09-23 (initial draft from the setup discussion —
unconverged by design: every OQ is open, the POC register holds proposals
not results, and the prior-art pass is partial)
---

# alkfs — Phase 0 (Exploration)

This document captures Phase 0 (Exploration) for the `alkfs` crate: vision,
guiding principles, prior art, open questions (OQ-FS-01..NN), and the
candidate POC register. Phase 0's objective per `docs/sdd_process.md`:
*capture vision and guiding principles; research options; validate
approaches; converge on a recommended approach.* It is the input to Phase 1
(Architecture), where the Architect will produce `docs/architecture/`
specs, ADRs, and the open-questions tracker.

Drafted 2026-09-23 from the initial setup discussion. The crate is the
storage-engine member of the alk* family: alkcall (call + channels — the
substrate), alktty/alktunnels/alksocks (the protocol-crate siblings),
alkgit (the first in-family storage consumer, currently paused on exactly
the problem this crate exists to solve).

**Honest framing:** this Phase 0 is earlier in its lifecycle than
alksocks' was at the equivalent commit. There are more unknowns here than
in any sibling so far — a filesystem is both a storage engine (hashing,
chunking, durability, GC) and a serving protocol (verbs, sessions, wire
framing), and almost none of those decisions have empirical ground yet.
The POC register below is proposals, not results. Expect this document to
be rewritten several times before convergence.

## Vision and guiding principles

**One sentence:** a content-addressed, branch-aware virtual filesystem for
the alk family — a local storage engine (path-tree metadata +
content-addressed blobs) with a producer/consumer serving protocol on
alkcall channels, so that alkgit's object storage, the coming alksftp
door, and the alknet filesystem vision all compose on the same substrate —
and it never touches the host filesystem unless explicitly configured to.

**Why this crate exists.** The alknet mono-repo's filesystem research
(three POC iterations, 24 passing tests) proved a viable three-layer
architecture but lived inside a project with excessive scope. The alk*
family has since been decomposed and published (alkcall, alktty,
alktunnels, alkvault; alksocks and alkgit in flight). alkgit paused
because its storage problem — content-addressed blob storage with
branch/CAS semantics — is not a git-specific problem, and solving it
inside alkgit would leave alksftp and the alknet filesystem rewrite to
solve it again. The same basic "shape" recurs across the family:
git + git-lfs is small-object CAS metadata over big-blob content storage;
iroh-blobs' FsStore is inline-small/outboard-large; the alknet-filesystem
POC is SQLite path edges over a blob store. alkfs is that shape, made a
crate.

**Scope sketch (unconverged — this is the shape Phase 0 must confirm or
cut):**

1. **Storage engine half** — the path tree (paths, branches, snapshots,
   tombstones, cached sizes) in a transactional metadata store; content
   bytes in a content-addressed blob layer; write sessions
   (branch-on-write/merge-on-close); GC. Fully local, no channels
   required — a consumer embeds the engine in-process.
2. **Serving protocol half** — the producer/consumer pair on alkcall
   channels: a producer registers openable filesystem channels
   (`ChannelCore::register_openable`); a consumer opens them and speaks
   the file protocol inside. The `alk/fs`-shaped ALPN resource, the same
   "ALPN as a service" shape as alktty/alktunnels/alksocks.
3. **Doors stay out** — alksftp (SFTP door), FUSE/mount adapters, sync
   tools are separate crates/features that consume alkfs, per the family
   rule (alkgit vision: doors are family infrastructure, not crate
   contents).

Guiding principles, inherited from the alk* family plus the filesystem
research:

1. **No forced host-FS access — the defining requirement.** The analogue
   of alksocks' "never binds a port": the engine manages its own content
   store and never reads, writes, or mounts the host filesystem unless
   explicitly configured to. Every bridge to the real world (a blob-file
   store, an SFTP door, a mount, a sync tool) is an explicit, optional,
   feature-gated assembly shape. The engine itself is storage-agnostic
   about what backs its blob layer (filesystem files, SQLite, remote).
2. **Metadata/content split is load-bearing.** Small structured state
   (path edges, branch pointers, tombstones, sizes) lives in a
   transactional store; content bytes live under their hash in the blob
   layer. Path operations are O(path edges), never O(bytes) — rename is
   O(1) regardless of file size; identical content dedups across
   branches and paths by construction. This is the alknet-filesystem
   POC's core conclusion and the same shape as git + git-lfs and
   iroh-blobs' inline/outboard split.
3. **Content addressing with a durability contract.** Content is
   identified by its hash, not its path. The invariant that must survive
   every design choice: content is durable before any metadata row
   naming it commits; a crash mid-write leaves the old version intact
   and visible; no torn version is ever readable; no metadata commit
   orphans its content. Exact hashing/chunking is an OQ; the invariant
   is not.
4. **Branch-aware from day one.** Fossil-style branches (a branch is a
   parent chain + per-branch overrides + tombstones), branch-on-write/
   merge-on-close for the write path. This is what gives free
   multi-agent/multi-fork content sharing and the POSIX
   concurrent-reader-sees-old-version property — and it is the property
   git's object model needs (content shared across refs by hash).
5. **"ALPN as a service," not "a server."** The filesystem is a produced,
   ACL-scoped resource on a channels connection. The protocol never
   opens host files or binds anything; door-shaped conveniences (local
   loopback front door, in-process consumer handle) are optional
   assembly-layer shapes on either side. Producer/consumer vocabulary,
   never server/client.
6. **Substrate-agnostic protocol, native engine.** The file-protocol
   state machine is generic over `T: AsyncRead + AsyncWrite + Unpin`
   (fast-socks5/alksocks genericity precedent); the storage engine is
   native-only behind features (real FS I/O, SQLite). Whether the
   protocol layer itself stays wasm-clean is an OQ, not an assumption.
7. **Multi-tenancy is a where-clause, not an afterthought.** The POC's
   `bucket` column is the isolation unit; identity → bucket mapping is
   an assembly-layer auth question; per-path/per-bucket policy is a
   Phase 1 design question. A filesystem is arbitrary read/write by
   nature — the open gate and path-scope policy are the security
   boundary.
8. **Bounded resources on every serving path.** alkgit's ADR-009 posture
   (wall-clock, size, round limits) is the consumer shape this crate
   must serve; the serving protocol inherits alkcall's backpressure and
   channel-cap invariants rather than re-deriving them.

## What is already settled

The foundation is POC-validated and (upstream) ADR-pinned; this crate
does not start from zero. It inherits:

- **The channels substrate** — demux→Connection→handler→mux, the
  establishment story (`register_openable_with_establisher`, alkcall
  ADR-049; refused sessions are typed `channel:open_failed` call errors,
  never phantom channels), the identity seam (CF-005/CF-006: per-call
  opener identity on the open-op hooks), ACL-for-free via
  `register_openable`, the two-pump data plane (`channels::pump_bidi`,
  ADR-050 — use it, do not hand-roll), hub relay
  (`ChannelRelay`/`HubLegTemplate`, ADR-051). All production-validated by
  alktty/alktunnels/alksocks.
- **The metadata/content split, POC-proven.** alknet-filesystem POC
  iteration 1: SQLite path tree over a blob store, 8 tests — branch
  inheritance, tombstones, O(1) rename, bucket isolation, honker
  notify-atomic-with-mutation.
- **The write path, POC-proven.** Iteration 2: branch-on-write/
  merge-on-close reconciles "BLAKE3 must hash the complete file" with
  "writes arrive in chunks, possibly out of order" — concurrent readers
  see the old version until close() commits atomically; crash/abort
  leaves the old version intact. 7 tests.
- **The distributed-sync shape, POC-proven but scope-uncommitted.**
  Iteration 3: path tree as an automerge CRDT synced over QUIC; 9 tests;
  metadata and content sync separately; concurrent-root-map
  initialization is a real constraint (root structures must be created
  by one node and synced before others write). Whether any of this is
  alkfs v1 scope is OQ-FS-14.
- **The iroh-blobs store-seam findings (the external-store probe).** The
  alknet-blobs probe traced iroh-blobs 0.103's full `Command` actor
  surface: there is **no `Store` trait** — `Store` is a concrete struct
  over an `irpc::Client`; `MemStore`/`FsStore` are actors; a third store
  is a third actor speaking the pub `Command` enum. Blockers are a
  ~4-line visibility PR (`Store::from_sender`, `ref_from_sender`,
  `ApiClient`, the `Scope` field); GC (`run_gc`) is pub and reusable;
  ~120-160 lines of bao-tree glue must be re-implemented per store. The
  probe's cautionary half: `TempTags`/`TempTagScope` are sealed
  `pub(crate)` — sealed surface is exactly what turns "external store"
  into "fork" (AGENTS.md convention 13's cautionary example).
- **The consumer shapes this crate must serve.** alkgit's backend trait
  family (`docs/architecture/backend.md` there: `GitRefs`, `GitPackGen`,
  `GitPackIngest` — streaming pack generation/ingestion, CAS ref
  transactions, budgeted resources) and the russh-sftp `Handler` trait
  (the POC's near-1:1 SFTP↔PathTree mapping table). "Optimize for git
  and sftp-like" is the working posture.
- **The SQLite-as-application-file-format insight.** BLOBs < ~100KB are
  faster inline in SQLite than as filesystem files; atomic transactions
  over path-tree metadata; the schema is the documentation. iroh-blobs'
  FsStore discovered the same shape independently (redb inline tables +
  filesystem files). The inline-small/outboard-large hybrid is the
  metadata/content split at storage granularity.
- **The family conventions** — AGENTS.md in this repo (error handling,
  tokio subset, feature-gating, upstream posture, one-way doors) and the
  alkcall ADR set listed there.

## Prior art

### alknet-filesystem POCs — the direct ancestor

`/workspace/@alkdev/alknet/docs/research/alknet-filesystem/`
(`poc-summary.md`, `alknet-blobs-external-store-probe.md`), POC crates at
`/workspace/alknet-filesystem-poc` and `/workspace/alknet-fs-sync-poc`.
The three-layer conclusion (SQLite path tree + iroh-blobs content +
honker coordination) and the write-path resolution
(branch-on-write/merge-on-close) are this crate's inheritance, not prior
art to re-litigate — but *every dependency choice* in those POCs is open
again:

- **SQLite path tree** (`rusqlite` 0.39, bundled): `buckets`/`branches`/
  `paths`/`tombstones` + `write_sessions`/`write_chunks`; recursive-CTE
  chain walk resolves `(bucket, branch, path)` → content link in
  sub-millisecond time; only deltas are stored per branch.
- **iroh-blobs `MemStore`** as the content layer (deliberately not
  `FsStore` — no redb, no fsync rabbit hole in the POC).
- **honker-core** for notify-in-transaction (the transactional-outbox
  pattern built in): `SELECT notify(...)` inside the same transaction as
  a path-tree mutation; watchers wake on commit, not poll.
- **What did NOT transfer and why** — the POC's remaining unknowns
  (FsStore/redb coexistence, SFTP wiring, GC/tags, chain-depth perf,
  snapshot semantics) are this Phase 0's OQ list; the probe resolved the
  two-database question by reframing it (external actor, own SQLite
  file), and the redb question dissolves entirely if alkfs owns its blob
  metadata in its own store.

### iroh-blobs — the nearest CAS store (evaluated; not adopted as-is)

`/workspace/iroh-blobs` (v0.100 checkout) + published 0.103. `DESIGN.md`
is the best available treatment of the blob-store trade space (files are
hard: the bitfield/data/outboard write-ordering problem). What it gives:
BLAKE3 content addressing, bao-tree verified streaming (per-chunk
integrity with an outboard), dedup by construction, partial-range reads,
tags + mark-sweep GC, a hybrid store (small inline in redb, large as
filesystem files) — the same metadata/content split as principle 2.

**The known frictions (why the user called it "a pita" for git):**

- **The transfer protocol is welded to iroh/QUIC.** iroh-blobs' network
  story is an iroh `ProtocolHandler` speaking its own ALPN over QUIC. For
  alkfs this is irrelevant-by-design — content transfer rides alkcall
  channels — but it means iroh-blobs is at most a *local store*
  dependency, never the transfer layer. (The store side itself is
  transport-independent — that is what the Command-actor probe proved.)
- **Whole-file naming vs incremental writes.** BLAKE3/bao names a blob
  by the root hash of its *complete* byte sequence; you cannot compute
  the address until all bytes exist. Partial data can live under temp
  tags (`BlobStatus::Partial`) but cannot be pinned by its final hash.
  The POC's branch-on-write/merge-on-close is one reconciliation; chunk
  lists / Merkle-DAG naming is the other (OQ-FS-04). git escapes the
  problem structurally: objects are small and independently hashed;
  packs are the exception, and pack *generation* streams to a consumer
  that hashes on arrival.
- **Two-database coexistence** (redb for blob metadata + SQLite for the
  path tree): two WALs, two fsync paths, two crash-recovery stories —
  the POC summary's unknown #1, reframed by the probe ("neither fork nor
  coexist: a third store actor with its own single SQLite file"), and
  dissolvable entirely if alkfs owns blob metadata in its own store
  (OQ-FS-02/03).
- **Sealed internals** (`TempTags`, the `BaoTreeSender`) — the probe's
  fork-vs-PR calculus. Third-party upstream, not ours, never will be
  (AGENTS.md convention 17).

### git + git-lfs — the shape to optimize for

The user-level framing this crate must honor: "the same basic shape
exists with git + gitlfs as with how iroh's blobs handled the mix of
small and large blobs." git itself is the small-object CAS: every object
individually hashed, refs are names over hashes, content shared across
refs/branches for free, rename is metadata-only. git-lfs is the large-blob
sidecar: content-addressed pointer rows in the tree, bytes in a separate
content store (rudolfs is the family's reference server for that half —
namespace/bucket isolation, LRU cache decorator, fanout streaming). The
alkfs analogue: the metadata layer *is* git's object/ref shape; the blob
layer *is* the LFS store; small content can inline into the metadata
store exactly as iroh-blobs inlines small blobs into redb. Whether
alkfs's engine API makes alkgit's gix-odb backend an implementation
detail of alkfs (or leaves gix-odb native and serves only the
general-FS shape) is OQ-FS-12 — the highest-stakes scope question in
this document.

### alkgit — the first consumer

`/workspace/@alkdev/alkgit` — paused on the storage problem. Its backend
doc (`docs/architecture/backend.md`) pins the seam: five traits
(`GitRegistry`, `GitRegistryStore`, `GitRefs`, `GitPackGen`,
`GitPackIngest`), kept small/orthogonal/substrate-blind after the
alknet-blobs sealed-surface lesson. The properties alkfs must serve
efficiently: streaming pack generation (O(counts) memory, blocking-thread
friendly), streaming pack ingestion (budgeted, fsck/connectivity report),
CAS ref transactions, registry records with grants. Its research
(`docs/research/gitoxide.md`, `poc2-findings.md`) carries the gix-odb
API contract notes — including the durability shape (pack bytes durable
before the ref transaction that names them commits) that mirrors
principle 3 exactly.

### russh-sftp / alksftp — the door shape

`/workspace/russh-sftp` (read-only reference): the `Handler` trait is a
near-1:1 mirror of POSIX syscalls as SFTP packets, and the POC mapped
every op onto the PathTree + WriteSession API (open→resolve or
WriteSession::open; write→write_chunk with offset as key; close→hash+
merge+notify; readdir/list_dir; stat→indexed row — cheaper than a real
FS fstat; rename→O(1) edge move). The client's `File` already implements
`AsyncRead + AsyncSeek + AsyncWrite` with pipelined writes. alksftp (the
coming family crate) would speak this verb set; whether alkfs's serving
protocol adopts SFTP-shaped verbs natively or defines its own framing
that alksftp translates is OQ-FS-08. The alknet-tty async-IO adapter
patterns (AsyncWrite-over-mpsc, kill-on-drop) are reusable for the write
bridge.

### SQLite (application file format) + honker

https://sqlite.org/appfileformat.html — the insight that anchored the
POC. honker (`/workspace/honker`, `honker-core` 0.2.4) supplies
notify/locks/queues as SQL functions on *your* connection — the
transactional-outbox property. Caveats: honker is third-party (not ours,
convention 17), single-machine by explicit design ("two servers writing
the same .db over NFS is not a Honker deployment strategy"), and its
scope in alkfs is an OQ (notify-on-commit may be the only load-bearing
piece — locks/queues/scheduler may be excess).

### rudolfs — the git-lfs server reference

`/workspace/@alkdev/alknet/docs/research/references/gitlfs/
rudolfs-reference.md`: `StorageKey = (Namespace, Oid)` tenant isolation;
the decorator composition `Verify ↔ Encrypted ↔ Cached ↔ Retrying(Disk →
S3)`; LRU cache in front of permanent storage; `fanout()` streaming to
client and cache simultaneously. The cache/permanent split and the
fanout pattern are the production-shape references for alkfs's blob
layer and its serving read path.

### Anti-prior-art (what NOT to carry over)

- **The alknet mono-repo's scope.** The filesystem research is inherited
  as *findings*, not as a code path; the crate stays small per the
  decomposition discipline (alksocks' "socks + channels, nothing else"
  resolution is the template — alkfs's version is OQ-FS-01).
- **iroh-blobs' transfer protocol as the content path.** Content
  transfer rides alkcall channels, full stop; an iroh/QUIC side-protocol
  would fork the family's transport story.
- **iroh-blobs' FsStore partial-file lifecycle as a requirement.** Its
  749-line `bao_file.rs` partial-blob-on-filesystem machinery exists
  because redb/filesystem is its substrate; a SQLite-inline store (POC
  write_chunks) or an alkfs-owned blob store has no need for it.
- **gix-odb's layout as alkfs's layout.** Loose-objects + packfile
  directory layout is git's on-disk contract; alkfs is a general
  engine. If alkgit keeps gix-odb native, alkfs serves the general shape
  and git storage stays in alkgit (OQ-FS-12).
- **NFS-style shared-file multi-node assumptions.** honker's own warning
  applies to the whole engine: single-machine local state first;
  distribution is an explicit layer (OQ-FS-14), not an ambient property.

## Open Questions

These are the design questions Phase 0 must resolve (or explicitly
defer) before the architecture spec. Numbered OQ-FS-01.. so they can be
referenced, tracked, and promoted into `docs/architecture/
open-questions.md` in Phase 1. Status is open unless stated; the point
of this document is to hold the reasoning without forcing premature
decisions. Grouped by theme; numbering is stable across reorganizations
(do not renumber — findings files and commits reference these ids).

### Core architecture

#### OQ-FS-01: Crate scope — what lives in alkfs?

The component split (§Vision) is a sketch, not a decision. Questions to
converge on:

- One crate with engine + serving protocol (feature-gated apart), or
  engine and protocol as separate crates (the alkcall registry/protocol
  split precedent)? The engine must be embeddable in-process without
  channels (alkgit's use case); the protocol must be usable without the
  default storage engine (an embedder with its own backend).
- Is there a backend trait seam at all (the alkgit `GitRefs`-family
  pattern: traits in-crate, implementations behind features), or is the
  storage engine simply *the* implementation with the protocol generic
  over a small handle type? The sealed-surface lesson
  (`alknet-blobs-external-store-probe.md`) says: decide this *before*
  consumers exist; it is a one-way door.
- What is explicitly out: doors (alksftp, FUSE, mount), sync tooling,
  UI/registry applications, the alknet rewrite's client stack.

#### OQ-FS-02: Metadata store substrate — and is blob metadata in the same file?

The POC used `rusqlite` (bundled) for the path tree and it worked well
(schema-as-documentation, recursive CTEs, BLOB columns at chunk
granularity). Open sub-questions:

- SQLite/rusqlite vs redb vs something else for the path tree. The POC
  evidence favors SQLite (honker integration, transactional outbox,
  sub-ms resolves); redb buys a lighter footprint but loses SQL and the
  honker seam.
- The **one-file-vs-two question**: if alkfs owns the blob layer too,
  blob metadata (hash index, sizes, refcounts/liveness) can live in the
  *same* SQLite file as the path tree — one WAL, one commit boundary,
  and the durability ordering of principle 3 becomes a single
  transaction instead of a cross-store fsync dance. The probe's
  external-actor shape (iroh-blobs with its own store) vs an alkfs-owned
  store decides whether this is even on the table. Small content can
  then inline as BLOBs (the appfileformat sweet spot) — possibly making
  the "blob store" a layer *inside* one database with file-backed
  spill-over for large content (the iroh-blobs FsStore hybrid shape).
- Concurrency model: single writer connection + reader pool? WAL
  settings (`synchronous=NORMAL` vs `FULL`) as a durability-vs-throughput
  knob? What is the honest fsync contract per operation class?

#### OQ-FS-03: Blob substrate — reuse iroh-blobs, own the store, or hybrid?

Three live options, shaped by the probe:

- **(a) Consume iroh-blobs as a store** (implement the `Command` actor
  externally per the probe; 4-line upstream PR; ~120-160 lines of bao
  glue) — gets BLAKE3+bao verified streaming, GC, tags for free; pays
  the iroh-blobs/irpc dependency weight, the sealed-`TempTags`
  fallback (self-managed liveness), and still needs the metadata-store
  coexistence story (OQ-FS-02). Also carries `bao_tree` version-tracking
  as the maintenance surface.
- **(b) Own the blob store.** BLAKE3 (`blake3` crate) + bao
  (`bao_tree` crate) directly, alkfs-owned storage layout — full control
  of durability ordering (principle 3 becomes enforceable in one
  transaction with OQ-FS-02's single-file shape), no sealed surfaces, no
  iroh-blobs dependency. Cost: re-derive verified-streaming import/
  export (the glue the probe measured), GC, partial states — the
  pieces iroh-blobs already solved, now ours to keep correct.
- **(c) Hybrid/no-bao start.** Whole-file BLAKE3 + a simple file-per-blob
  or SQLite-inline store first, add verified streaming (bao outboards)
  when a consumer needs range verification. git's own objects are small;
  packs are written-once-then-verified-by-consumer. Honest question:
  does any alkfs v1 consumer actually need per-chunk bao verification on
  the read path, or is end-to-end TLS + hash-check-on-close sufficient?

The deciding inputs: the alkgit workload (pack-sized blobs, streaming),
the sftp workload (range reads, seek), and how much of iroh-blobs'
surface survives contact with "no iroh/QUIC transfer."

### Write path, branching, GC

#### OQ-FS-04: Hashing and chunking — whole-file addresses vs chunk DAGs

The load-bearing storage-format question (a one-way door once content
exists in the wild):

- **Whole-file BLAKE3 (+ bao outboard for verified streaming).** Simple,
  git-shaped, matches the POC and alkgit's objects; but the address
  doesn't exist until the write completes (staging required — the
  branch-on-write answer), no partial availability under a final name,
  no cross-file chunk dedup (two 1GB files sharing a 500MB prefix
  dedup zero bytes).
- **Chunk-list / Merkle-DAG addressing** (content-defined or fixed-size
  chunks; the file "name" is a root hash over chunk hashes, iroh-blobs
  style): dedup at chunk granularity, partial availability, resumable
  writes under a stable name, cheap append; but bigger metadata, a
  chunker to pin down (CDC boundary-shift sensitivity), and whole-file
  identity becomes "same root hash" rather than "same bytes hash" (root
  hash equality still implies byte equality with bao-style trees, at
  hash-of-chunk-hashes cost).
- **Hybrid** (the git-lfs/iroh shape): small content inline/whole-hash;
  large content chunked. Threshold policy is a knob; the *format* split
  is the one-way door.

Sub-questions: CDC (rollsum/buzhash) vs fixed-size vs BLAKE3's native
chunking (`bao_tree`'s chunk size); where chunk indices live (metadata
store rows vs outboard files); whether chunk dedup across *files* is a
v1 requirement or a defer-able nicety; interaction with OQ-FS-05 (a
chunk-DAG write can commit incrementally, weakening the branch-on-write
staging argument).

#### OQ-FS-05: Write path semantics beyond the POC

Branch-on-write/merge-on-close is POC-proven for the happy path. What
Phase 0 must still answer:

- **Durability details** — per-chunk transaction commit (POC shape) vs
  batched WAL; `synchronous` level; whether fsync of spilled large
  content must precede the path-row commit (principle 3) and how that
  is ordered when content lives outside the DB file; crash-mid-close
  behavior.
- **Concurrency** — the POC left honker named locks unwired; concurrent
  writers to the same path need a real policy (last-close-wins is
  session-safe but not POSIX; O_EXCL-ish create semantics; advisory
  byte-range locks for the sftp door?).
- **Streaming large writes** — pack generation and 1GB+ uploads: the
  POC's per-chunk SQLite rows are proven at ~32KB×1MB; the pack-size
  regime needs a spill story (OQ-FS-02's file-backed overflow) and a
  backpressure story inherited from alkcall channels.
- **Sparse/out-of-order/ftruncate** — SFTP pipelines out-of-order
  (proven); sparse files and explicit truncation/extend are
  unaddressed.

#### OQ-FS-06: Branch/snapshot/commit model

The POC has Fossil-style branches (name → parent chain + deltas) but no
explicit commit/snapshot op — writes to a branch are immediately visible
on that branch. Open questions:

- Is a snapshot a new branch (Fossil's model — maps naturally to the
  chain walk) or a recorded point-in-time within a branch (git's model)?
  What do alkgit (refs + CAS) and the sftp door each need?
- Refs as a first-class concept: alkfs stores `refs` rows naming commits
  (branch heads), enabling CAS ref transactions (alkgit's
  `GitRefs::apply` shape) over the same metadata store. Is the ref
  namespace git-shaped from day one, or a later addition?
- Merge semantics across branches: the POC has none (branch-on-write
  collapses trivially at close). Real merges (three-way? automerge-CRDT
  for the metadata layer per POC 3?) are presumably out of v1 — say so
  explicitly rather than leaving it implied.
- Chain-depth performance: the recursive CTE degrades on deep chains
  (POC unknown #6); resolve-cache/materialized-view shape if needed —
  perf probe before spec, or accept and document.

#### OQ-FS-07: GC and liveness

Content is shared across branches/paths by hash, so naive per-path tags
(Poc unknown #5's iroh-tags shape) break sharing — deleting a path must
not collect content another path/branch still names. The candidate
shape: **liveness = reachability walk** (mark from all live branch heads
+ refs + write sessions; sweep unreachable) — a metadata-store query
over path rows, no separate tag table needed if blob liveness rows are
refcounted or mark-computed at GC time. Sub-questions: incremental vs
stop-the-world GC; tombstone retention (content behind tombstones is
unreachable-but-recent — grace windows); orphaned write-session chunk
reaping (crash cleanup, the POC's known orphans); cross-bucket sharing
(never — buckets are tenants).

### Serving protocol

#### OQ-FS-08: The file protocol over channels — verbs, sessions, framing

The biggest unspecced surface, and the crate's first real wire format
(one-way door — ADR before the first consumer):

- **Verb set.** SFTP-shaped (the russh-sftp Handler mapping is proven
  1:1 against the engine) vs a leaner custom set (open/read/write/
  close/stat/readdir/rename/remove + extended ops). Working posture:
  SFTP-shaped verbs, SFTP-versioned semantics where it matters
  (handles, pipelined writes, `SeekFrom::End` cheapness).
- **Session model.** One channel per file session (alksocks' one-channel-
  per-CONNECT shape) vs one control channel multiplexing many file
  handles (the alktty demux shape). A directory traversal or a git clone
  opens *many* files; per-file channels spend channel IDs and opens
  (the 256-cap arithmetic, OQ-SK-09's twin); a multiplexed control
  channel reintroduces the demux trade alksocks resolved *for SOCKS5*
  (whose RFC structure genuinely has one command per connection — a
  file protocol has no such constraint). This trade has different
  physics here than it had there; no inherited answer.
- **Framing on the data path.** If sessions are multiplexed, requests
  need IDs and payloads need framing (length-prefix + request-id — the
  one-way door). If per-session, the payload may be near-pass-through.
  Chunk sizes, backpressure (bounded buffers are inherited), and
  flow-control for pipelined writes all live here.
- **Read-path streaming.** Range reads (offset+len), EOF semantics,
  verified-streaming vs trust-the-store; zero-copy ambitions explicitly
  out (channels are the substrate, not splice(2)).
- **Establishment.** `register_openable_with_establisher` with a scope
  gate (OQ-FS-10); refused opens are typed errors with per-verb error
  mapping (SFTP status codes at the door, faithful engine errors in
  protocol — convention 2).

#### OQ-FS-09: ALPN, params, and the resource model

Provisional `alk/fs` (final naming per alkcall ADR-004/006 convention).
Open sub-questions (mostly Phase 1 ADRs with Phase 0 ground):

- The params-object shape (ADR-039 precedent: ALPN-specific, interpreted
  by the open handler) — what identifies a produced filesystem resource?
  (bucket? branch? scope string? limits?)
- In-process and loopback consumers: the engine half must be directly
  embeddable (no channels) — the protocol layer is one substrate among
  several, generic over `T` (principle 6). The in-process shape is also
  the test seam, the alksocks POC pattern.
- Hub relay story: a filesystem resource traverses relays
  terminate-and-re-produce like any produced resource; nothing
  alkfs-specific expected — verify during POC rather than assume.

#### OQ-FS-10: Doors — alksftp, mounts, sync (out of crate, but shapes the API)

Family rule: doors are separate crates/features. Phase 0's job is to
keep the protocol layer door-ready: the verb set (OQ-FS-08) must map
onto russh-sftp's `Handler` without translation loss; a FUSE/mount door
needs POSIX-ish error mapping and inode-ish handle semantics — do not
design for FUSE in v1, but record what it would demand so the protocol
doesn't preclude it. Directory-sync tooling (alkfs ↔ host dir) is the
explicit, feature-gated host-FS bridge if/when wanted — never ambient.

#### OQ-FS-11: Multi-tenancy, identity, and path-scope policy

Buckets are the isolation unit (POC-proven free). Open questions: the
`ALKFS_OPEN_SCOPE`-shaped scope gate (alktty/alksocks precedent) — does
scope name buckets, path prefixes, or both; identity → bucket mapping
at the assembly layer (vault references, never plaintext secrets —
family rule); per-path/per-bucket policy as a producer-side policy
callback vs declarative ACL (alksocks OQ-SK-05's dialer-refuses
resolution is the evidence-backed template); write-vs-read grant
separation (a read-only bucket mount is the obvious first split).

### Consumer fit

#### OQ-FS-12: alkgit fit — the question that un-pauses alkgit

The first consumer and the reason this crate moved ahead of alkgit. The
decision tree:

- **(a) alkgit keeps gix-odb native; alkfs serves the general FS.**
  Lowest integration risk; but then alkfs doesn't solve the problem that
  paused alkgit, and the family carries two storage stories.
- **(b) alkgit's backend traits get an alkfs-backed implementation.**
  `GitPackGen` streams a pack *out of* alkfs content (pack assembly is
  alkgit-side; the blob bytes come from alkfs reads);
  `GitPackIngest` streams a pack *into* alkfs (each unpacked object
  lands as content; refs land as metadata rows); `GitRefs` becomes
  CAS transactions over alkfs refs. gix-odb's on-disk layout disappears;
  git semantics ride alkfs's content addressing. This is the "optimize
  for git" path and the probable answer — but it makes alkgit's
  workload (pack-scale blobs, O(counts) memory, streaming) the
  benchmark OQ-FS-13 must meet.
- **(c) gix-odb *on top of* alkfs** (an odb backend where loose
  objects/packs are alkfs files) — keeps gix-odb's pack machinery but
  treats alkfs as the disk. Probably the worst of both: gix-odb assumes
  filesystem semantics alkfs won't natively provide (mmap, file locks).

Sub-questions: does git's object-id namespace (sha1/sha256) coexist with
alkfs's content addresses (path rows mapping git-oids → alkfs hashes,
dedup at the alkfs layer); CAS ref transaction shape; whether pack
ingestion budget enforcement (alkgit ADR-009) maps onto alkfs write
sessions.

#### OQ-FS-13: Performance shape and budgets

No numbers exist yet. What Phase 0 should collect (empirically, via the
POC register) so Phase 1 can pin budgets: path-resolve cost at realistic
branch depths (POC: sub-ms in-memory; chains of 10+?); small-file
throughput (the inline-BLOB sweet spot claim vs reality at 4KB metadata
ops); large-file write throughput through chunked sessions; pack
gen/ingest streaming rates over a channel vs native gix-odb; memory
bounds under the alkcall channel caps. The alkgit ADR-009 limits shape
is the consumer contract to serve.

### Posture and deferred

#### OQ-FS-14: Distributed sync / multi-node — in scope at all?

POC 3 proved automerge-CRDT sync of the path tree (9 tests, LWW
conflicts, the concurrent-root-init constraint) with content fetched
separately. But sync is a product-layer concern that may not belong in
the engine crate: the family pattern is composition (alkcall relay for
transport, automerge as a third-party sync layer, honker queues as the
local outbox). Working posture: **deferred — out of v1 scope**, recorded
so the metadata schema doesn't preclude it (branch/paths rows are
already CRDT-encodable per POC 3's document structure). Revisit when a
consumer needs multi-node.

#### OQ-FS-15: WASM posture

The expected shape (convention 4): wasm-clean protocol/ops layer; native
storage engine behind features (real FS/SQLite never compiles to
wasm32-unknown-unknown). Open: does any consumer actually want the
protocol layer in wasm (a sandboxed alkfs consumer, mirroring alksocks'
sandboxed-SOCKS-consumer story)? If none is in sight, the honest answer
may be alkhttp-style native-only (the "wasm-clean is preferred, not
mandatory" precedent) — but the protocol layer being wasm-clean by
construction costs little if the engine split exists anyway. Decide
deliberately once the split (OQ-FS-01) exists; verify with
`cargo check --target wasm32-unknown-unknown`.

## Candidate POC register (proposals — none run yet)

POC placement conventions (inherited from alktunnels/alksocks): a POC
needing this repo's code runs in a worktree (`.worktrees/research/
<task-id>/` per `docs/sdd_process.md`); a self-contained POC runs as a
standalone crate in the global workspace with findings written into
`docs/research/` here. Findings always land in `docs/research/`.

| # | Candidate | Hypothesis to validate | Feeds |
|---|---|---|---|
| 1 | Engine skeleton: path tree + inline-blob store in one SQLite file | One-file metadata+blob-metadata (OQ-FS-02) holds up under the POC's 15-test suite ported over; single-transaction durability ordering (principle 3) is expressible | OQ-FS-02, OQ-FS-05 |
| 2 | Write path at pack scale | Chunked write sessions handle 100MB+ streams (spill-to-file regime) with correct durability ordering and crash-abort semantics | OQ-FS-05, OQ-FS-13 |
| 3 | Blob substrate bake-off (narrow) | (a) iroh-blobs external actor vs (b) own blake3/bao store vs (c) inline-hybrid: measure integration cost, GC story, sealed-surface fallout against the probe's predictions | OQ-FS-03 |
| 4 | Chunking probe (paper + micro-bench) | Whole-file vs chunk-DAG: dedup gains on realistic workloads (git packs, agent workspaces), write-path impact, metadata size — enough to decide the format one-way door or at least stage it | OQ-FS-04 |
| 5 | Serving protocol spike | SFTP-verb protocol over channels: per-file-channel vs multiplexed-handles session model, open cost at directory-walk and git-clone fan-out, framing sketch (not a wire ADR) | OQ-FS-08, OQ-FS-09 |
| 6 | alkgit seam spike | `GitPackGen`/`GitPackIngest` shaped against an alkfs-backed engine on the POC's API — does the trait family survive contact; where do git oids map | OQ-FS-12 |
| 7 | GC walk prototype | Reachability-mark GC over path rows + refs: correctness on shared content across branches, cost model, orphaned-session reaping | OQ-FS-07 |

Order is indicative, not committed: #1/#2 de-risk the engine core;
#3/#4 resolve the storage-format one-way doors; #5/#6 are only worth
running once #1 exists (the protocol needs an engine to serve). The
register exists so POC work has home ids; expect entries to be split,
merged, or dropped as OQs sharpen.

## Survey / prior-art list

Read/verified (cited above):

- alknet-filesystem POCs —
  `/workspace/@alkdev/alknet/docs/research/alknet-filesystem/
  poc-summary.md`, `alknet-blobs-external-store-probe.md`; POC crates
  `/workspace/alknet-filesystem-poc`, `/workspace/alknet-fs-sync-poc`.
- iroh-blobs — `/workspace/iroh-blobs` (v0.100 checkout + `DESIGN.md`),
  published 0.103 in cargo cache (probe source); the family's reference
  notes at `/workspace/@alkdev/alknet/docs/research/references/iroh/
  iroh-blobs/` (overview, key types, transfer protocol, storage).
- alkgit — `docs/architecture/backend.md` (the trait seam),
  `docs/research/{vision,gitoxide,git-protocol,poc2-findings}.md`.
- russh-sftp — `/workspace/russh-sftp` (`server/handler.rs`, client
  `File` pipelining).
- SQLite appfileformat — https://sqlite.org/appfileformat.html; honker
  — `/workspace/honker` (`honker-core` 0.2.4).
- rudolfs (git-lfs server) —
  `/workspace/@alkdev/alknet/docs/research/references/gitlfs/
  rudolfs-reference.md`.
- alkcall — ADRs 034/035/036/037/039/042/049/050/051, ledger
  CF-005/CF-006 (`docs/architecture/decisions/`); alktty/alktunnels/
  alksocks Phase 0 docs as the format/template precedents.

To evaluate (research-specialist queue, feeding the OQs named):

- **Chunking/CDC prior art** — FastCDC, rollsum (bup), rsync-style
  boundaries; `bao_tree`'s BLAKE3 chunking as the default candidate
  (OQ-FS-04).
- **CAS filesystems** — Plan 9 fossil+venti (the branch/CAS ancestry the
  POC name-checks), IPFS unixfs/iros DAG shapes, OST/lessfs-style
  inline-vs-outboard hybrids (OQ-FS-04, OQ-FS-06).
- **git storage internals** — gix-odb pack/idx layout and
  `gix-pack::data::input` streaming (alkgit research has the survey;
  re-read for OQ-FS-12's object-id/namespace questions).
- **SQLite durability posture** — WAL + `synchronous=NORMAL` vs `FULL`
  under the commit-boundary contract; SQLite-as-blob-store limits
  (OQ-FS-02, OQ-FS-05).
- **FUSE/mount doors** — rust bindings shape, POSIX semantics alkfs
  would need to fake (OQ-FS-10; defer design, record constraints).

## Convergence checklist (what Phase 0 must produce)

- [ ] Vision + guiding principles captured (this doc, §Vision — the
      scope sketch needs confirmation or cutting, OQ-FS-01)
- [ ] Prior-art pass complete: alknet-filesystem POCs re-read and
      mapped (done); iroh-blobs surface re-verified against the probe's
      0.103 findings; git/git-lfs shape pinned against alkgit's backend
      contract; CDC/chunking survey (OQ-FS-04 input); CAS-filesystem
      survey
- [ ] OQ-FS-01 (crate scope) — converged: engine/protocol split, trait
      seam or not, explicit non-goals
- [ ] OQ-FS-02 (metadata store) — converged: substrate, one-file-vs-two
      (blob metadata placement), durability knob
- [ ] OQ-FS-03 (blob substrate) — converged: consume iroh-blobs vs own
      the store vs hybrid (POC #3)
- [ ] OQ-FS-04 (hashing/chunking) — converged: the storage-format
      one-way door (POC #4)
- [ ] OQ-FS-05 (write path) — durability/concurrency/spill semantics
      pinned (POC #2)
- [ ] OQ-FS-06 (branch/snapshot/refs) — model chosen; ref namespace
      decided; merge explicitly in-or-out of v1
- [ ] OQ-FS-07 (GC) — liveness shape chosen; retention/reaping policy
      pinned (POC #7)
- [ ] OQ-FS-08 (file protocol) — verbs, session model, framing sketch;
      the wire ADR itself is Phase 1's (one-way door, first consumer in
      sight) (POC #5)
- [ ] OQ-FS-09 (ALPN/params) — naming + params ground collected; ADR
      in Phase 1
- [ ] OQ-FS-10 (doors) — protocol kept door-ready; nothing designed in
- [ ] OQ-FS-11 (tenancy/policy) — scope-string + policy shape settled
- [ ] OQ-FS-12 (alkgit fit) — the (a)/(b)/(c) decision made; alkgit
      un-pause plan written (POC #6)
- [ ] OQ-FS-13 (budgets) — numbers collected; budget table drafted
- [ ] OQ-FS-14 (sync) — explicitly deferred or scoped with evidence
- [ ] OQ-FS-15 (wasm) — decided once the engine/protocol split exists
- [ ] Targeted POCs run + findings in `docs/research/`
- [ ] Converge: recommended approach written up, ready to hand to the
      Architect for Phase 1