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

Clean up rebranding drift in docs, agent configs, and source comments

Browse Source 
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
This commit is contained in:
glm-5.2 committed 2026-08-02 07:36:28 +00:00
1 parent 5e268e8f47
commit 6d6142978a
24 files changed
+128 -108
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/architecture/README.md
+17 -11
View File
@@ -53,7 +53,7 @@ format definition; the engine is generic.
`jsonschema` crate (v0.46.5, Draft 2020-12) handles validation with
custom keyword support. The novel code is the offset computation, not
the validation. This eliminates ~14,000 lines of hand-rolled schema
engines (typebox-rs, the @alkimiadev/alktype prototype). See [schema-layer.md](schema-layer.md)
engines (typebox-rs, the @alkdev/alktype prototype). See [schema-layer.md](schema-layer.md)
and [ADR-001](decisions/001-alktype-purpose-scope-jsonschema-engine.md).
3. **Two layout modes for two use cases.** Packed sequential
@@ -97,14 +97,20 @@ format definition; the engine is generic.
## References
- `docs/research/alknet-typedef/findings.md` — POC results (26 tests
passing, two layout modes, TUnion dispatch, endianness)
- `docs/research/call-channels-unification/findings.md` §"alknet-typedef:
JSON Schema as the binary struct engine" — the origin of this research
thread
- `/workspace/@alkdev/typebox/example/typedef/typedef.ts` — the TypeBox
- `@alkdev/alknet: docs/research/alknet-typedef/findings.md` — POC results
(26 tests passing, two layout modes, TUnion dispatch, endianness)
- `@alkdev/alknet: docs/research/call-channels-unification/findings.md`
§"alknet-typedef: JSON Schema as the binary struct engine" — the
origin of this research thread
- `@alkdev/alknet: typebox/example/typedef/typedef.ts` — the TypeBox
schema kinds (619 lines)
- `/workspace/jsonschema/` — the jsonschema crate (v0.46.5, Draft 2020-12)
- `/workspace/alknet-typedef-poc/` — the POC code (disposable)
- `/workspace/@alkimiadev/typebox-rs/` — prior attempt, replaced by alktype
- `/workspace/@alkimiadev/alktype/` — prior attempt (the @alkimiadev/alktype prototype, a handler-registry pattern; not to be confused with this crate, which reuses the name but is backed by the `jsonschema` crate)
- `@alkdev/alknet: jsonschema/` — the jsonschema crate (v0.46.5, Draft
2020-12)
- `@alkdev/alknet: alknet-typedef-poc/` — the POC code (disposable)
- `@alkdev/alknet: typebox-rs/` — prior attempt, replaced by alktype
- `@alkdev/alknet: alktype-prototype/` — prior attempt (the @alkdev/alktype prototype, a handler-registry pattern; not to be confused with this crate, which reuses the name but is backed by the `jsonschema` crate)
> **Note**: The research findings, POC code, and prior-attempt paths above
> refer to the parent `@alkdev/alknet` workspace where this crate originated.
> They are preserved here as historical context for the architectural
> decisions; the artifacts themselves are not part of this standalone repo.
docs/architecture/data-access.md
+3 -2
View File
@@ -377,8 +377,9 @@ See [open-questions.md](open-questions.md) for full details.
## References
- `docs/research/alknet-typedef/findings.md` §"POC Results" — POC 1
(read/write round-trip) and POC 2 (SFTP byte-identical round-trip)
- `@alkdev/alknet: docs/research/alknet-typedef/findings.md` §"POC Results"
— POC 1 (read/write round-trip) and POC 2 (SFTP byte-identical
round-trip)
- [layout-engine.md](layout-engine.md) — offset computation that produces
the positions this layer reads/writes at
- [validation.md](validation.md) — validation that runs on the same
docs/architecture/decisions/001-alktype-purpose-scope-jsonschema-engine.md
+19 -14
View File
@@ -9,7 +9,7 @@ Three threads in the codebase converge on the same pattern: a JSON Schema
describes the shape of binary data, and the binary data is the struct's
bytes at computed offsets.
1. **typedef.ts** (`/workspace/@alkdev/typebox/example/typedef/typedef.ts`,
1. **typedef.ts** (`@alkdev/alknet: typebox/example/typedef/typedef.ts`,
619 lines) defines custom TypeBox schema kinds (`TFloat32`, `TStruct`,
`TUnion`, etc.) that carry binary layout semantics. These are registered
via `TypeRegistry.Set` with custom validators.
@@ -34,17 +34,17 @@ generic.
Two prior attempts built their own jsonschema engines — the fatal flaw:
- **typebox-rs** (`/workspace/@alkimiadev/typebox-rs/`, ~8,400 lines):
- **typebox-rs** (`@alkdev/alknet: typebox-rs/`, ~8,400 lines):
a full 26-variant `SchemaKind` enum, a custom `Value` type with typed
arrays, and a 912-line hand-written validator.
- **the @alkimiadev/alktype prototype** (`/workspace/@alkimiadev/alktype/`,
- **the @alkdev/alktype prototype** (`@alkdev/alknet: alktype-prototype/`,
~5,600 lines): a handler-registry pattern that also implements its own
validation for each type. (Not to be confused with this crate, which
reuses the name but is a fresh implementation backed by the `jsonschema`
crate rather than a hand-rolled engine.)
The `jsonschema` crate (v0.46.5, Draft 2020-12) is already in the
workspace at `/workspace/jsonschema/`. It handles validation with custom
workspace at `@alkdev/alknet: jsonschema/`. It handles validation with custom
keyword support — the novel code is the offset computation, not the
validation.
@@ -103,7 +103,7 @@ be added as a feature gate later — the engine's core (offset computation,
### Positive
- **Eliminates ~14,000 lines of hand-rolled schema engines.** typebox-rs
and the @alkimiadev/alktype prototype are replaced by `jsonschema` + an
and the @alkdev/alktype prototype are replaced by `jsonschema` + an
offset map + ~50 lines of custom keyword implementations. The codebase
drops from "a port of TypeBox" to "jsonschema + an offset map."
- **One schema, three uses.** The same JSON Schema validates, computes
@@ -129,7 +129,7 @@ be added as a feature gate later — the engine's core (offset computation,
### Negative
- **New dependency on `jsonschema`.** The crate is already in the
workspace but not yet used by any alknet crate. This is the first
workspace but not yet used by any other crate. This is the first
consumer.
- **`serde_json` with `preserve_order` is required.** Field order is
load-bearing for binary layouts. The `preserve_order` feature adds a
@@ -159,15 +159,20 @@ be added as a feature gate later — the engine's core (offset computation,
## References
- `docs/research/alknet-typedef/findings.md` — POC results (26 tests
passing, two layout modes, TUnion dispatch, endianness)
- `docs/research/call-channels-unification/findings.md` §"alknet-typedef:
JSON Schema as the binary struct engine" — the origin of this research
thread
- `/workspace/@alkdev/typebox/example/typedef/typedef.ts` — the TypeBox
- `@alkdev/alknet: docs/research/alknet-typedef/findings.md` — POC results
(26 tests passing, two layout modes, TUnion dispatch, endianness)
- `@alkdev/alknet: docs/research/call-channels-unification/findings.md`
§"alknet-typedef: JSON Schema as the binary struct engine" — the origin
of this research thread
- `@alkdev/alknet: typebox/example/typedef/typedef.ts` — the TypeBox
schema kinds (619 lines)
- `/workspace/jsonschema/` — the jsonschema crate (v0.46.5, Draft 2020-12)
- `/workspace/alknet-typedef-poc/` — the POC code (disposable)
- `@alkdev/alknet: jsonschema/` — the jsonschema crate (v0.46.5, Draft
2020-12)
- `@alkdev/alknet: alknet-typedef-poc/` — the POC code (disposable)
> Cross-repo references (`@alkdev/alknet: ...`) point to the parent
> monorepo where this crate originated. The artifacts are preserved there
> as historical context; they are not part of this standalone repo.
- [ADR-002](002-two-layout-modes-packed-vs-aligned.md) — the two layout
modes decision
- [ADR-003](003-schema-annotations.md) — schema annotation shapes
docs/architecture/decisions/002-two-layout-modes-packed-vs-aligned.md
+3 -2
View File
@@ -129,8 +129,9 @@ opt-in via the `encoding` annotation (see ADR-003).
## References
- `docs/research/alknet-typedef/findings.md` §"POC Results" — POC 1
(aligned OffsetMap) and POC 2 (packed LayoutBuilder/SequentialReader)
- `@alkdev/alknet: docs/research/alknet-typedef/findings.md` §"POC Results"
— POC 1 (aligned OffsetMap) and POC 2 (packed
LayoutBuilder/SequentialReader)
- [ADR-001](001-alktype-purpose-scope-jsonschema-engine.md) —
purpose and scope
- [ADR-003](003-schema-annotations.md) — schema annotations including
docs/architecture/decisions/003-schema-annotations.md
+2 -2
View File
@@ -251,8 +251,8 @@ event types). Both work.
## References
- `docs/research/alknet-typedef/findings.md` §"Open Questions" — the
annotation shape questions this ADR resolves
- `@alkdev/alknet: docs/research/alknet-typedef/findings.md` §"Open
Questions" — the annotation shape questions this ADR resolves
- [ADR-001](001-alktype-purpose-scope-jsonschema-engine.md) —
purpose and scope
- [ADR-002](002-two-layout-modes-packed-vs-aligned.md) — the two layout
docs/architecture/decisions/004-error-handling-validation-strategy.md
+2 -2
View File
@@ -148,8 +148,8 @@ you exactly which field failed and why.
## References
- `docs/research/alknet-typedef/findings.md` §"Open Questions" — error
handling strategy question (OQ 8)
- `@alkdev/alknet: docs/research/alknet-typedef/findings.md` §"Open
Questions" — error handling strategy question (OQ 8)
- [ADR-001](001-alktype-purpose-scope-jsonschema-engine.md) —
purpose and scope
- [ADR-002](002-two-layout-modes-packed-vs-aligned.md) — the two layout
docs/architecture/decisions/005-int64-uint64-first-class-kinds.md
+5 -4
View File
@@ -104,10 +104,11 @@ The engine now has **19** first-class kinds (17 + Int64 + Uint64).
## References
- `docs/research/call-channels-unification/findings.md` §"russh-sftp" —
the SFTP schema with `"offset": { "AlkType:Uint64": true }`
- `docs/research/alknet-typedef/findings.md` §"POC 1" — the POC included
u64 read/write
- `@alkdev/alknet: docs/research/call-channels-unification/findings.md`
§"russh-sftp" — the SFTP schema with
`"offset": { "AlkType:Uint64": true }`
- `@alkdev/alknet: docs/research/alknet-typedef/findings.md` §"POC 1" —
the POC included u64 read/write
- [ADR-001](001-alktype-purpose-scope-jsonschema-engine.md) —
purpose and scope (the kind set)
- [ADR-003](003-schema-annotations.md) — schema annotations
docs/architecture/layout-engine.md
+4 -3
View File
@@ -348,13 +348,14 @@ See [open-questions.md](open-questions.md) for full details.
## References
- `docs/research/alknet-typedef/findings.md` §"POC Results" — POC 1
(aligned OffsetMap) and POC 2 (packed LayoutBuilder/SequentialReader)
- `@alkdev/alknet: docs/research/alknet-typedef/findings.md` §"POC Results"
— POC 1 (aligned OffsetMap) and POC 2 (packed
LayoutBuilder/SequentialReader)
- [ADR-002](decisions/002-two-layout-modes-packed-vs-aligned.md) —
the two layout modes decision
- [ADR-003](decisions/003-schema-annotations.md) — schema
annotations
- [schema-layer.md](schema-layer.md) — the 17 AlkType kinds and their
- [schema-layer.md](schema-layer.md) — the 19 AlkType kinds and their
byte sizes
- [data-access.md](data-access.md) — read/write functions that use the
computed offsets
docs/architecture/overview.md
+18 -12
View File
@@ -36,7 +36,7 @@ each field. The custom keyword implementations are small (a few lines
each, generated from shared macros — see [validation.md](validation.md)).
The crate replaces two prior attempts that built their own jsonschema
engines — typebox-rs (~8,400 lines) and the @alkimiadev/alktype prototype
engines — typebox-rs (~8,400 lines) and the @alkdev/alktype prototype
(~5,600 lines) — with `jsonschema` + an offset map + small custom keyword
implementations. See
[ADR-001](decisions/001-alktype-purpose-scope-jsonschema-engine.md).
@@ -105,7 +105,7 @@ alktype
`alktype` is dependency-light: `jsonschema` + `serde_json` only.
No tokio, no platform deps. Compiles to `wasm32-unknown-unknown` for
browser use. The `jsonschema` crate is already in the workspace at
`/workspace/jsonschema/` — alktype is its first consumer.
`@alkdev/alknet: jsonschema/` — alktype is its first consumer.
`serde_json` requires the `preserve_order` feature because field order
is load-bearing for binary layouts. The order of properties in the
@@ -190,14 +190,20 @@ See [open-questions.md](open-questions.md) for full details.
## References
- `docs/research/alknet-typedef/findings.md` — POC results (26 tests
passing, two layout modes, TUnion dispatch, endianness)
- `docs/research/call-channels-unification/findings.md` §"alknet-typedef:
JSON Schema as the binary struct engine" — the origin of this research
thread
- `/workspace/@alkdev/typebox/example/typedef/typedef.ts` — the TypeBox
- `@alkdev/alknet: docs/research/alknet-typedef/findings.md` — POC results
(26 tests passing, two layout modes, TUnion dispatch, endianness)
- `@alkdev/alknet: docs/research/call-channels-unification/findings.md`
§"alknet-typedef: JSON Schema as the binary struct engine" — the
origin of this research thread
- `@alkdev/alknet: typebox/example/typedef/typedef.ts` — the TypeBox
schema kinds (619 lines)
- `/workspace/jsonschema/` — the jsonschema crate (v0.46.5, Draft 2020-12)
- `/workspace/alknet-typedef-poc/` — the POC code (disposable)
- `/workspace/@alkimiadev/typebox-rs/` — prior attempt, replaced by alktype
- `/workspace/@alkimiadev/alktype/` — prior attempt (the @alkimiadev/alktype prototype; not to be confused with this crate, which reuses the name but is backed by the `jsonschema` crate)
- `@alkdev/alknet: jsonschema/` — the jsonschema crate (v0.46.5, Draft
2020-12)
- `@alkdev/alknet: alknet-typedef-poc/` — the POC code (disposable)
- `@alkdev/alknet: typebox-rs/` — prior attempt, replaced by alktype
- `@alkdev/alknet: alktype-prototype/` — prior attempt (the @alkdev/alktype prototype; not to be confused with this crate, which reuses the name but is backed by the `jsonschema` crate)
> **Note**: The research findings, POC code, and prior-attempt paths above
> refer to the parent `@alkdev/alknet` workspace where this crate originated.
> They are preserved here as historical context for the architectural
> decisions; the artifacts themselves are not part of this standalone repo.
docs/architecture/questions/001-arrays-of-variable-length-element-structs.md
+2 -2
View File
@@ -2,8 +2,8 @@
- **Origin**: [../layout-engine.md](../layout-engine.md),
[../data-access.md](../data-access.md);
`docs/research/alknet-typedef/findings.md` §"Problem 3: Nested structs
and arrays of structs"
`@alkdev/alknet: 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)
docs/architecture/questions/002-no-std-alloc-support.md
+2 -1
View File
@@ -1,7 +1,8 @@
# OQ-002: `no_std` + `alloc` support
- **Origin**: [../overview.md](../overview.md);
`docs/research/alknet-typedef/findings.md` §"Open Questions" (OQ 6)
`@alkdev/alknet: docs/research/alknet-typedef/findings.md` §"Open
Questions" (OQ 6)
- **Status**: deferred(scope)
- **Door type**: Two-way (additive — can be added as a feature gate
without changing the existing `std` API)
docs/architecture/questions/003-builder-api-for-schema-construction.md
+2 -2
View File
@@ -2,8 +2,8 @@
- **Origin**: [../schema-layer.md](../schema-layer.md),
[../overview.md](../overview.md);
`docs/research/alknet-typedef/findings.md` (the builder API was noted
as the one detail not covered by the POCs)
`@alkdev/alknet: docs/research/alknet-typedef/findings.md` (the builder
API was noted as the one detail not covered by the POCs)
- **Status**: deferred(scope)
- **Door type**: Two-way (additive — a builder API can be added without
changing the existing JSON-consumption path)
docs/architecture/schema-layer.md
+5 -4
View File
@@ -13,7 +13,7 @@ annotations.
## The 19 AlkType Kinds
These are the custom schema kinds defined in TypeBox's `typedef.ts`
(`/workspace/@alkdev/typebox/example/typedef/typedef.ts`, 619 lines) and
(`@alkdev/alknet: typebox/example/typedef/typedef.ts`, 619 lines) and
ported to Rust via `jsonschema` custom keywords. Each kind carries binary
layout semantics — a known byte size (for fixed-size types) or a known
encoding strategy (for variable-length types).
@@ -296,7 +296,7 @@ let validator = jsonschema::options()
.with_keyword("AlkType:Float32", factory)
.with_keyword("AlkType:Int32", factory)
.with_keyword("AlkType:Struct", factory)
// ... all 17 kinds
// ... all 19 kinds
.build(&schema)?;
```
@@ -498,9 +498,10 @@ See [open-questions.md](open-questions.md) for full details.
## References
- `/workspace/@alkdev/typebox/example/typedef/typedef.ts` — the TypeBox
- `@alkdev/alknet: typebox/example/typedef/typedef.ts` — the TypeBox
schema kinds (619 lines)
- `/workspace/jsonschema/` — the jsonschema crate (v0.46.5, Draft 2020-12)
- `@alkdev/alknet: jsonschema/` — the jsonschema crate (v0.46.5, Draft
2020-12)
- [ADR-003](decisions/003-schema-annotations.md) — schema
annotation shapes
- [validation.md](validation.md) — custom keyword validator implementations
docs/architecture/validation.md
+3 -3
View File
@@ -325,11 +325,11 @@ not validation.
## References
- `docs/research/alknet-typedef/findings.md` §"Validation" — the POC's
custom keyword validators for all 17 kinds
- `@alkdev/alknet: docs/research/alknet-typedef/findings.md`
§"Validation" — the POC's custom keyword validators for all 17 kinds
- [ADR-004](decisions/004-error-handling-validation-strategy.md) —
error handling and validation strategy
- [schema-layer.md](schema-layer.md) — the 17 AlkType kinds that the
- [schema-layer.md](schema-layer.md) — the 19 AlkType kinds that the
validators check
- [data-access.md](data-access.md) — read/write functions that operate
on the same buffers
docs/sdd_process.md
+1 -1
View File
@@ -2,7 +2,7 @@
## Overview
This document defines the SDD process for the @alkdev/storage package. It
This document defines the SDD process for the @alkdev/alktype package. It
leverages:
- **OpenCode CLI** as the agent execution environment