alknet/docs/research/alknet-filesystem/alknet-blobs-external-store-probe.md

alknet-blobs: External SQLite Store — Command-Surface Probe

Status: Probe complete. The external-crate path (no fork) is feasible. The required upstream change is a ~4-line visibility-widening PR with zero logic changes. Date: 2026-07-08 Scope: Resolves open question #1 from poc-summary.md ("FsStore (redb + filesystem) vs SQLite — the two-database question"). Determines whether a sibling alknet-blobs crate can implement a SQLite-backed blob store that speaks iroh-blobs' Command actor protocol without forking iroh-blobs, by checking whether the full public API surface is sufficient.

---

TL;DR

The POC summary framed this as "fork iroh-blobs to use SQLite instead of redb — a big maintenance commitment." That framing is a false dichotomy. There is a third path the summary didn't consider: implement a SqliteStore actor in an external crate that speaks iroh-blobs' public Command protocol, with zero changes to iroh-blobs core plus a trivial upstream visibility PR.

The probe traced every Command variant against the published iroh-blobs 0.103.0 source. Findings:

1. There is no Store trait. Store is a concrete struct wrapping an irpc::Client<proto::Request> (an mpsc sender). MemStore and FsStore are two actor implementations that both call Store::from_sender(sender). A third store is a third actor, not a trait impl.

