Release v0.3.0: compiled forms — ReadPlan, owned BastDoc, LeafMeta, ValidationPlan, fingerprinting
Public API bump 0.2.0 -> 0.3.0 (the 030-compiled-forms plan is now fully implemented; all eight phases landed). - Cargo.toml: version 0.3.0. lib.rs re-exports complete (ReadPlan + sub-types, LeafMeta, OffsetEntry, ValidationPlan + sub-types). - ADR-007 "Cost" rewritten to the Arc<ReadPlan> cost (15.7 ns) with the 0.2.0 "re-parse on demand" framing as a historical note (review #004 L2, the last loose end from that review). - ADR-011/012 status blocks flipped to implemented; architecture README ADR table rows updated; layout-engine.md rewritten for the 0.3.0 surface (engine-factory reader construction, OffsetMap OffsetEntry/LeafMeta/fingerprint section, owned BastDoc compute signature); SequentialReader module doc points at the engine factory. Reviews #004 and #005 flipped to closed. - Bench re-run (alktty wire_vs_bast, 0.3.0 tree): read p64 98 ns/chunk (parity with phase 2; hand-rolled 5.7 us/stream), layout_build 180 ns (was ~1.2 us — the phase-4 owned-doc cache removed the per-build re-parse, ~7x), sequential_reader_new 15.7 ns, write p64 -3%, engine_compile unchanged (meta-schema validation dominates). No dedicated validate_bytes-stream bench: the phase-7 spot check (~0.2 us plan-validate vs ~0.6 us compile-per-call) stands; a dedicated bench is a follow-up if alkcall profiling motivates it. - Downstream: alktty compiles against the path dep unchanged; alkcall has no dependency yet. Verification (full block, all green): 474 tests; clippy -D warnings clean; cargo doc zero warnings; wasm32 release build green; cargo publish --dry-run clean at 0.3.0.
This commit is contained in:
1 parent
537a2170fb
commit
9949f914df
11 files changed
+94
-36
No files matched your search
@@ -63,23 +63,26 @@ write-side.
|
||||
|
||||
### Cost
|
||||
|
||||
`SequentialReader::new` clones the top-level struct's field schemas (a
|
||||
`Vec<(String, Value)>` of the `properties` entries) and clones the
|
||||
schema itself. This is cheap — a struct has a small number of fields
|
||||
(SFTP's largest packet has 5). The construction cost is negligible
|
||||
compared to the cost of reading a buffer.
|
||||
`SequentialReader::new(Arc<ReadPlan>)` is a refcount bump — 15.7 ns
|
||||
(measured, alktty `wire_vs_bast` bench, 0.3.0). The reader shares the
|
||||
engine's compiled [`ReadPlan`](011-compiled-read-plan-for-packed-mode.md)
|
||||
(the packed read-side compiled form) via `Arc` instead of cloning
|
||||
schema data; construction cost is negligible compared to reading a
|
||||
buffer. The engine holds the owned `BastDoc` (ADR-012 §2a) for the
|
||||
aligned materialize path and the one-shot `*::compile` paths.
|
||||
|
||||
> **Note**: The "re-parse on demand" framing below (the read loop
|
||||
> re-parsing `BastDoc::new` per field) is the root cause of the 400x
|
||||
> read-path gap measured in
|
||||
> **Historical note**: the original 0.2.0 framing here ("re-parse on
|
||||
> demand" — the read loop re-parsing `BastDoc::new` per field) was the
|
||||
> root cause of the 400x read-path gap measured in
|
||||
> [review #004](../../reviews/004-performance-review.md).
|
||||
> [ADR-011](011-compiled-read-plan-for-packed-mode.md) (Proposed)
|
||||
> retires this framing by giving the packed read path a compiled
|
||||
> `ReadPlan`; the "Cost" section here and the
|
||||
> `src/engine.rs:112-115` doc comment will be updated in the
|
||||
> implementation commit per ADR-011's recommended order. The factory
|
||||
> decision itself (`sequential_reader() -> Option<SequentialReader>`,
|
||||
> owned fresh reader, consumer-driven cursor) is retained.
|
||||
> [ADR-011](011-compiled-read-plan-for-packed-mode.md) (implemented,
|
||||
> 0.3.0) retired it: the packed read loop walks `Arc<ReadPlan>` (2.27
|
||||
> µs/chunk → 98 ns/chunk), `sequential_reader()` is an `Arc::clone`,
|
||||
> and the owned `BastDoc` (ADR-012 §2a) removed the remaining
|
||||
> per-access re-parse sites in `read_field`/`write_field`/`validate_bytes`.
|
||||
> The factory decision itself (`sequential_reader() ->
|
||||
> Option<SequentialReader>`, owned fresh reader, consumer-driven
|
||||
> cursor) was retained unchanged.
|
||||
|
||||
## Consequences
|
||||
|
||||
|
||||
@@ -2,7 +2,8 @@
|
||||
|
||||
## Status
|
||||
|
||||
Accepted. Closes review #004 H1 + M1 (packed side) + L1 + L2;
|
||||
Accepted. Implemented in 0.3.0 (phases 1–2, 2026-09-02). Closes review
|
||||
#004 H1 + M1 (packed side) + L1 + L2;
|
||||
retires the "re-parse on demand" framing from ADR-007. A derisking
|
||||
POC on branch `readplan-poc` confirmed the `ReadPlan` shape covers
|
||||
every `BastType` arm in the current read loop before implementation
|
||||
|
||||
@@ -2,8 +2,10 @@
|
||||
|
||||
## Status
|
||||
|
||||
Accepted. Implemented (§3's `ValidationPlan`, 0.3.0 phase 7, 2026-08-31);
|
||||
bundles three pieces of work into the 0.3.0 release so the
|
||||
Accepted. Implemented in 0.3.0 — §3's `ValidationPlan` (phase 7,
|
||||
2026-08-31), §1's fingerprinting (phase 6), §2a's owned `BastDoc`
|
||||
(phases 3–4), §2b's `LeafMeta` (phase 5); all shipped 2026-09-02.
|
||||
Bundles three pieces of work into the 0.3.0 release so the
|
||||
crate ships one round of breaking changes, not two (or three). The
|
||||
three pieces: (a) fingerprinting `ReadPlan`/`OffsetMap`, (b) closing
|
||||
the deferred M1 sites via an owned `BastDoc` + `OffsetMap` `LeafMeta`,
|
||||
|
||||
Reference in new issue
Block a user