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
@@ -0,0 +1,20 @@
|
||||
# OQ-069: Arrays of variable-length-element structs
|
||||
|
||||
- **Origin**: [crates/typedef/layout-engine.md](crates/typedef/layout-engine.md),
|
||||
[crates/typedef/data-access.md](crates/typedef/data-access.md);
|
||||
`docs/research/alknet-typedef/findings.md` §"Problem 3: Nested structs
|
||||
and arrays of structs"
|
||||
- **Status**: deferred(scope)
|
||||
- **Door type**: Two-way (additive — the engine can add lazy walking
|
||||
logic without changing the existing fixed-stride array support)
|
||||
- **Priority**: low
|
||||
- **Impacts**: Blocks any protocol with interleaved variable-length struct arrays (e.g., a protocol where each array element has a string field and elements are packed as `[fixed_0][str_0][fixed_1][str_1]...`). Does NOT block SFTP `Name` packet handling — SFTP serializes this as a sequence of length-prefixed strings (the serde `SeqAccess` pattern), not as an array of fixed-stride structs. Does NOT block any current consumer.
|
||||
- **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.
|
||||
- **Resolution**: Not yet decidable. The mechanism (lazy sequential
|
||||
walking of array elements, reading each element's length prefixes to
|
||||
find the next element's start) is understood but not needed by any
|
||||
current consumer. Arrays of fixed-size structs are fully supported.
|
||||
- **Cross-references**: ADR-096, [layout-engine.md](crates/typedef/layout-engine.md)
|
||||
Reference in new issue
Block a user