alkdev/alktype
6
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rebrand TypeDef to AlkType in code, keyword strings, and docs

Browse Source 
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.
This commit is contained in:
glm-5.2 committed 2026-08-02 07:05:53 +00:00
1 parent 1cfb3638d1
commit 5e268e8f47
31 files changed
+1851 -1851
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

src/offset_map.rs
+127 -127
View File
@@ -11,10 +11,10 @@
//! to satisfy the field's alignment requirement (natural alignment by
//! default, overridable via the `"align"` annotation).
use crate::error::TypedefError;
use crate::error::AlkTypeError;
use crate::schema::{
get_typedef_kind, get_typedef_kind_loose_enum, parse_align, parse_encoding,
parse_max_length, resolve_ref_or_inline, TypeDefKind, VariableEncoding,
get_alktype_kind, get_alktype_kind_loose_enum, parse_align, parse_encoding,
parse_max_length, resolve_ref_or_inline, AlkTypeKind, VariableEncoding,
};
use serde_json::Value;
@@ -67,25 +67,25 @@ impl OffsetMap {
///
/// Walks the schema recursively, computing byte positions for each
/// field based on type sizes, field order, and alignment. The
/// top-level schema must be a `TypeDef:Struct`.
/// top-level schema must be a `AlkType:Struct`.
///
/// # Errors
///
/// Returns [`TypedefError::Schema`] if the top-level schema is not a
/// `TypeDef:Struct` or has no `TypeDef:*` kind, or if the schema is
/// Returns [`AlkTypeError::Schema`] if the top-level schema is not a
/// `AlkType:Struct` or has no `AlkType:*` kind, or if the schema is
/// malformed (missing `properties`, unknown kind, etc.).
///
/// Returns [`TypedefError::Offset`] for unsupported type combinations
/// Returns [`AlkTypeError::Offset`] for unsupported type combinations
/// encountered during the walk.
pub fn compute(schema: &Value) -> Result<Self, TypedefError> {
let kind = get_typedef_kind(schema)
.and_then(|s| s.parse::<TypeDefKind>().ok())
pub fn compute(schema: &Value) -> Result<Self, AlkTypeError> {
let kind = get_alktype_kind(schema)
.and_then(|s| s.parse::<AlkTypeKind>().ok())
.ok_or_else(|| {
TypedefError::Schema("top-level schema has no TypeDef:* kind".to_string())
AlkTypeError::Schema("top-level schema has no AlkType:* kind".to_string())
})?;
if kind != TypeDefKind::Struct {
return Err(TypedefError::Schema(format!(
"OffsetMap::compute requires a TypeDef:Struct at the top level, got {kind}"
if kind != AlkTypeKind::Struct {
return Err(AlkTypeError::Schema(format!(
"OffsetMap::compute requires a AlkType:Struct at the top level, got {kind}"
)));
}
let mut ctx = ComputeCtx {
@@ -145,7 +145,7 @@ struct FieldLayout {
}
impl<'a> ComputeCtx<'a> {
/// Recurse into a `TypeDef:Struct`, appending `(field_path, ByteRange)`
/// Recurse into a `AlkType:Struct`, appending `(field_path, ByteRange)`
/// pairs to `self.fields` and advancing `self.offset`.
///
/// Returns `(total_size, alignment)` where `total_size` includes
@@ -163,15 +163,15 @@ impl<'a> ComputeCtx<'a> {
struct_schema: &Value,
prefix: &str,
parent_struct_align: usize,
) -> Result<(usize, usize), TypedefError> {
) -> Result<(usize, usize), AlkTypeError> {
let obj = struct_schema
.as_object()
.ok_or_else(|| TypedefError::Schema("struct schema is not an object".to_string()))?;
.ok_or_else(|| AlkTypeError::Schema("struct schema is not an object".to_string()))?;
let properties = obj
.get("properties")
.and_then(|v| v.as_object())
.ok_or_else(|| {
TypedefError::Schema("struct schema has no 'properties' object".to_string())
AlkTypeError::Schema("struct schema has no 'properties' object".to_string())
})?;
let struct_default_align = parse_align(struct_schema).unwrap_or(parent_struct_align);
@@ -194,13 +194,13 @@ impl<'a> ComputeCtx<'a> {
// data_access::write_string writes prefix+data inline — clobbering
// subsequent fields. Only allowed as the last field in the struct.
if i < field_count - 1 {
if let Some(kind) = get_typedef_kind_loose_enum(field_schema) {
if let Some(kind) = get_alktype_kind_loose_enum(field_schema) {
if kind.is_variable_length() {
let keyword_value = field_schema
.as_object()
.and_then(|o| {
o.keys()
.find(|k| k.starts_with("TypeDef:"))
.find(|k| k.starts_with("AlkType:"))
.and_then(|k| o.get(k))
})
.cloned()
@@ -210,7 +210,7 @@ impl<'a> ComputeCtx<'a> {
let is_inline_length_prefixed =
encoding == VariableEncoding::LengthPrefixed && max_length.is_none();
if is_inline_length_prefixed {
return Err(TypedefError::Offset {
return Err(AlkTypeError::Offset {
field_path: field_path.clone(),
reason: format!(
"non-final inline length-prefixed variable field \
@@ -244,17 +244,17 @@ impl<'a> ComputeCtx<'a> {
field_schema: &Value,
field_path: &str,
struct_default_align: usize,
) -> Result<FieldLayout, TypedefError> {
let kind = get_typedef_kind_loose_enum(field_schema).ok_or_else(|| TypedefError::Offset {
) -> Result<FieldLayout, AlkTypeError> {
let kind = get_alktype_kind_loose_enum(field_schema).ok_or_else(|| AlkTypeError::Offset {
field_path: field_path.to_string(),
reason: "field schema has no TypeDef:* kind".to_string(),
reason: "field schema has no AlkType:* kind".to_string(),
})?;
match kind {
TypeDefKind::Struct => {
AlkTypeKind::Struct => {
self.compute_struct_field(field_schema, field_path, struct_default_align)
}
TypeDefKind::Union => Err(TypedefError::Offset {
AlkTypeKind::Union => Err(AlkTypeError::Offset {
field_path: field_path.to_string(),
reason: "TUnion is not supported in aligned static mode (ADR-102). \
Unions are the protocol dispatch pattern — use packed sequential \
@@ -262,31 +262,31 @@ impl<'a> ComputeCtx<'a> {
a struct with an explicit discriminator field."
.to_string(),
}),
TypeDefKind::Array => {
AlkTypeKind::Array => {
self.compute_array_field(field_schema, field_path, struct_default_align)
}
TypeDefKind::String
| TypeDefKind::Bytes
| TypeDefKind::Record
| TypeDefKind::Timestamp => {
AlkTypeKind::String
| AlkTypeKind::Bytes
| AlkTypeKind::Record
| AlkTypeKind::Timestamp => {
self.compute_variable_field(field_schema, field_path, struct_default_align)
}
k if k.is_fixed_size() => {
self.compute_fixed_field(k, field_schema, field_path, struct_default_align)
}
_ => unreachable!("all TypeDefKind variants are covered above"),
_ => unreachable!("all AlkTypeKind variants are covered above"),
}
}
/// Compute the layout for a fixed-size primitive field.
fn compute_fixed_field(
&mut self,
kind: TypeDefKind,
kind: AlkTypeKind,
field_schema: &Value,
field_path: &str,
struct_default_align: usize,
) -> Result<FieldLayout, TypedefError> {
let size = kind.type_size().ok_or_else(|| TypedefError::Offset {
) -> Result<FieldLayout, AlkTypeError> {
let size = kind.type_size().ok_or_else(|| AlkTypeError::Offset {
field_path: field_path.to_string(),
reason: format!("type_size returned None for fixed kind {kind}"),
})?;
@@ -299,7 +299,7 @@ impl<'a> ComputeCtx<'a> {
Ok(FieldLayout { align })
}
/// Compute the layout for a nested `TypeDef:Struct` field.
/// Compute the layout for a nested `AlkType:Struct` field.
///
/// Probes the nested struct's layout at a temporary offset of 0 to
/// determine its total size and alignment, aligns the parent offset,
@@ -309,7 +309,7 @@ impl<'a> ComputeCtx<'a> {
field_schema: &Value,
field_path: &str,
struct_default_align: usize,
) -> Result<FieldLayout, TypedefError> {
) -> Result<FieldLayout, AlkTypeError> {
let inner_parent_align = parse_align(field_schema).unwrap_or(struct_default_align);
let mut probe = ComputeCtx {
root: self.root,
@@ -335,37 +335,37 @@ impl<'a> ComputeCtx<'a> {
Ok(FieldLayout { align })
}
/// Compute the layout for a `TypeDef:Array` field.
/// Compute the layout for a `AlkType:Array` field.
fn compute_array_field(
&mut self,
field_schema: &Value,
field_path: &str,
struct_default_align: usize,
) -> Result<FieldLayout, TypedefError> {
) -> Result<FieldLayout, AlkTypeError> {
let obj = field_schema
.as_object()
.ok_or_else(|| TypedefError::Offset {
.ok_or_else(|| AlkTypeError::Offset {
field_path: field_path.to_string(),
reason: "array schema is not an object".to_string(),
})?;
let items = obj.get("items").ok_or_else(|| TypedefError::Offset {
let items = obj.get("items").ok_or_else(|| AlkTypeError::Offset {
field_path: field_path.to_string(),
reason: "TArray is missing 'items'".to_string(),
})?;
let element_schema =
resolve_ref_or_inline(items, self.root).ok_or_else(|| TypedefError::Offset {
resolve_ref_or_inline(items, self.root).ok_or_else(|| AlkTypeError::Offset {
field_path: field_path.to_string(),
reason: "could not resolve TArray items schema".to_string(),
})?;
let elem_kind = get_typedef_kind(element_schema)
.and_then(|s| s.parse::<TypeDefKind>().ok())
.ok_or_else(|| TypedefError::Offset {
let elem_kind = get_alktype_kind(element_schema)
.and_then(|s| s.parse::<AlkTypeKind>().ok())
.ok_or_else(|| AlkTypeError::Offset {
field_path: field_path.to_string(),
reason: "TArray element schema has no TypeDef:* kind".to_string(),
reason: "TArray element schema has no AlkType:* kind".to_string(),
})?;
if !elem_kind.is_fixed_size() {
return Err(TypedefError::Offset {
return Err(AlkTypeError::Offset {
field_path: field_path.to_string(),
reason: format!(
"TArray of variable-length element kind {elem_kind} is not supported (OQ-069)"
@@ -373,7 +373,7 @@ impl<'a> ComputeCtx<'a> {
});
}
let elem_size = elem_kind.type_size().ok_or_else(|| TypedefError::Offset {
let elem_size = elem_kind.type_size().ok_or_else(|| AlkTypeError::Offset {
field_path: field_path.to_string(),
reason: format!("element kind {elem_kind} has no fixed size"),
})?;
@@ -431,12 +431,12 @@ impl<'a> ComputeCtx<'a> {
field_schema: &Value,
field_path: &str,
struct_default_align: usize,
) -> Result<FieldLayout, TypedefError> {
) -> Result<FieldLayout, AlkTypeError> {
let keyword_value = field_schema
.as_object()
.and_then(|o| {
o.keys()
.find(|k| k.starts_with("TypeDef:"))
.find(|k| k.starts_with("AlkType:"))
.and_then(|k| o.get(k))
})
.cloned()
@@ -510,10 +510,10 @@ mod tests {
#[test]
fn simple_fixed_fields_natural_alignment() {
let schema = json!({
"TypeDef:Struct": true,
"AlkType:Struct": true,
"properties": {
"flag": { "TypeDef:Uint8": true },
"id": { "TypeDef:Uint32": true }
"flag": { "AlkType:Uint8": true },
"id": { "AlkType:Uint32": true }
}
});
let m = map(&schema);
@@ -525,10 +525,10 @@ mod tests {
#[test]
fn u8_then_u32_three_bytes_padding() {
let schema = json!({
"TypeDef:Struct": true,
"AlkType:Struct": true,
"properties": {
"a": { "TypeDef:Uint8": true },
"b": { "TypeDef:Uint32": true }
"a": { "AlkType:Uint8": true },
"b": { "AlkType:Uint32": true }
}
});
let m = map(&schema);
@@ -539,16 +539,16 @@ mod tests {
#[test]
fn nested_struct_dotted_paths() {
let schema = json!({
"TypeDef:Struct": true,
"AlkType:Struct": true,
"properties": {
"header": {
"TypeDef:Struct": true,
"AlkType:Struct": true,
"properties": {
"magic": { "TypeDef:Uint32": true },
"version": { "TypeDef:Uint8": true }
"magic": { "AlkType:Uint32": true },
"version": { "AlkType:Uint8": true }
}
},
"body": { "TypeDef:Uint32": true }
"body": { "AlkType:Uint32": true }
}
});
let m = map(&schema);
@@ -564,11 +564,11 @@ mod tests {
#[test]
fn array_fixed_count_element_offsets() {
let schema = json!({
"TypeDef:Struct": true,
"AlkType:Struct": true,
"properties": {
"vals": {
"TypeDef:Array": true,
"items": { "TypeDef:Uint32": true },
"AlkType:Array": true,
"items": { "AlkType:Uint32": true },
"minItems": 3,
"maxItems": 3
}
@@ -584,11 +584,11 @@ mod tests {
#[test]
fn array_variable_count_length_prefix() {
let schema = json!({
"TypeDef:Struct": true,
"AlkType:Struct": true,
"properties": {
"vals": {
"TypeDef:Array": true,
"items": { "TypeDef:Uint32": true }
"AlkType:Array": true,
"items": { "AlkType:Uint32": true }
}
}
});
@@ -600,10 +600,10 @@ mod tests {
#[test]
fn variable_string_length_prefix_at_known_offset() {
let schema = json!({
"TypeDef:Struct": true,
"AlkType:Struct": true,
"properties": {
"id": { "TypeDef:Uint32": true },
"name": { "TypeDef:String": true }
"id": { "AlkType:Uint32": true },
"name": { "AlkType:String": true }
}
});
let m = map(&schema);
@@ -615,10 +615,10 @@ mod tests {
#[test]
fn variable_string_max_length_reservation() {
let schema = json!({
"TypeDef:Struct": true,
"AlkType:Struct": true,
"properties": {
"id": { "TypeDef:Uint32": true },
"name": { "TypeDef:String": true, "maxLength": 256 }
"id": { "AlkType:Uint32": true },
"name": { "AlkType:String": true, "maxLength": 256 }
}
});
let m = map(&schema);
@@ -630,10 +630,10 @@ mod tests {
#[test]
fn variable_string_offset_indirect_eight_bytes() {
let schema = json!({
"TypeDef:Struct": true,
"AlkType:Struct": true,
"properties": {
"id": { "TypeDef:Uint32": true },
"blob": { "TypeDef:String": { "encoding": "offset-indirect" } }
"id": { "AlkType:Uint32": true },
"blob": { "AlkType:String": { "encoding": "offset-indirect" } }
}
});
let m = map(&schema);
@@ -645,14 +645,14 @@ mod tests {
#[test]
fn union_byte_discriminator_rejected_in_aligned_mode() {
let schema = json!({
"TypeDef:Struct": true,
"AlkType:Struct": true,
"properties": {
"payload": {
"TypeDef:Union": true,
"AlkType:Union": true,
"discriminator": {
"kind": "byte",
"offset": 0,
"type": "TypeDef:Uint8"
"type": "AlkType:Uint8"
},
"mapping": {
"5": { "$ref": "#/$defs/Read" },
@@ -662,26 +662,26 @@ mod tests {
},
"$defs": {
"Read": {
"TypeDef:Struct": true,
"AlkType:Struct": true,
"properties": {
"handle": { "TypeDef:Uint32": true },
"length": { "TypeDef:Uint32": true }
"handle": { "AlkType:Uint32": true },
"length": { "AlkType:Uint32": true }
}
},
"Write": {
"TypeDef:Struct": true,
"AlkType:Struct": true,
"properties": {
"handle": { "TypeDef:Uint32": true },
"length": { "TypeDef:Uint32": true },
"data": { "TypeDef:Uint32": true }
"handle": { "AlkType:Uint32": true },
"length": { "AlkType:Uint32": true },
"data": { "AlkType:Uint32": true }
}
}
}
});
let err = OffsetMap::compute(&schema).unwrap_err();
assert!(matches!(err, TypedefError::Offset { .. }), "got {err:?}");
assert!(matches!(err, AlkTypeError::Offset { .. }), "got {err:?}");
let reason = match err {
TypedefError::Offset { reason, .. } => reason,
AlkTypeError::Offset { reason, .. } => reason,
_ => unreachable!(),
};
assert!(reason.contains("ADR-102"), "reason: {reason}");
@@ -690,10 +690,10 @@ mod tests {
#[test]
fn union_field_name_discriminator_rejected_in_aligned_mode() {
let schema = json!({
"TypeDef:Struct": true,
"AlkType:Struct": true,
"properties": {
"event": {
"TypeDef:Union": true,
"AlkType:Union": true,
"discriminator": { "kind": "field", "name": "type" },
"mapping": {
"read": { "$ref": "#/$defs/Read" },
@@ -703,38 +703,38 @@ mod tests {
},
"$defs": {
"Read": {
"TypeDef:Struct": true,
"AlkType:Struct": true,
"properties": {
"type": { "TypeDef:Uint8": true },
"handle": { "TypeDef:Uint32": true }
"type": { "AlkType:Uint8": true },
"handle": { "AlkType:Uint32": true }
}
},
"Write": {
"TypeDef:Struct": true,
"AlkType:Struct": true,
"properties": {
"type": { "TypeDef:Uint8": true },
"handle": { "TypeDef:Uint32": true },
"length": { "TypeDef:Uint32": true }
"type": { "AlkType:Uint8": true },
"handle": { "AlkType:Uint32": true },
"length": { "AlkType:Uint32": true }
}
}
}
});
let err = OffsetMap::compute(&schema).unwrap_err();
assert!(matches!(err, TypedefError::Offset { .. }), "got {err:?}");
assert!(matches!(err, AlkTypeError::Offset { .. }), "got {err:?}");
}
#[test]
fn non_final_inline_string_rejected_in_aligned_mode() {
let schema = json!({
"TypeDef:Struct": true,
"AlkType:Struct": true,
"properties": {
"name": { "TypeDef:String": true },
"id": { "TypeDef:Uint32": true }
"name": { "AlkType:String": true },
"id": { "AlkType:Uint32": true }
}
});
let err = OffsetMap::compute(&schema).unwrap_err();
match err {
TypedefError::Offset { field_path, reason } => {
AlkTypeError::Offset { field_path, reason } => {
assert_eq!(field_path, "name");
assert!(reason.contains("ADR-100"), "reason: {reason}");
}
@@ -745,10 +745,10 @@ mod tests {
#[test]
fn final_inline_string_allowed_in_aligned_mode() {
let schema = json!({
"TypeDef:Struct": true,
"AlkType:Struct": true,
"properties": {
"id": { "TypeDef:Uint32": true },
"name": { "TypeDef:String": true }
"id": { "AlkType:Uint32": true },
"name": { "AlkType:String": true }
}
});
let m = map(&schema);
@@ -759,10 +759,10 @@ mod tests {
#[test]
fn non_final_maxlength_string_allowed_in_aligned_mode() {
let schema = json!({
"TypeDef:Struct": true,
"AlkType:Struct": true,
"properties": {
"name": { "TypeDef:String": true, "maxLength": 256 },
"id": { "TypeDef:Uint32": true }
"name": { "AlkType:String": true, "maxLength": 256 },
"id": { "AlkType:Uint32": true }
}
});
let m = map(&schema);
@@ -773,10 +773,10 @@ mod tests {
#[test]
fn non_final_offset_indirect_string_allowed_in_aligned_mode() {
let schema = json!({
"TypeDef:Struct": true,
"AlkType:Struct": true,
"properties": {
"blob": { "TypeDef:String": { "encoding": "offset-indirect" } },
"id": { "TypeDef:Uint32": true }
"blob": { "AlkType:String": { "encoding": "offset-indirect" } },
"id": { "AlkType:Uint32": true }
}
});
let m = map(&schema);
@@ -787,10 +787,10 @@ mod tests {
#[test]
fn struct_level_align_rounds_up_total() {
let schema = json!({
"TypeDef:Struct": true,
"AlkType:Struct": true,
"align": 16,
"properties": {
"flag": { "TypeDef:Uint8": true }
"flag": { "AlkType:Uint8": true }
}
});
let m = map(&schema);
@@ -801,12 +801,12 @@ mod tests {
#[test]
fn field_level_align_overrides_struct_default() {
let schema = json!({
"TypeDef:Struct": true,
"AlkType:Struct": true,
"align": 1,
"properties": {
"tag": { "TypeDef:Uint8": true },
"flag": { "TypeDef:Uint8": true, "align": 16 },
"id": { "TypeDef:Uint32": true }
"tag": { "AlkType:Uint8": true },
"flag": { "AlkType:Uint8": true, "align": 16 },
"id": { "AlkType:Uint32": true }
}
});
let m = map(&schema);
@@ -819,11 +819,11 @@ mod tests {
#[test]
fn field_align_smaller_than_struct_default() {
let schema = json!({
"TypeDef:Struct": true,
"AlkType:Struct": true,
"align": 8,
"properties": {
"a": { "TypeDef:Uint8": true },
"b": { "TypeDef:Uint32": true, "align": 1 }
"a": { "AlkType:Uint8": true },
"b": { "AlkType:Uint32": true, "align": 1 }
}
});
let m = map(&schema);
@@ -835,10 +835,10 @@ mod tests {
#[test]
fn iter_returns_all_paths_in_order() {
let schema = json!({
"TypeDef:Struct": true,
"AlkType:Struct": true,
"properties": {
"a": { "TypeDef:Uint8": true },
"b": { "TypeDef:Uint32": true }
"a": { "AlkType:Uint8": true },
"b": { "AlkType:Uint32": true }
}
});
let m = map(&schema);
@@ -849,16 +849,16 @@ mod tests {
#[test]
fn compute_rejects_non_struct_top_level() {
let schema =
json!({ "TypeDef:Union": true, "discriminator": { "kind": "byte" }, "mapping": {} });
json!({ "AlkType:Union": true, "discriminator": { "kind": "byte" }, "mapping": {} });
let err = OffsetMap::compute(&schema).unwrap_err();
assert!(matches!(err, TypedefError::Schema(_)));
assert!(matches!(err, AlkTypeError::Schema(_)));
}
#[test]
fn compute_rejects_missing_typedef_kind() {
fn compute_rejects_missing_alktype_kind() {
let schema = json!({ "type": "object", "properties": {} });
let err = OffsetMap::compute(&schema).unwrap_err();
assert!(matches!(err, TypedefError::Schema(_)));
assert!(matches!(err, AlkTypeError::Schema(_)));
}
#[test]