f7c71da9e5cfa9da2fb132baf0bf8cb1db40d5a9
15
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 glm-5.2
|
1037e68091 |
Accept ADR-011: compiled read plan for packed mode
Tighten framing per pre-acceptance review (no decision changes): - Be precise about M1 coverage: closes the packed-side site (engine.rs:284 validate_bytes); the aligned-side M1 sites (engine.rs:334,467, layout_builder.rs:190) are a deliberate reversible bet, not a non-issue. - Replace the 'two type walkers is symmetric with OffsetMap/ PackedLayout' spin with an honest 'parallel typed tree, permanent maintenance tax, justified by ~20-50x composite-dispatch win on SFTP-shaped union-with-$ref-variants packets.' - Move the 'determinism enables fingerprinting/cache/handshake' future work out of the positives list into a dedicated 'Future capabilities' section — it is a forward reference, not a current win. - Clarify bast_doc: Value is retained unconditionally (unused in packed mode, still needed in aligned mode); add a Send+Sync test note for Arc<ReadPlan> shared from the Send+Sync engine. - Tighten the 'no format! allocations' claim to 'no resolve_typeref, no BastDef::parse, no JSON node access on the happy path' (error- path format! remains, and is not the cost being removed). - Add a 'POC coverage' section recording that the readplan-poc branch walked every BastType arm and confirmed ReadPlan covers all cases, including the union Byte/Field split and the array variable-stride (element_stride = 0) case. Status flipped Proposed -> Accepted. README ADR table updated. Verification: docs-only change; cargo test --release, cargo clippy --all-targets -- -D warnings, cargo doc --no-deps unchanged (no source touched). |
||
|
glm-5.2
|
3184818c08 |
Propose ADR-011: compiled read plan for packed mode
Review #004 measured the packed read path at ~400x slower per chunk than a hand-rolled codec, root-caused to SequentialReader re-parsing BastDoc::new on every field read (the 're-parse on demand' framing from ADR-007). The write path is competitive because it has a compiled form (PackedLayout); the read path is the only mode/side pair without one. ADR-011 proposes ReadPlan — the packed read-side compiled form, symmetric to OffsetMap (aligned R/W) and PackedLayout (packed W). Packed positions are data-dependent (variable-length fields shift subsequent fields), so the compiled form is necessarily a read program (a pre-resolved tree of read instructions), not a flat lookup table like OffsetMap. ReadPlan::compile walks BastDoc once at engine construction, resolves all $ref\s eagerly, computes effective endianness at every node, and inlines union variants; the read loop then indexes into a Vec, matches on ReadKind, and calls data_access with a precomputed Endian — no BastDoc, no resolve_typeref, no JSON node access at read time. Scope: SequentialReader and materialize_packed consume the plan (one walker, not two); bast_validation, LayoutBuilder, and aligned one-shot paths stay on BastDoc (different concern, not hot loops). Includes a 7-step Recommended Order matching review #004's structure. Breaking public-API change (0.2.0 -> 0.3.0): SequentialReader::new and materialize_packed take ReadPlan; BastDoc and the Bast* types are unchanged (smaller breakage than review #004's Option A). Cross-links: ADR-007's 'Cost' section gets a Note pointing at review #004 and ADR-011, marking the 're-parse on demand' framing as the root cause slated for retirement (the factory decision itself is retained); the actual Cost/doc-comment rewrite happens in the implementation commit per ADR-011's recommended order. README ADR table updated. Verification: docs-only change, no source touched. Closes review #004 H1, M1 (packed side), L1, L2 (on implementation). |
||
|
glm-5.2
|
82fec45bc6 |
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). |
||
 deepseek-v4-pro
