From 82fec45bc6938c6efb314120fdf4d6cbcc23a33f Mon Sep 17 00:00:00 2001 From: "glm-5.2" Date: Sun, 16 Aug 2026 09:45:01 +0000 Subject: [PATCH] Sync docs to 18 BAST kinds (Timestamp removal fallout) - README: 19 -> 18 kinds, drop the timestamp row from the kinds table, drop 'timestamp shape' from the validate_bytes constraint list, remove the residual 'upcoming alkcall crate' sentence from the crate independence section (alkcall exists now), fix two '19 kinds' refs in the documentation pointer list and schema-layer link. - src/data_access.rs: module doc comment still said 'all 19 AlkType kinds' -> 18. - bast-format.md (normative): 19 -> 18 AlkTypeKind enum variants. - layout-engine.md: cross-reference to 'the 19 AlkType kinds' -> 18. - ADR-BAST (bast-bast-format.md): the Decision section claimed the post- pivot enum has '19 unchanged' variants; now 18, with the wording adjusted so it no longer says 'unchanged' across the pivot. - ADR-VAL-SPLIT: drop 'timestamp shape' from the value-domain constraint list and the validator-arm table row (validate_timestamp no longer exists). Left as historically accurate (describe the v0.1.0 pre-pivot state): ADR-003/004/006 Context mentions of AlkType:Timestamp, ADR-005 'engine now has 19', and the '19 jsonschema::Keyword factories' references in the What-is-removed sections of ADR-BAST and ADR-VAL-SPLIT. Verification: cargo test --release (407 pass), cargo clippy --all-targets -- -D warnings (clean), cargo doc --no-deps (clean), cargo build --target wasm32-unknown-unknown --release (clean). --- README.md | 14 +++++--------- docs/architecture/bast-format.md | 2 +- docs/architecture/decisions/bast-bast-format.md | 4 ++-- .../decisions/val-split-two-validator-model.md | 3 +-- docs/architecture/layout-engine.md | 2 +- src/data_access.rs | 2 +- 6 files changed, 11 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 50ff9f5..3b38341 100644 --- a/README.md +++ b/README.md @@ -101,7 +101,7 @@ let engine = AlkTypeEngine::compile(&doc, "ChunkHeader", LayoutMode::Packed, Non # Ok::<(), alktype::AlkTypeError>(()) ``` -## The 19 BAST kinds +## The 18 BAST kinds | `kind` | Rust type | Size | Notes | |--------|-----------|-----:|-------| @@ -119,13 +119,12 @@ let engine = AlkTypeEngine::compile(&doc, "ChunkHeader", LayoutMode::Packed, Non | `enum` | `u32` index | 4 | index into the `values` array; bounds-checked by the BAST-native validator | | `string` | length-prefixed UTF-8 | 4 + N | `[length: u32][bytes]` by default | | `bytes` | length-prefixed raw bytes | 4 + N | `[length: u32][bytes]` by default | -| `timestamp` | length-prefixed RFC 3339 | 4 + N | non-strict string check (see inline docs) | | `struct` | record of fields | composite | nested; field paths are dotted (`"header.version"`) | | `union` | tagged union | composite | byte-offset or field-name discriminator | | `array` | repeated element | composite | fixed-size elements with stride; `count` required in v1 (D-BAST-004) | | `record` | string-keyed map | composite | `[count: u32][key, value]...` | -The 19 kinds map to the `AlkTypeKind` Rust enum. `AlkTypeKind::to_bast_str`/ +The 18 kinds map to the `AlkTypeKind` Rust enum. `AlkTypeKind::to_bast_str`/ `from_bast_str` convert between the enum and the lowercase BAST strings (D-BAST-002). Only `struct`, `union`, and `enum` can appear as named `$defs` entries; primitives, arrays, and records appear as field/element/ @@ -186,7 +185,7 @@ types (ADR-VAL-SPLIT): the layout engine, then runs the **BAST-native validator** — a recursive walker over the BAST type tree that checks the value-domain constraints the materializer doesn't (integer ranges, `maxLength`, - timestamp shape, enum index bounds, union variant constraints). No + enum index bounds, union variant constraints). No `jsonschema` involvement; the BAST document is the complete validation spec for bytes (D-BAST-006). - `validate_json(&Value)` / `is_valid_json(&Value)` — for already-parsed @@ -232,10 +231,7 @@ for the full spec. `alktype` does **not** depend on any application or networking crate. It defines its own types (`AlkTypeError`, `AlkTypeEngine`, `FieldValue`, etc.) and is usable in contexts where networking doesn't exist — CLI -tools, test harnesses, schema-building utilities, and WASM targets. The -upcoming `alkcall` crate (the `alknet-call` + `alknet-channels` -unification) depends on `alktype` for both binary layout and JSON -payload schemas; `alktype` knows nothing about `alkcall`. +tools, test harnesses, schema-building utilities, and WASM targets. ## Schemas as untrusted input @@ -257,7 +253,7 @@ Architecture documentation lives under [`docs/architecture/`](docs/architecture/ - [BAST format](docs/architecture/bast-format.md) — **normative format spec**: meta-schema, TypeRef, TypeDef shapes, validation model - [Schema layer](docs/architecture/schema-layer.md) — the BAST parser - (`BastDoc`/`BastDef`/`BastType` typed tree), the 19 kinds, the + (`BastDoc`/`BastDef`/`BastType` typed tree), the 18 kinds, the `AlkTypeKind` enum - [Layout engine](docs/architecture/layout-engine.md) — offset computation, the two layout modes, alignment, endianness diff --git a/docs/architecture/bast-format.md b/docs/architecture/bast-format.md index 50e17ea..4ce1c6b 100644 --- a/docs/architecture/bast-format.md +++ b/docs/architecture/bast-format.md @@ -39,7 +39,7 @@ custom-keyword content. 3. **`kind`-based vocabulary.** Every type has a `kind` field whose value is a known string (`"uint32"`, `"struct"`, `"union"`, etc.). This replaces the `AlkType:*` custom-keyword pattern with a flat, - easily-matched string. The 19 `AlkTypeKind` enum variants are + easily-matched string. The 18 `AlkTypeKind` enum variants are unchanged; `AlkTypeKind::from_str`/`to_str` map between the enum and the lowercase BAST strings (D-BAST-002). diff --git a/docs/architecture/decisions/bast-bast-format.md b/docs/architecture/decisions/bast-bast-format.md index e922c0c..38f5385 100644 --- a/docs/architecture/decisions/bast-bast-format.md +++ b/docs/architecture/decisions/bast-bast-format.md @@ -90,8 +90,8 @@ its consequences; the spec records the shape. 3. **`kind`-based vocabulary.** Every type has a `kind` field whose value is a known string (`"uint32"`, `"struct"`, `"union"`, etc.). This replaces the `AlkType:*` custom-keyword pattern with a flat, - easily-matched string. The 19 `AlkTypeKind` enum variants are - unchanged; `AlkTypeKind::from_bast_str`/`to_bast_str` map between + easily-matched string. The 18 `AlkTypeKind` enum variants are + the BAST kinds; `AlkTypeKind::from_bast_str`/`to_bast_str` map between the enum and the lowercase BAST strings (D-BAST-002). 4. **Order is explicit.** Struct fields are an ordered array, not an object with `properties`. Field order is unambiguous — no reliance diff --git a/docs/architecture/decisions/val-split-two-validator-model.md b/docs/architecture/decisions/val-split-two-validator-model.md index 5716575..dfef36f 100644 --- a/docs/architecture/decisions/val-split-two-validator-model.md +++ b/docs/architecture/decisions/val-split-two-validator-model.md @@ -27,7 +27,7 @@ paths: needed for `validate_bytes`; the BAST document *is* the validation spec for bytes. The natural validator is a recursive walker over the BAST type tree that checks the value-domain constraints the - materializer does not (integer ranges, `maxLength`, timestamp shape, + materializer does not (integer ranges, `maxLength`, enum index bounds, union variant constraints). The POC (`bast-validator-poc` branch, `src/bast_poc.rs`) proved this out end-to-end with 20 reference tests. @@ -75,7 +75,6 @@ alone: | Float finiteness (Float32/64) | `validate_float` | | String `maxLength` (byte length) | `check_string` | | Bytes `maxLength` (array length) | `check_bytes` (accepts `Value::String` and `Value::Array`) | -| RFC 3339 timestamp shape | `validate_timestamp` (non-strict, matching v0.1.0) | | Enum index bounds | `validate_enum` — **fixes the v0.1.0 dead constraint** | | Union variant dispatch | `validate_union` reads `__discriminator`, resolves the variant, recurses | | Struct fields | `validate_struct` walks `fields`, requires each declared field present, recurses | diff --git a/docs/architecture/layout-engine.md b/docs/architecture/layout-engine.md index 15077c6..960ad91 100644 --- a/docs/architecture/layout-engine.md +++ b/docs/architecture/layout-engine.md @@ -356,7 +356,7 @@ See [open-questions.md](open-questions.md) for full details. the two layout modes decision - [ADR-003](decisions/003-schema-annotations.md) — schema annotations -- [schema-layer.md](schema-layer.md) — the 19 AlkType kinds and their +- [schema-layer.md](schema-layer.md) — the 18 AlkType kinds and their byte sizes - [data-access.md](data-access.md) — read/write functions that use the computed offsets diff --git a/src/data_access.rs b/src/data_access.rs index 2a16dec..f05b6d8 100644 --- a/src/data_access.rs +++ b/src/data_access.rs @@ -1,4 +1,4 @@ -//! Data access layer: primitive read/write functions for all 19 AlkType +//! Data access layer: primitive read/write functions for all 18 AlkType //! kinds with endianness support, bounds checking, and zero-copy access. //! //! These are the building blocks used by the layout types ([`crate::offset_map`],