docs(architecture): add alknet-typedef crate specs, ADRs 095-098, and OQs 069-071
Add the alknet-typedef architecture specification — the binary struct engine that takes JSON Schema with TypeDef:* custom keywords and produces offset maps, read/write functions, and validation. Specs (docs/architecture/crates/typedef/): - overview.md: purpose, 'schema is the format' principle, consumers, scope - schema-layer.md: 17 TypeDef:* kinds, jsonschema integration, annotations - layout-engine.md: two layout modes, three variable-length strategies - data-access.md: read/write, TUnion dispatch, field paths, zero-copy - validation.md: custom keyword validators, TypedefError, TypedefEngine ADRs: - 095: Purpose, scope, and the jsonschema engine - 096: Two layout modes — packed sequential vs aligned static - 097: Schema annotations — endianness, alignment, encoding, TUnion - 098: Error handling and validation strategy OQs (deferred(scope)): - 069: Arrays of variable-length-element structs - 070: no_std + alloc support - 071: Builder API for schema construction Index updates: README doc table + ADR table, open-questions.md theme table + Deferred/Blocked section, overview.md crate graph. Grounded in the alknet-typedef POC (26 tests passing) and the call-channels-unification research. Reviewed by architecture-reviewer; all critical issues, warnings, and suggestions addressed.
This commit is contained in:
1 parent
bf0f827bf4
commit
85c5590001
16 files changed
+2230
-1
No files matched your search
@@ -211,6 +211,14 @@ Door type is separate from whether a decision is made. A two-way door is a decis
|
||||
| [OQ-66](questions/066-alknet-register-wire-protocol.md) | `alknet/register` Wire Protocol | deferred(scope) | one | med |
|
||||
| [OQ-67](questions/067-iroh-proxy-support.md) | iroh Proxy Support (Direct-Connection Peer Exposure) | resolved | one | med |
|
||||
|
||||
### alknet-typedef
|
||||
|
||||
| OQ | Title | Status | Door | Pri |
|
||||
|----|-------|--------|------|-----|
|
||||
| [OQ-069](questions/069-arrays-of-variable-length-element-structs.md) | Arrays of Variable-Length-Element Structs | deferred(scope) | two | low |
|
||||
| [OQ-070](questions/070-no-std-alloc-support.md) | `no_std` + `alloc` Support | deferred(scope) | two | low |
|
||||
| [OQ-071](questions/071-builder-api-for-schema-construction.md) | Builder API for Schema Construction | deferred(scope) | two | med |
|
||||
|
||||
## Deferred / Blocked
|
||||
|
||||
The safe-exit visibility surface. These questions are parked because the
|
||||
@@ -358,3 +366,37 @@ filtering the tables above.
|
||||
[OQ-64](questions/064-client-side-tls-helper.md).
|
||||
- **Full file**: [OQ-64](questions/064-client-side-tls-helper.md)
|
||||
|
||||
### OQ-069: Arrays of Variable-Length-Element Structs
|
||||
|
||||
- **Blocked on**: A concrete consumer that needs arrays of structs with
|
||||
variable-length fields, where the elements are interleaved
|
||||
(`[fixed_0][str_0][fixed_1][str_1]...`) and the engine must walk
|
||||
sequentially rather than use a fixed stride. The SFTP `Name` packet
|
||||
has `Vec<File>` where `File` contains strings, but SFTP serializes
|
||||
this as a sequence of length-prefixed strings (the serde `SeqAccess`
|
||||
pattern), not as an array of fixed-stride structs. Arrays of
|
||||
fixed-size structs are fully supported.
|
||||
- **Priority**: low
|
||||
- **Full file**: [OQ-069](questions/069-arrays-of-variable-length-element-structs.md)
|
||||
|
||||
### OQ-070: `no_std` + `alloc` Support
|
||||
|
||||
- **Blocked on**: An embedded use case that requires `no_std` + `alloc`
|
||||
(e.g., a microcontroller running Rust without `std`). The WASM target
|
||||
has `std` available via `wasm-bindgen`. The engine's core (offset
|
||||
computation, read/write) is already allocation-free; the `jsonschema`
|
||||
dependency is the only `alloc` consumer.
|
||||
- **Priority**: low
|
||||
- **Full file**: [OQ-070](questions/070-no-std-alloc-support.md)
|
||||
|
||||
### OQ-071: Builder API for Schema Construction
|
||||
|
||||
- **Blocked on**: A concrete need for programmatic schema construction
|
||||
in Rust. The current consumers (SFTP, metatensor, binary call frames,
|
||||
TTY negotiation) all have schemas that can be hand-written or
|
||||
generated from TypeBox. A builder API would be a fluent Rust API that
|
||||
produces the same JSON Schema structure — it would sit on top of the
|
||||
engine, not inside it.
|
||||
- **Priority**: medium
|
||||
- **Full file**: [OQ-071](questions/071-builder-api-for-schema-construction.md)
|
||||
|
||||
Reference in new issue
Block a user