Skip to content

Commit abe6e03

Browse files
frristclaude
andcommitted
docs(architecture): refresh §11/§12 status for the read tier, DeleteBucket abort, and spool eviction
The local-table Locator read tier is wired and validated (TestForgeReadAfterEviction; #44 for retention-retired catalog blocks), so the "not wired" bullet inverts: the remaining gap is spool eviction itself — unbounded today, DeleteObject releases network-side only — tracked in #48 alongside §5's bounded-cache spec. Record DeleteBucket's implicit abort of in-flight multipart sessions (and its hilt blob.Abort gate), point §11's cache-eviction open question at #48, and note the forge paths are now exercised by the in-repo smelt itest harness. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 parent 36c3490 commit abe6e03

1 file changed

Lines changed: 14 additions & 7 deletions

File tree

docs/architecture.md

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -579,7 +579,7 @@ The first cut keeps digest-before-upload; `allocate-by-size` is a same-rack fast
579579
- **`min`/`max` final values** — 8 MiB / 256 MiB are the starting proposals; confirm against the
580580
base-fee and transaction-count budget.
581581
- **Lifting the 256 MiB ceiling** (streaming commP) versus the simplicity of coarse splitting.
582-
- **Local cache vs near-stateless** — cache sizing/eviction, or commit to near-stateless.
582+
- **Local cache vs near-stateless** — cache sizing/eviction, or commit to near-stateless (#48).
583583
- **Catalog GC**`gc_candidates` is a write-only log this iteration; the catalog CARs on Piri grow
584584
with mutation volume until a collector exists.
585585
- **Monotonic `nextPieceId` ratchet** under heavy churn (pdp-sim) — possibly periodic dataset
@@ -809,17 +809,21 @@ reference index — and is out of scope for this iteration.
809809
810810
### Deferred as forge-mode glue (validated live in smelt, not the in-process harness)
811811
812-
The in-memory harness uses a no-op uploader and serves reads from the spool, so these forge-network
813-
paths are stubbed in-tree and verified against a real sprue+piri+indexer later:
812+
The in-memory harness uses a no-op uploader and serves reads from the spool; the forge-network
813+
paths below are exercised against the real stack by the smelt-based `itest/` harness in CI:
814814
815815
- **`remove(digest)` and `abort(digest)` are live.** `RemoveBlob` invokes `/blob/remove` on
816816
sprue, which forwards `/blob/release` to the storage nodes ([§9](#9-the-system-contract-piri--sprue--indexer)); delete finality means claim-release-now,
817817
bytes-at-root-death. `AbortBlob` retires parked part-blobs via `/blob/abort` — sprue translates
818818
it into `/blob/reject` on the node (provider recovered from the `cause` receipt chain);
819819
allocation-expiry GC (FIL-625) remains the backstop when an abort never arrives.
820-
- **The local-table `Locator` read tier is not wired.** Body-blob *locations* are recorded at accept,
821-
but the read path that consumes them ([§7.4](#74-read-getobject), [§8](#8-retrieval-addressing-when-bodies-need-a-sharded-dag-index)) is deferred — it is only exercised after spool
822-
eviction (also not built) and is best validated live.
820+
- **The local-table `Locator` read tier is wired and validated.** Body blobs re-resolve after
821+
spool loss from `blob_locations` + `/content/retrieve` (`TestForgeReadAfterEviction`), and
822+
retention-retired catalog blocks resolve via `shard_inclusions` (#44) — the read paths of
823+
[§7.4](#74-read-getobject) / [§8](#8-retrieval-addressing-when-bodies-need-a-sharded-dag-index).
824+
Spool **eviction** itself is still unbuilt: nothing bounds the spool, and `DeleteObject`'s
825+
release is network-side only, so local disk grows with every body byte ever written — the
826+
bounded-cache policy [§5](#5-the-data-layer) specifies is tracked in #48.
823827
- **Multipart parts park at UploadPart, accept at Complete.** (Built: `parkBlobs`/`concludeBlobs`
824828
over the `blob_parks` table.) The in-process harness still spools parts
825829
at `UploadPart` and uploads+accepts them at `Complete`; the true forge *parking* (upload early,
@@ -835,7 +839,10 @@ paths are stubbed in-tree and verified against a real sprue+piri+indexer later:
835839
sessions and committed objects), and a background sweeper aborts open sessions older
836840
than `multipart_session_ttl` (default 7d) and reaps terminal session rows. A successful
837841
Complete retains its session in state `completed` so a duplicate Complete is idempotent
838-
per S3. The network-side `/blob/abort` unwind remains a parking-flow concern (above).
842+
per S3. `DeleteBucket` implicitly aborts the bucket's in-flight sessions before the space
843+
delete (upstream's conformance teardown never aborts them); its `/blob/abort` leg is gated
844+
on hilt granting `blob.Abort` for the bucket-delete operation. The network-side `/blob/abort`
845+
unwind remains a parking-flow concern (above).
839846
840847
### Known correctness boundary
841848

0 commit comments

Comments
 (0)