|
510553d800 |
Remove the Timestamp kind
The Timestamp kind was a residual from an early research reference. It was byte-identical to String everywhere (length-prefixed UTF-8) and its only distinguishing behavior was a hand-rolled non-strict RFC 3339 check that the docs admitted was incomplete (Feb 31 passes, seconds range unchecked, no leap seconds). JSON-level timestamp validation is jsonschema's job (format: date-time on the validate_json path), not alktype's. Removes the AlkTypeKind::Timestamp variant, its to_bast_str/from_bast_str mapping, the builder's Schema::timestamp() constructor, the validate_timestamp/is_rfc3339_timestamp validator arms, and the materializer/reader/engine timestamp arms. Updates the meta-schema primitive enum (14 -> 13), the spec docs (bast-format.md, schema-layer.md, builder.md, validation.md, overview.md, data-access.md, README.md), and the kind-count references (19 -> 18). 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). |
||
|
deepseek-v4-pro
|
62ed009281 |
Resolve review #003 nits N1, N3, N4
- N1: number_from_f64 now returns AlkTypeError::Access for non-finite floats instead of silently materializing Value::Null. A NaN/Inf in the buffer surfaces as a clear access error rather than a misleading 'expected a number' validation error. - N3: drop the dead Value::String arm from check_bytes; the materializer only ever emits bytes as an array of u8. Update the validation-model docs to match. - N4: fix stale ADR references in doc comments (ADR-096 -> ADR-002, ADR-097 -> ADR-003, ADR-098 -> ADR-004, ADR-101 -> ADR-007). N2 (BastType::alk_kind returning Struct for ) left as documented; every current caller resolves the ref first, so forcing Option through the call sites is churn without benefit. Verification: cargo test --release (411 pass), cargo clippy --all-targets -- -D warnings (clean), cargo doc --no-deps (clean). |
||
|
deepseek-v4-pro
|
230345a867 |
Validate BAST documents against the meta-schema at compile time
Resolves review #003 finding M3. - Add bast_meta::validate_bast_doc and call it from AlkTypeEngine::compile before parsing. Malformed annotations (unknown endian/encoding strings, non-integer align/maxLength, missing required properties) now surface as AlkTypeError::Schema instead of being silently tolerated by the parser. - Align the meta-schema TypeRef with the parser: allow inline struct/union/ enum as TypeRefs (the parser and builder already accepted them; the meta-schema and spec did not). Update bast-format.md TypeRef table and the BastType doc comment to the seven-form vocabulary. Verification: cargo test --release (410 pass), cargo clippy --all-targets -- -D warnings (clean), cargo doc --no-deps (clean), cargo build --target wasm32-unknown-unknown --release (clean). |
||
|
glm-5.2
|
62270b03ca |
Sync architecture docs and ADRs to BAST pivot (steps 9-10)
Step 9 (convert tests to BAST format) was a no-op: steps 4-8 converted
the tests as they went. The only remaining reference in
src/tests was the intentional rejection test at
src/schema.rs:462 (asserting the old keyword form is rejected). Full
suite passes: 389 tests (312 lib + 77 integration).
Step 10 (sync architecture docs and ADRs):
Descriptive docs rewritten/updated for BAST:
- schema-layer.md: rewritten for the BAST parser (BastDoc/BastDef/
BastType typed tree, AlkTypeKind enum with to_bast_str/from_bast_str,
what was removed). Points at bast-format.md for the normative format.
- validation.md: rewritten for the two-validator model
(bast_validation for validate_bytes, standard jsonschema for
validate_json). Documents the repurposed build_validator, the
AlkTypeError::Validation uniform payload (D-BAST-009), and what is
removed.
- builder.md: updated all output examples to BAST JSON
(struct_() -> { kind: struct, fields: [...] }; object() -> standard
JSON Schema). Documents build_doc, count(), and the field-name union
fields requirement (D-BAST-005).
- overview.md: updated for BAST (what/why, schema-is-the-format table,
dependencies, architecture pointers, design decisions table).
- README.md (architecture index): updated document table, ADR table
(new ADR-BAST + ADR-VAL-SPLIT, superseded ADR-001), OQ table
(OQ-007/OQ-008 resolutions updated for BAST-native validator), and
key design principles (#1, #2, #7, #10 reworded for BAST).
- data-access.md: updated tunion function signatures to BastUnion and
the variant resolution to return BastType (resolve_typeref for refs).
- layout-engine.md: updated construct signatures
(LayoutBuilder::new(bast_doc, root_name), OffsetMap::compute(&doc),
SequentialReader::new(bast_doc, root_name)), the recursive-walk
description (BAST typed tree), and composite-kind headings
(TStruct/TUnion/TArray -> struct/union/array). Added D-BAST-004
note on array count requirement.
New ADRs:
- ADR-BAST (bast-bast-format.md): the BAST format, meta-schema,
//kind vocabulary, design principles, what is removed, the
enum index bounds bug fix. Supersedes ADR-001's format-specific
content; records D-BAST-001..009.
- ADR-VAL-SPLIT (val-split-two-validator-model.md): the two-validator
model (BAST-native for validate_bytes, standard jsonschema for
validate_json), the repurposed build_validator, the uniform
AlkTypeError::Validation payload. Refines ADR-004's validation
strategy and ADR-010's validation step; records D-BAST-006/007/009.
Amended ADRs (supersession/amendment notes added; original decision
text preserved as historical record):
- ADR-001: format-specific content superseded by ADR-BAST;
purpose/scope and schema-is-the-format principle retained.
- ADR-002: unchanged under the pivot; one-line note that the input
format changed but the modes didn't.
- ADR-003: annotation semantics retained; annotation location moved
to BAST type-level properties (amended by ADR-BAST).
- ADR-004: AlkTypeError enum retained (D-BAST-009); validation
strategy section refined by ADR-VAL-SPLIT.
- ADR-009: builder API surface retained; build() output format
amended to BAST / standard JSON Schema by ADR-BAST (D-BAST-008).
- ADR-010: validate_bytes two-step concept retained; validation step
amended to the BAST-native validator by ADR-VAL-SPLIT.
Other:
- Cargo.toml description: JSON Schema with AlkType:* custom keywords
-> BAST document.
- bast-pivot.md research record: status draft -> implemented, with a
pointer to the ADRs that superseded its decisions.
- bast-implementation.md plan: status draft -> complete, with a note
that step 9 was a no-op and step 10 is this commit.
- open-questions.md: OQ-006/OQ-007/OQ-008 resolutions updated for the
BAST-native validator.
- questions/008-unionvalidator-variant-dispatch.md: added a
post-BAST-pivot note pointing to the current bast_validation
implementation; v0.1.0 resolution text preserved as historical
record.
Verification:
- cargo test --release: 389 pass (312 lib + 77 integration)
- cargo clippy --all-targets -- -D warnings: clean
- cargo doc --no-deps: clean
- cross-reference check: every relative link in the new/updated docs
resolves (verified by script).
|
||
|
glm-5.2
|
f5f52c61e8 |
Decompose BAST pivot doc into normative spec + implementation plan
The bast-pivot.md research doc had grown to 1477 lines (~58KB) through iterative editing, pushing its most actionable content (D-BAST decisions, POC result, migration steps) past the 50KB Read tool cap. Agents peeking at the truncated file landed in duplicated/out-of-order sections. Decompose into three readable-sized files with distinct roles: - docs/architecture/bast-format.md (28KB, new): the normative BAST format spec -- meta-schema, TypeRef, examples, validation model. Grounded in the POC and D-BAST-001..009. Stable and safe to write now; schema-layer.md/validation.md stay describing current code and are rewritten post-implementation (per AGENTS.md ADR-grounding rule). - docs/plans/bast-implementation.md (31KB, new): the execution entry point -- ordered 10-step plan with per-step goal/files/spec-ref/ verification, the public-API semver contract table up front as a scope-creep guardrail, and the ADR-sync checklist at the end. Each step links to the specific bast-format.md section and D-BAST anchor. - docs/research/bast-pivot.md (28KB, trimmed): now the research record only -- Summary, Motivation, POC scope/result, Decisions, Risks, References. The normative format spec, what-changes tables, validator-split details, and migration steps moved to the two new docs; pointers added. 1155 lines removed, 216 added. - docs/architecture/README.md: index updated to list bast-format.md and the two in-progress pivot docs, with notes on schema-layer.md and validation.md being rewritten when the pivot lands. All three files are under the 50KB Read cap, so an implementing agent gets the whole document in one call. Cross-reference anchors verified to resolve. No code changes; cargo test --release (396 tests) green. Verification: cargo test --release (310 crate + 86 integration, all pass). |
||
|
glm-5.2
|
c0217d91a8 |
Resolve v0.1.0 open questions and fix production-readiness issues
POC: /workspace/alktype-builder-poc/ (18/18 tests pass, findings in
docs/research/alktype-builder-poc/findings.md). Round 2 adds the SFTP
Packet validate_bytes tests (7 new: valid Init/Read/Write/Status,
short buffer, unknown discriminator, over-maxLength Bytes).
Open questions resolved (OQ-004 through OQ-008):
- OQ-004: Discriminator::Field name is String (already implemented;
docs updated to mark resolved)
- OQ-005: Both union discriminator kinds return the same shape:
{__discriminator, ...variant-fields}. Field-name path also had a
real offset bug (returned start, not end) - fixed.
- OQ-006: builder.md Example 3 now wraps the Union in a
Schema::struct_().field("payload", ...) and merges $defs via
Definitions::merge_into (matches the engine's AlkType:Struct-at-root
constraint and the SFTP wire shape)
- OQ-007: Bytes materialization is array-of-u8 (Value::Array of
Value::Number, one entry per byte 0..=255). BytesValidator accepts
both Value::String (validate_json) and Value::Array (validate_bytes).
maxLength = max byte count. Replaces the lossy from_utf8_lossy path
that corrupted non-UTF-8 bytes and broke maxLength semantics.
- OQ-008 (new): UnionValidator now dispatches to variant schemas via
sub-validators built at factory time. AlkTypeEngine::compile calls
schema::inline_union_variant_refs before build_validator to inline
$refs in union mapping entries (necessary because union_factory
receives the union node, but $defs live at the schema root).
Production-readiness fixes in src/ (no stubs/hedges in a published crate):
- materialize.rs: Record stub -> full count-prefixed key/value pair
implementation per schema-layer.md TRecord
- materialize.rs: root_of() was broken (returned the current node, not
the schema root) -> root schema threaded through every recursive call
so resolve_ref_or_inline can resolve $refs for nested composites
- builder.rs: LengthPrefixed encoding setter was a no-op when the
keyword was already in object form -> complete the branch (updates
the encoding entry in place for both LengthPrefixed and OffsetIndirect)
- builder.rs, engine.rs: POC-referencing comments cleaned up; the
round-trip test's or_else fallback (papering over write_field being
aligned-only) replaced with direct byte writes
Documentation:
- builder.md: Example 3 updated; Discriminator::Field spec shows String;
Open Questions section updated (OQ-004 resolved)
- validation.md: AlkType:Bytes and AlkType:Union validator descriptions
updated for array-of-u8 form and variant dispatch
- open-questions.md: OQ-004/005/006/007/008 marked resolved; new
Validation theme entries
- questions/004-008: individual OQ files updated with resolutions
- findings.md: round 2 results documented
Verification:
- cargo test: 369 -> 391 tests pass (22 new: 14 materialize, 5
inline_union_variant_refs, 3 validation/builder)
- cargo clippy --all-targets: clean
- POC: 11 -> 18 tests (7 new SFTP Packet tests); all pass
|
||
|
glm-5.2
|
c6893eece8 |
Centralize scattered OQs into the tracker (OQ-004 through OQ-007)
Four open questions were scattered inline in builder.md and the POC findings doc. Moved them into the central OQ tracker under docs/architecture/questions/ and updated the index: - OQ-004: Discriminator::Field name type (&str vs String) — raised in builder.md during ADR-009 spec drafting - OQ-005: Union materialization shape (byte-offset vs field-name consistency) — raised in the POC findings - OQ-006: Builder spec Example 3 wrap Union in Struct — raised in the POC findings (doc fix; engine requires AlkType:Struct at top level) - OQ-007: Bytes materialization lossy UTF-8 — raised in the POC findings (blocks SFTP use case for validate_bytes) Index updates: - open-questions.md: new 'Schema Construction' and 'Validation' theme groups; new 'Open' section for active investigation targets (distinct from 'Deferred / Blocked' which holds scope-parked OQs) - README.md: OQ table extended with OQ-004 through OQ-007 - builder.md: inline OQ-004 replaced with a tracker reference - findings.md: inline OQ-005/006/007 replaced with tracker references Doc-only change; 369 tests pass. |
||
|
glm-5.2
|
1a8a44ed0e |
Draft builder API (ADR-009) and generalized validation validate_bytes (ADR-010) for v0.1.0
- ADR-009: fluent Rust builder producing serde_json::Value, covers AlkType kinds + standard JSON Schema; resolves OQ-003 (alkcall is the unblocking consumer) - ADR-010: AlkTypeEngine::validate_bytes(&[u8]) as the single-call binary-buffer validation entry point; materialize Value from bytes, then validate; two methods on one struct, not a trait - builder.md: full builder API spec (Schema, Definitions, Discriminator) with four usage examples (channels chunk header, call input schema, SFTP Packet union, OperationSpec error schemas) - validation.md: new validate_bytes subsection + entry-point comparison table; AlkTypeEngine impl block updated; design decisions table updated - overview.md: builder.md added to component pointers; 'Not a schema builder' scope boundary retired; ADR-009/010 added to decisions table; OQ-003 marked resolved; Consumers table adds alkcall as first consumer - open-questions.md + questions/003: OQ-003 moved from deferred(scope) to resolved (ADR-009) - README.md: builder doc + ADR-009/010 added; OQ-003 marked resolved; two new Key Design Principles (9, 10) for v0.1.0 additions Doc-only change; 346 tests pass, clippy clean. |
||
|
glm-5.2
|
6d6142978a |
Clean up rebranding drift in docs, agent configs, and source comments
Fix stale references left over from the alknet-typedef → alktype migration: - .opencode/agents/: replace @alkdev/alknet constraints (tokio, crypto, feature flags, anyhow/thiserror) with alktype-accurate ones (sync, AlkTypeError, WASM-clean); fix @alkimiadev → @alkdev org name; remove nonexistent AGENTS.md ref; replace alknet-http/alknet-agent spec examples - docs/sdd_process.md: fix wrong package name (@alkdev/storage → @alkdev/alktype) - docs/architecture/: rewrite dangling /workspace/ and docs/research/ paths as @alkdev/alknet: cross-repo references with explanatory notes; fix @alkimiadev → @alkdev; fix 'not yet used by any alknet crate' stale context - src/ + tests/: correct '17 AlkType kinds' → '19' in doc comments (enum has 19 variants; pre-existing count error); fix dangling /workspace/ path in poc_roundtrip.rs |
||
|
glm-5.2
|
5e268e8f47 |
Rebrand TypeDef to AlkType in code, keyword strings, and docs
Rename all 19 JSON Schema custom keyword strings from "TypeDef:*"
to "AlkType:*" (e.g., "TypeDef:Struct" -> "AlkType:Struct")
across source, tests, and docs. This is a breaking change to the
schema format itself — existing schemas using the old keywords
must be updated.
Rename the Rust identifiers:
- TypedefEngine -> AlkTypeEngine
- TypedefError -> AlkTypeError
- TypeDefKind -> AlkTypeKind
- TYPEDEF_PREFIX -> ALKTYPE_PREFIX
- get_typedef_kind{,_loose,_loose_enum,_enum} ->
get_alktype_kind{,_loose,_loose_enum,_enum}
Update error message strings ("unknown TypeDef kind" ->
"unknown AlkType kind"), 11 test function names containing
typedef_kind/to_typedef_error, and doc-comment prose ("TypeDef
kind" -> "AlkType kind", "typedef engine" -> "alktype
engine", "typedef schema" -> "alktype schema"). Fix the broken
docs/architecture/crates/typedef/ path references in source doc
comments to point at docs/architecture/ directly. Rebrand the
typedef:annotation test fixture and the "not-a-typedef" test
string to their alktype equivalents.
Update ~20 generic "typedef" prose references in the architecture
docs ("typedef is the binary struct engine", "use typedef",
"typedef limitation", "replaced by typedef", etc.) to alktype.
Rename TypedefEngine in the ADR-007 code example to AlkTypeEngine.
Preserve as provenance per the prior prose-rebrand decision:
typedef.ts references (external TypeBox source file),
docs/research/alknet-typedef/findings.md research citations,
/workspace/alknet-typedef-poc/ POC path, and the
"alknet-typedef:" research section headers in findings.
Build, 295 tests, and clippy all pass clean.
|
||
|
glm-5.2
|
1cfb3638d1 |
Rebrand alknet-typedef to alktype in docs, crate name, and lib name
Renumber ADRs 095-102 to 001-008 and OQs 069-071 to 001-003, and update all cross-references (titles, body prose, file-path links, tables) across the 5 spec docs, README, open-questions index, and all 11 ADR/OQ files. Inline the ADR-009 door-type definition from the parent alknet project (broken cross-project reference). Rebrand prose: alknet-typedef -> alktype in headings, body text, dependency diagrams, and "additions" notes. Disambiguate the prior failed attempt at /workspace/@alkimiadev/alktype/ as "the @alkimiadev/alktype prototype" to distinguish it from this crate. Historical research citations (docs/research/*, /workspace/alknet-typedef-poc/) are kept as-is for provenance. Rename the crate in Cargo.toml ([package].name, [lib].name) and update the 11 use alknet_typedef::* imports across the 4 test files. Rebrand the crate-level doc comment in src/lib.rs. The TypeDef:* keyword strings, TypedefError/TypedefEngine identifiers, and other code-level references are unchanged — those are a separate code rebrand pass. Build, 295 tests, and clippy all pass clean. |
||
|
glm-5.2
|
2c4a4994dc |
Port alknet-typedef crate from alknet
Copy the binary struct engine (src/, tests/) verbatim from alknet/crates/alknet-typedef and create a standalone Cargo.toml (workspace-inherited fields inlined). Port the architecture docs (specs, ADRs 095-102, OQs 069-071) from alknet's nested multi-crate layout to a flat single-crate layout, fixing relative link paths. Build, 295 tests, and clippy all pass clean. |