2. The Command enum is pub (generated by the irpc #[rpc_requests] macro, which propagates the source pub enum Request's visibility). Every request struct, every channel payload type, and every helper type that crosses the actor boundary (Hash, HashAndFormat, Tag, TagInfo, TempTag, Bitfield, BlobStatus, AddProgressItem, ExportProgressItem, EncodedItem, BaoContentItem, Leaf, Scope) is pub. A downstream actor can match on Command and handle every variant using only pub surface.

3. The only blockers are four pub(crate) items that need widening to pub: Store::from_sender, Store::ref_from_sender, the ApiClient type alias, and the Scope field. This is a ~4-line, zero-logic upstream PR. Optionally, exposing TempTags/TempTagScope would enable iroh-native temp-tag tracking, but a self-managed-GC fallback makes this unnecessary.

4. No Command variant is BLOCKED. The redb-specific types (EntryState, DataLocation, OutboardLocation, the redb tables module) never cross the pub API boundary — they're confined to the pub(crate) store/fs/meta module. A SQLite store has its own schema and never touches them.

5. GC is reusable, not re-implementable. run_gc (store/gc.rs:222) is pub and walks the store via the pub Store methods (tags().list(), tags().list_temp_tags(), blobs().list(), blobs().delete(), export_bao(), sync_db()). A downstream store that correctly implements those Command variants gets iroh's GC for free.

6. ~100 lines of bao-tree orchestration must be re-implemented (the ImportBao/ExportBao/ExportRanges/Observe handlers). This is re-implementation, not reuse — but all of it sits on pub bao_tree APIs (traverse_ranges_validated, PreOrderMemOutboard::create, BaoTree, ChunkRanges). MemStore already demonstrates this pattern: it has its own BaoFileStorage/PartialMemStorage; FsStore has its own; alknet-blobs would have its own. One store impl = one copy of the bao glue.

Verdict: Build alknet-blobs as an external crate. Do not fork. Push the 4-line visibility PR upstream. If upstream rejects it, fork — but the fork is ~4 lines different from the external crate, not the "big maintenance commitment" the summary feared.

---

Background: Why the POC summary's framing was wrong

The POC summary (poc-summary.md §"Open Unknowns #1") said:

The alternative — forking iroh-blobs to use SQLite instead of redb — is a big maintenance commitment. The POC's write_chunks table proves SQLite can handle chunk-sized inline BLOBs at iroh's granularity, so the swap is mechanically possible. But it should only be done if the two-database coexistence proves problematic, not for aesthetics.

This assumed the choice was binary: (a) run redb + SQLite side-by-side, or (b) fork iroh-blobs to swap redb for SQLite. Reading the actual code reveals a third option: an external crate that implements the Command actor protocol against SQLite, with iroh-blobs untouched.

The key architectural fact the summary missed: iroh-blobs has no Store trait. Store (src/api.rs:213) is a concrete struct holding an irpc::Client<proto::Request> — a typed mpsc sender. MemStore (src/store/mem.rs) and FsStore (src/store/fs.rs) are not trait implementations; they are actor tasks that hold an mpsc::Receiver<Command>, handle commands, and produce a Store via Store::from_sender(sender). The seam is the Command enum, not a trait. A third store is a third actor.

This re-frames the risk calculus the summary was conservative about. The "two-database" concern (two WALs, two fsync paths, two crash-recovery stories, silent-corruption risk on the seam) is avoided not by "a big maintenance commitment" but by writing a sibling crate that owns its own single SQLite file — exactly the architecture the POC's path-tree + write-chunks + honker work already validated.

---

The Command protocol is pub

iroh-blobs 0.103.0, src/api/proto.rs:

• pub enum Request (line 92), decorated with #[rpc_requests(message = Command, alias = "Msg", rpc_feature = "rpc")] (line 90).
• The irpc-derive macro (/workspace/irpc/irpc-derive/src/lib.rs:146) emits #vis enum #message_enum_name { ... }, propagating the source enum's pub. So pub enum Command is generated, with one variant per Request variant, each wrapping WithChannels<RequestStruct, Request>.
• WithChannels fields (inner, tx, rx) are pub (irpc/src/lib.rs:1162-1168).
• Per-variant *Msg type aliases (e.g. ImportBaoMsg, ExportBaoMsg) are generated as pub type (irpc-derive/src/lib.rs:328-335).
• From<WithChannels<T, Request>> for Command impls are generated and pub (irpc-derive/src/lib.rs:279-281).

Every request struct (ImportBaoRequest, ExportBaoRequest, BlobStatusRequest, SetTagRequest, ListTagsRequest, …) is pub with pub fields. Every channel payload type (Hash, HashAndFormat, Tag, TagInfo, TempTag, Bitfield, BlobStatus, AddProgressItem, ExportProgressItem, EncodedItem, BaoContentItem, Leaf, Scope, BatchResponse, ImportByteStreamUpdate, ExportRangesItem) is pub.

The Command enum is the actor's inbox type. A downstream crate that spawns a tokio task holding mpsc::Receiver<Command> can match on every variant and produce a Store via Store::from_sender(sender) — once that constructor is pub.

---

The four items that must be made pub

Mandatory (the ~4-line PR)

Item	File:line	Current	Needed for
ApiClient type alias	src/api.rs:33	pub(crate) type ApiClient = irpc::Client<proto::Request>;	The external store wrapper holds an ApiClient field (as MemStore/FsStore do). Without it the from_sender signature can't be expressed. Alternative: make from_sender take irpc::Client<proto::Request> directly and keep ApiClient private — fewer surface changes.
Store::from_sender	src/api.rs:299	pub(crate) fn from_sender(client: ApiClient) -> Self	External actor constructs a Store from its mpsc::Sender. This is the single load-bearing change.
Store::ref_from_sender	src/api.rs:303	pub(crate) fn ref_from_sender(client: &ApiClient) -> &Self	Deref/AsRef<Store> for the external store wrapper (matches MemStore/FsStore pattern).
Scope field	src/api/proto.rs:693	pub struct Scope(pub(crate) u64);	Batch must construct a Scope to send back on its oneshot::Sender<Scope>; import variants receive a Scope they must destructure. Only Scope::GLOBAL is constructible today. Minimum: make the field pub (it's a u64), or add Scope::new(u64)/Scope::into_inner().

Optional (enables iroh-native temp-tag tracking, NOT required)

Item	File:line	Current	Why
util::temp_tag module	src/util.rs:4	pub(crate) mod temp_tag;	TempTags, TempTagScope, TagDrop, TagCounter are sealed. Without this, imports can only emit untracked temp tags via TempTag::new(haf, None) (pub).
TempTags struct + create/create_scope/end_scope	src/util/temp_tag.rs:173	pub(crate) struct TempTags (methods individually pub but in sealed module)	Refcounted, GC-aware temp tags for imports and CreateTempTag.
TempTagScope + TagDrop	src/util/temp_tag.rs:211,60	sealed	Batch scope bookkeeping (scope.on_drop(&msg)).
Bitfield::new_unchecked	src/api/proto/bitfield.rs:74	pub(crate)	ImportBao fs handler uses it. Bitfield::new (pub) is a fine substitute. Not required.

The fallback if TempTags stays sealed: use TempTag::new(haf, None) (pub today) for imports. The tag is valid on the wire and protects the blob from GC for the tag's lifetime, but on_drop is None so the refcount never decrements — effectively a leak until process exit or explicit DeleteBlobs. This is acceptable because:

1. alknet-blobs owns its SQLite schema; the path tree (from the POC) already tracks which hashes are live via path rows + tags. Self-managed GC against SQLite is the natural design.
2. MemStore and FsStore each own their own TempTags instance already — there is no shared global temp-tag registry. A third store having its own is the existing pattern, not a deviation.
3. iroh's run_gc (see below) walks the store via pub Store methods, so it works regardless of how temp tags are tracked internally — as long as ListTempTags returns the right set.

Under this fallback, the only strictly-required upstream change is the 4 lines above.

---

GC is reusable (a correction to the probe's first pass)

The first pass of this probe incorrectly concluded that run_gc was pub(crate) and that a downstream store would have to write its own GC loop. That is wrong:

• pub async fn run_gc(store: Store, config: GcConfig) — src/store/gc.rs:222. It is pub.
• gc_mark_task (gc.rs:34) walks live hashes via: store.tags().list(), store.tags().list_temp_tags(), store.export_bao(hash, ChunkRanges::all()).hashes().
• gc_sweep_task (gc.rs:83) deletes dead blobs via: store.blobs().list().stream(), store.blobs().delete(batch), store.sync_db().

Every one of those is a pub method on Store backed by a Command variant (ListTags, ListTempTags, ExportBao, ListBlobs, DeleteBlobs, SyncDb). A downstream alknet-blobs store that correctly implements those six variants gets iroh's mark-sweep GC for free — it just calls run_gc(store.clone(), gc_config) in a spawned task, exactly as MemStore::new_with_opts (mem.rs:143) and FsStore::load_with_opts (fs.rs:1427) do.

The implication: even under the "self-managed temp tags" fallback, GC is not a thing alknet-blobs has to build. It's a thing it gets by implementing the Command variants it would implement anyway.

---

Per-variant verdict

All ~24 Command variants traced. Channel payload types are pub for every variant. EntryState/DataLocation/OutboardLocation (redb value types) never appear in pub channel types — confirmed by reading every #[rpc(tx=..., rx=...)] attribute in proto.rs. They are confined to the pub(crate) redb meta actor.

Variant	Verdict	Notes
ListBlobs	PUB-OK	Stream Hash from your DB.
Batch	NEEDS-PUB	Must construct Scope for the oneshot reply — needs Scope field pub. The TempTagScope::on_drop bookkeeping is sealed; implement your own ~30-line scope tracker or skip batch-scoped cleanup (acceptable for a SQLite store that owns its own GC).
DeleteBlobs	PUB-OK	Delete in your DB; protected-set is your own.
ImportBao	PUB-OK (logic-heavy)	Re-implement ~60-100 lines of bao-tree chunk assembly (BaoContentItem::{Parent,Leaf} → outboard + data + Bitfield). Uses pub bao_tree APIs. See "Re-implementation cost" below.
ExportBao	PUB-OK	Call pub traverse_ranges_validated with a 6-line Sender impl you write yourself (the iroh BaoTreeSender is sealed but trivial).
ExportRanges	PUB-OK	~40 lines of range iteration + Bitfield superset checks + Leaf emission. Pub Bitfield/Leaf/RangeSet2.
Observe	PUB-OK	Implement your own watch::Sender<Bitfield> → mpsc::Sender<Bitfield> forwarder (~15 lines). Pub Bitfield.
BlobStatus	PUB-OK	Return NotFound/Partial/Complete from your DB.
ImportBytes	NEEDS-PUB	Scope field needed (request carries scope). Emit AddProgressItem::Done(TempTag) via TempTag::new(haf, None) (pub, untracked) or TempTags::create (sealed).
ImportByteStream	NEEDS-PUB	Same as ImportBytes.
ImportPath	NEEDS-PUB	Same as ImportBytes.
ExportPath	PUB-OK	Write your data to target path; emit ExportProgressItem.
ListTags	PUB-OK	Query your tag table.
SetTag	PUB-OK
DeleteTags	PUB-OK
RenameTag	PUB-OK
CreateTag	PUB-OK	Tag::auto is pub (store/util.rs:72).
ListTempTags	PUB-OK	Return your own temp-tag list. Required for run_gc to work — it calls this.
CreateTempTag	NEEDS-PUB	Scope field. TempTag::new(value, None) (pub) for untracked, or TempTags::create (sealed) for tracked.
SyncDb	PUB-OK	Flush your SQLite.
WaitIdle	PUB-OK	Track your own task set.
Shutdown	PUB-OK
ClearProtected	PUB-OK	Your own protected set.

NEEDS-PUB count: 6 variants (Batch, ImportBytes, ImportByteStream, ImportPath, CreateTempTag) — all blocked only by the Scope field. One change (Scope(pub u64)) unblocks all six.

BLOCKED count: 0.

---

Re-implementation cost (the real maintenance burden)

The visibility PR is trivial. The actual work — and the honest maintenance cost — is re-implementing the bao-tree orchestration that the ImportBao/ExportBao/ExportRanges/Observe handlers do. These handlers don't wire pub pieces together; they orchestrate pub bao_tree APIs. A downstream store writes its own copy.

Handler	Lines to re-implement	Uses (all pub)
ImportBao	~60-100	BaoContentItem, BaoTree, ChunkRanges, Bitfield::new, PreOrderMemOutboard (for compute-on-import path), Leaf. Re-derive the "size-1 leaf validates size" check (is_validated, sealed in pub(crate) bitfield module — ~3 lines).
ExportBao	~6	traverse_ranges_validated + a Sender for &mut mpsc::Sender<EncodedItem> impl (the iroh BaoTreeSender is a 6-line ref_cast wrapper at store/util.rs:400-415).
ExportRanges	~40	Bitfield superset check, RangeSet2 iteration, Leaf emission.
Observe	~15	tokio::sync::watch → mpsc::Sender<Bitfield> forwarder.

Total: ~120-160 lines of bao-tree glue to re-implement in alknet-blobs. This is the same glue MemStore has its own copy of (src/store/mem.rs, the BaoFileStorage/PartialMemStorage/import_bao/export_bao functions) and FsStore has its own copy of (src/store/fs/bao_file.rs, 749 lines). The pattern is "one store impl = one copy of the bao glue." alknet-blobs is a third store impl; it gets a third copy. The copy is smaller than FsStore's because a SQLite store doesn't need the partial-blob-on-filesystem lifecycle (the POC's write_chunks table handles partial state in SQLite).

This is re-implementation, not reuse — but it is re-implementation against stable, pub bao_tree APIs, not against iroh internals. The maintenance cost is: track bao_tree version bumps. That is a much smaller surface than "track all of iroh-blobs."

---

alknet-crate reuse for the write/read path

The four existing alknet crates (post-POC) reduce some of the work the POC flagged as unknown:

• alknet-tty (crates/alknet-tty/) — TtyHandle already exposes tokio::io::AsyncWrite stdin and Stream<Item=Bytes> stdout (src/backend.rs:139-182). The MockStdinSink (src/backend.rs:366-403) is a working AsyncWrite-over-mpsc::Sender<Bytes> adapter — directly reusable as a pattern for the SFTP write path's chunk bridge into WriteSession::write_chunk. The kill-on-Drop contract pattern (exit_code future, ADR-056) is the same shape as write-session abort-on-drop.
• alknet-call (crates/alknet-call/) — already uses irpc (workspace dep irpc = "0.16") for structured RPC. The EventEnvelope/length-prefixed JSON framing (src/protocol/wire.rs) is a different protocol than iroh-blobs' Command actor protocol, but the irpc usage pattern (matching on request variants, channel-based replies) is the same shape alknet-blobs' actor will use.
• alknet-core (crates/alknet-core/) — optional iroh = "0.35" dep. Version mismatch: alknet-core is on iroh 0.35/irpc 0.16; published iroh-blobs 0.103 requires iroh 1.0/irpc 0.17. alknet-blobs will pull iroh-blobs 0.103's irpc 0.17 transitively. This needs resolution at spec time — either alknet-core bumps to iroh 1.0, or alknet-blobs pins an iroh-blobs version compatible with irpc 0.16. Open question for the spec.

None of the existing alknet crates implement the blob store's bao-tree orchestration — that is genuinely new work. But the async-IO adapter patterns (AsyncWrite-over-mpsc, Stream-of-Bytes, kill-on-drop futures) are already proven in alknet-tty and reduce the write-path wiring risk.

---

Versioning reality

Three iroh-blobs generations are in play:

Source	Version	iroh	irpc	Notes
/workspace/iroh-blobs (local checkout)	0.100.0	0.98	0.14	Pre-n0-rebrand. Used for the original architecture reading.
crates.io published (cached)	0.103.0	1.0	0.17	What the POC used; what alknet-blobs would target.
alknet-core dep	—	0.35	0.16	Two majors behind iroh-blobs 0.103.

This probe was run against 0.103.0 (the published version). The visibility findings (Store::from_sender pub(crate), Scope(pub(crate) u64), Command pub via macro, no Store trait, EntryState confined to pub(crate) meta) all hold on 0.103.0. The 4-line upstream PR would target the 0.103+ line.

The alknet-core iroh 0.35 vs iroh-blobs iroh 1.0 gap is a spec-time decision, not a probe blocker. It affects which iroh QUIC API the distributed-sync layer (POC 3) binds against, but not the local Command-actor surface this probe examined.

---

Recommended path

1. Build alknet-blobs as a workspace member (crates/alknet-blobs/), not a fork. It depends on iroh-blobs = "0.103" (published) and implements the Command actor against a single SQLite file (schema: the POC's path-tree tables + write_chunks + a blob-metadata table replacing redb's 4 tables + honker tables, all in one .db).

2. Push the 4-line visibility PR upstream to n0-computer/iroh-blobs: Store::from_sender/ref_from_sender + ApiClient (or change from_sender to take irpc::Client<proto::Request> directly) + Scope field. Zero logic changes. If merged, alknet-blobs is a pure downstream crate. If rejected, alknet-blobs forks those 4 lines — the fork is 4 lines different from the external crate, which is the opposite of "big maintenance commitment."

3. Use the self-managed-GC fallback (TempTag::new(haf, None) + own SQLite-backed liveness tracking) unless upstream agrees to expose TempTags. Reuse iroh's run_gc by correctly implementing ListTempTags/ListTags/ListBlobs/DeleteBlobs/ExportBao/SyncDb. This is the same pattern MemStore/FsStore use (each owns its own TempTags); alknet-blobs owns its own, just backed by SQLite.

4. Re-implement the ~120-160 lines of bao-tree orchestration (ImportBao/ExportBao/ExportRanges/Observe) against pub bao_tree APIs. Copy the structure from MemStore (the simpler reference; src/store/mem.rs), not FsStore (which has the partial-blob-on-filesystem complexity alknet-blobs doesn't need).

5. Reuse alknet-tty's async-IO adapter patterns (AsyncWrite-over-mpsc, Stream-of-Bytes, kill-on-drop) for the SFTP write-path bridge into WriteSession.

6. Resolve the iroh 0.35 vs 1.0 version gap at spec time. This is an open question for the architecture doc, not a probe finding.

---

What this closes and what remains

Closes: POC open question #1 ("FsStore (redb + filesystem) vs SQLite — the two-database question"). The answer is: neither. Build a third store (alknet-blobs) as an external crate with its own single SQLite file. No fork, no two-database coexistence. The upstream cost is a 4-line visibility PR.

Does not close (deferred to spec):

• The iroh 0.35 vs iroh 1.0 version gap (alknet-core dependency alignment).
• The exact SQLite schema for the blob-metadata tables (the redb 4-table shape is a reference; a SQLite store may unify inline_data/inline_outboard into BLOB columns or split differently — schema design is a spec task).
• Whether to expose TempTags upstream or commit to the self-managed-GC fallback (a spec decision; the fallback works, exposing TempTags is a nicety).
• SFTP wiring (POC open question #3 — unchanged; the alknet-tty patterns help but don't close it).
• The distributed sync layer's binding to iroh 1.0 vs 0.35 (POC 3 used iroh 1.0; alknet-core is on 0.35).

---

References

• Published source probed: ~/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/iroh-blobs-0.103.0/
  • src/api.rs:33,213,299,303 — ApiClient, Store, from_sender/ref_from_sender (pub(crate))
  • src/api/proto.rs:693 — Scope(pub(crate) u64)
  • src/api/proto.rs:90-139 — pub enum Request + #[rpc_requests] (generates pub enum Command)
  • src/store/mem.rs — reference actor (1127 lines, zero redb)
  • src/store/fs/meta.rs, src/store/fs/meta/tables.rs — redb confined here (~1100 lines)
  • src/store/fs/entry_state.rs — EntryState/DataLocation/OutboardLocation (pub(crate), never in pub channel types)
  • src/store/gc.rs:222 — pub async fn run_gc (reusable, walks store via pub methods)
  • src/util/temp_tag.rs:85 — TempTag::new (pub, untracked fallback); :173 — TempTags (pub(crate))
• irpc derive macro: /workspace/irpc/irpc-derive/src/lib.rs:146,279,328 — visibility propagation, From impls, *Msg aliases
• POC summary: docs/research/alknet-filesystem/poc-summary.md (this doc's parent context)
• alknet crates surveyed: crates/alknet-tty/src/backend.rs (AsyncWrite/Stream/kill-on-drop patterns), crates/alknet-call/src/protocol/wire.rs (irpc usage), crates/alknet-core/Cargo.toml (iroh 0.35 version gap)