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:
deepseek-v4-pro committed 2026-07-20 11:57:03 +00:00
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)