docs(research): correct layer vocabulary — alkcall has no transport code
- Verified against alkcall 0.8.1: no networking deps; Connection wraps a caller-provided established stream (ADR-012 dial/call decoupling) - 'transport' was being used loosely for 'wire/ops protocol'; now reserved for endpoints/dialing/byte-moving, which is in neither crate. Ops/framing/ACL surface = wire/ops protocol (alkcall's layer) - Vision sentence, scope line, OQ-BL-01 argument, and alkcall prior-art entry rewritten with the accurate layering; alkcall entry now states the transport-free fact explicitly - iroh-blobs-eval.md: 'welded to their transport' -> 'welded to their protocol stack (endpoints/transport weld on above it)' Verification: cargo test / clippy -D warnings / fmt --check clean
This commit is contained in:
1 parent
b0b385d94e
commit
7d9ac8a6ec
2 files changed
+40
-27
No files matched your search
@@ -31,7 +31,9 @@ Lessons for alkblobs:
|
|||||||
- **The command-enum-as-contract is a working pattern** (it is what
|
- **The command-enum-as-contract is a working pattern** (it is what
|
||||||
makes iroh-blobs' remote/local symmetry possible), but it carries the
|
makes iroh-blobs' remote/local symmetry possible), but it carries the
|
||||||
whole irpc machinery into the store layer and *is* the reason their
|
whole irpc machinery into the store layer and *is* the reason their
|
||||||
store is welded to their transport. POC #1's lean `Backend` trait is
|
store is welded to their protocol stack (theirs also welds transport
|
||||||
|
endpoints above that; the store-actor weld alone is what kills
|
||||||
|
backend swappability). POC #1's lean `Backend` trait is
|
||||||
the smaller hammer for our split: the trait stays dumb (opaque bytes),
|
the smaller hammer for our split: the trait stays dumb (opaque bytes),
|
||||||
and any ops surface above it (alkcall) speaks its own protocol.
|
and any ops surface above it (alkcall) speaks its own protocol.
|
||||||
- **Re-borrowed conclusion, not mechanism: per-hash serialized actors.**
|
- **Re-borrowed conclusion, not mechanism: per-hash serialized actors.**
|
||||||
@@ -175,7 +177,7 @@ findings (first-party, measured).
|
|||||||
## Do-not-inherit list (re-confirmed against 0.103)
|
## Do-not-inherit list (re-confirmed against 0.103)
|
||||||
|
|
||||||
- The `Command`-actor + irpc store abstraction (welds store to their
|
- The `Command`-actor + irpc store abstraction (welds store to their
|
||||||
transport stack).
|
protocol stack; endpoints/transport weld on above it).
|
||||||
- redb-specific entry-state modeling if we go sqlite (their tables and
|
- redb-specific entry-state modeling if we go sqlite (their tables and
|
||||||
`EntryState` postcard encoding are theirs; our sqlite schema is
|
`EntryState` postcard encoding are theirs; our sqlite schema is
|
||||||
`key → (value, size)` and our dispatch is store-layer policy).
|
`key → (value, size)` and our dispatch is store-layer policy).
|
||||||
|
|||||||
+36
-25
@@ -29,8 +29,9 @@ documents (`poc-trait-dispatch-findings.md`, `poc-largeblob-findings.md`,
|
|||||||
a put/get/verify store keyed under one canonical content hash (the
|
a put/get/verify store keyed under one canonical content hash (the
|
||||||
git-family derivation; legacy SHA-1-tolerant), with pluggable backends
|
git-family derivation; legacy SHA-1-tolerant), with pluggable backends
|
||||||
(small blobs in a kv/sqlite-ish store, large blobs on a filesystem
|
(small blobs in a kv/sqlite-ish store, large blobs on a filesystem
|
||||||
fallback), split from any transport/protocol layer, with auth-gated
|
fallback), split from any wire/ops-protocol layer (framing, op family,
|
||||||
network operations riding the alkcall seam (OQ-BL-01).
|
ACL ride the alkcall substrate when they exist — OQ-BL-01), which is
|
||||||
|
itself transport-free (alkcall is a pure protocol crate).
|
||||||
|
|
||||||
**Why this crate exists (the converging consumers):**
|
**Why this crate exists (the converging consumers):**
|
||||||
|
|
||||||
@@ -82,15 +83,16 @@ The implications for this crate:
|
|||||||
alkcall substrate (OQ-BL-01), whether it lives in this crate or a
|
alkcall substrate (OQ-BL-01), whether it lives in this crate or a
|
||||||
sibling.
|
sibling.
|
||||||
|
|
||||||
**The scope line:** this crate is the *store*, not the *transport*.
|
**The scope line:** this crate is the *store*, not the *wire/ops
|
||||||
iroh-blobs welds store + provider protocol + tickets + postcard into
|
protocol*. iroh-blobs welds store + provider protocol + tickets +
|
||||||
one crate; the defining posture here is the opposite split —
|
postcard into one crate; the defining posture here is the opposite
|
||||||
put/get/verify against a hash is its own layer, and any
|
split — put/get/verify against a hash is its own layer, and any
|
||||||
provider/protocol/ops surface lives above it or in feature-gated
|
ops/protocol surface lives above it or in feature-gated modules (the
|
||||||
modules (the alk* inversion-point pattern). "Above it" does not mean
|
alk* inversion-point pattern). "Above it" does not mean "without
|
||||||
"without alkcall": the ops surface *is* alkcall-shaped (OQ-BL-01) —
|
alkcall": the ops surface *is* alkcall-shaped (OQ-BL-01) — what the
|
||||||
what the store layer itself must never grow is transport, framing, or
|
store layer itself must never grow is wire framing, op dispatch, ACL,
|
||||||
auth internals. What stays *above* the crate regardless: repos/
|
or transport (alkcall carries none of the last either; the connection
|
||||||
|
is handed to it). What stays *above* the crate regardless: repos/
|
||||||
workspaces as reference sets (trees/manifests), path→hash mapping,
|
workspaces as reference sets (trees/manifests), path→hash mapping,
|
||||||
git semantics, the contract/gossip/replicator policy layer.
|
git semantics, the contract/gossip/replicator policy layer.
|
||||||
|
|
||||||
@@ -304,16 +306,22 @@ appfile pattern this crate now owns by its own validated design.
|
|||||||
|
|
||||||
### alkcall — the substrate (and the ops surface's foundation)
|
### alkcall — the substrate (and the ops surface's foundation)
|
||||||
|
|
||||||
`/workspace/@alkdev/alkcall` (the call + channels RPC crate). The ops
|
`/workspace/@alkdev/alkcall` (the call + channels RPC crate). **It
|
||||||
surface rides it (OQ-BL-01, settled): JSON-shaped control ops with
|
contains no transport code** — no networking dependencies (README:
|
||||||
JSON Schema validation and typed error schemas (ADR-016), binary
|
"a pure protocol crate — no networking, no transport dependencies");
|
||||||
streaming via the `channel_open` marker (ADR-047) in both directions
|
a `Connection` wraps an already-established byte stream that the
|
||||||
(`Sub` ADR-021 for verified fetch, `Pub`/`HandlerKind::Sink` ADR-046
|
*caller* provides (dialing/listening happens above it, per ADR-012's
|
||||||
for put), ACL via `AccessControl` + ownership checks (ADR-011) under
|
dial/call decoupling). What it owns is the wire/ops protocol: JSON
|
||||||
the ADR-017 privilege model, and the established data-path patterns
|
op family with JSON Schema validation and typed error schemas
|
||||||
|
(ADR-016), binary streaming via the `channel_open` marker (ADR-047)
|
||||||
|
in both directions (`Sub` ADR-021 for verified fetch, `Pub`/
|
||||||
|
`HandlerKind::Sink` ADR-046 for put), ACL via `AccessControl` +
|
||||||
|
ownership checks (ADR-011) under the ADR-017 privilege model, service
|
||||||
|
discovery, and N-channel multiplexing; established data-path patterns
|
||||||
(`BiStream`, two-pump `pump_bidi` ADR-050). The store layer itself
|
(`BiStream`, two-pump `pump_bidi` ADR-050). The store layer itself
|
||||||
stays alkcall-free (principle 1: substrate-agnostic); alkcall enters
|
stays alkcall-free (principle 1: substrate-agnostic); alkcall enters
|
||||||
only at the ops module/sibling boundary.
|
only at the ops module/sibling boundary — which is where transport,
|
||||||
|
if p2p git ever needs a specific one, enters above *that*.
|
||||||
|
|
||||||
## Open Questions
|
## Open Questions
|
||||||
|
|
||||||
@@ -330,11 +338,12 @@ are now settled separately.
|
|||||||
decision rather than an inherited assumption.) The original draft's
|
decision rather than an inherited assumption.) The original draft's
|
||||||
"undecided pending the first consumer's shape" conflated two things:
|
"undecided pending the first consumer's shape" conflated two things:
|
||||||
iroh-blobs' *actual* weld (no Store trait — its message-actor store is
|
iroh-blobs' *actual* weld (no Store trait — its message-actor store is
|
||||||
inseparable from the irpc transport machinery, the thing convention 7
|
inseparable from the irpc protocol machinery, the thing convention 7
|
||||||
rejects) and the presence of a protocol substrate under the ops layer,
|
rejects) and the presence of a protocol substrate under the ops layer,
|
||||||
which is a different layer entirely and is family-standard. The
|
which is a different layer entirely and is family-standard. The
|
||||||
inverted-point posture constrains the *store layer only*: the store
|
inverted-point posture constrains the *store layer only*: the store
|
||||||
grows no transport, framing, or auth internals. It does not argue for
|
grows no wire framing, op dispatch, ACL, or transport internals. It
|
||||||
|
does not argue for
|
||||||
an ops layer that reinvents them.
|
an ops layer that reinvents them.
|
||||||
|
|
||||||
Why alkcall specifically, rather than an in-band op scheme:
|
Why alkcall specifically, rather than an in-band op scheme:
|
||||||
@@ -362,10 +371,12 @@ Why alkcall specifically, rather than an in-band op scheme:
|
|||||||
- **The store stays substrate-agnostic regardless.** alkcall enters
|
- **The store stays substrate-agnostic regardless.** alkcall enters
|
||||||
only at the ops module/sibling layer, behind the store's public
|
only at the ops module/sibling layer, behind the store's public
|
||||||
surface — the same relationship alkhttp's handlers have to their
|
surface — the same relationship alkhttp's handlers have to their
|
||||||
storage. If alkcall were ever unavailable, the store layer loses
|
storage. If the ops surface were ever re-homed, the store layer
|
||||||
nothing (that independence is principle 1); the point is that the
|
loses nothing (that independence is principle 1); the point is that
|
||||||
ops surface, when it exists, does *not* re-implement what the
|
the ops surface, when it exists, does *not* re-implement what the
|
||||||
substrate provides.
|
substrate provides — and neither layer grows transport, which has
|
||||||
|
no home in either crate (alkcall's `Connection` is handed in, not
|
||||||
|
dialed).
|
||||||
|
|
||||||
**The crate-boundary question — reduced to placement only:** given an
|
**The crate-boundary question — reduced to placement only:** given an
|
||||||
alkcall-shaped op family, the remaining choice is where the
|
alkcall-shaped op family, the remaining choice is where the
|
||||||
|
|||||||
Reference in new issue
Block a user