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
This commit is contained in:
1 parent
5e268e8f47
commit
6d6142978a
24 files changed
+128
-108
No files matched your search
@@ -326,15 +326,15 @@ result, a concrete use case to arrive.
|
||||
|
||||
A decision should be `deferred(scope)` when:
|
||||
|
||||
- The use case isn't concrete (e.g., "we don't know what the agent crate
|
||||
will need from the call protocol")
|
||||
- The use case isn't concrete (e.g., "we don't know if any consumer needs
|
||||
arrays of variable-length-element structs")
|
||||
- The options depend on something that doesn't exist yet (e.g.,
|
||||
"depends on the alknet-http crate spec")
|
||||
"depends on a concrete consumer schema that needs this feature")
|
||||
- The trade-off requires data that can only come from implementation
|
||||
(e.g., "need performance benchmarks to choose between X and Y")
|
||||
- The decision is genuinely not needed for the current scope (e.g., "the
|
||||
current scope is core + call crates; this question is about the agent
|
||||
crate")
|
||||
current scope is the core engine; this question is about a builder API
|
||||
that no current consumer needs")
|
||||
|
||||
### `deferred(unclear)` — the pieces exist but the shape isn't clear
|
||||
|
||||
@@ -373,10 +373,10 @@ A decision should be `deferred(unclear)` when:
|
||||
(implies it's decided).
|
||||
2. **State the blocking condition** (`deferred(scope)`) or
|
||||
**investigation target** (`deferred(unclear)`) — what specific thing
|
||||
would unblock this? Be concrete: "blocked on: alknet-agent crate spec
|
||||
exists" or "investigation: work through 2+ example outbound-dial use
|
||||
cases (hub→worker, worker→hub) to see how verifier-selection +
|
||||
provider + connector compose."
|
||||
would unblock this? Be concrete: "blocked on: a concrete consumer that
|
||||
needs arrays of variable-length-element structs" or "investigation:
|
||||
work through 2+ example schemas with nested variable-length arrays to
|
||||
see how the lazy walking logic would compose."
|
||||
3. **State the impacts** — what does this block downstream? Be
|
||||
specific: "blocks the first hub deployment because the hub dials
|
||||
workers" not "blocks the hub crate." This is the triage signal that
|
||||
|
||||
@@ -111,13 +111,13 @@ cargo fmt --check # Format check
|
||||
For this project, also verify:
|
||||
|
||||
- No comments in code (per project convention)
|
||||
- Error handling uses `anyhow::Result` (application) / `thiserror` (library) — no
|
||||
panics in library code
|
||||
- Feature flags are used correctly (`tls`, `iroh`, `acme`) — base crate compiles
|
||||
lean
|
||||
- Error handling uses `AlkTypeError` (hand-rolled enum in `src/error.rs`) — no
|
||||
panics in library code, no `anyhow`/`thiserror`
|
||||
- No feature flags (the crate has none) — only `serde_json` + `jsonschema` deps
|
||||
- Public API is well-documented with `///` doc comments where appropriate
|
||||
- Module structure follows Rust conventions (`mod.rs`, `lib.rs`)
|
||||
- Module structure follows Rust conventions (`lib.rs`)
|
||||
- No unnecessary `unwrap()` or `expect()` in library code
|
||||
- WASM-clean: no platform deps, no tokio, no async
|
||||
|
||||
#### E. Security
|
||||
|
||||
|
||||
@@ -20,7 +20,7 @@ You manage the execution of decomposed task graphs:
|
||||
- Handle blocks and anomalies when they arise
|
||||
- Run an after-action review when the task graph is complete
|
||||
|
||||
## The `worktree` Tool (via @alkimiadev/open-coordinator)
|
||||
## The `worktree` Tool (via @alkdev/open-coordinator)
|
||||
|
||||
You use the **worktree** tool with `{action, args}` dispatch. Role is
|
||||
auto-detected — coordinator sessions get the full operation set, spawned
|
||||
@@ -191,7 +191,7 @@ also include:
|
||||
Example prompt template:
|
||||
|
||||
```
|
||||
You are an implementation specialist for the @alkdev/alknet project.
|
||||
You are an implementation specialist for the @alkdev/alktype project.
|
||||
|
||||
Your task: {{task}}
|
||||
|
||||
@@ -204,13 +204,14 @@ Your task: {{task}}
|
||||
7. Push: git push origin $(git branch --show-current)
|
||||
8. Notify: worktree({action: "notify", args: {message: "Task completed: {{task}}. <brief summary>", level: "info"}})
|
||||
|
||||
Key project constraints (@alkdev/alknet):
|
||||
Key project constraints (@alkdev/alktype):
|
||||
- Rust: use cargo build, cargo clippy, cargo fmt, cargo test
|
||||
- No comments in code
|
||||
- anyhow::Result for application errors, thiserror for library error types
|
||||
- Feature flags for transports (tls, iroh, acme)
|
||||
- Async via tokio runtime
|
||||
- AlkTypeError (hand-rolled enum in src/error.rs) is the library error type
|
||||
- No async runtime (no tokio) — the engine is fully synchronous
|
||||
- No feature flags currently
|
||||
- No panics in library code
|
||||
- WASM-clean: only serde_json + jsonschema deps, no platform deps
|
||||
```
|
||||
|
||||
### Partial Generation Spawning
|
||||
|
||||
@@ -207,30 +207,25 @@ This is especially important for complex tasks that span many file operations.
|
||||
|
||||
## Project Conventions
|
||||
|
||||
Read `AGENTS.md` at project root for full details. Key rules:
|
||||
Key project conventions (no AGENTS.md — these are the canonical rules):
|
||||
|
||||
1. **No comments in code** — Per project convention.
|
||||
2. **Error handling** — Use `anyhow::Result` for application code, `thiserror` for
|
||||
library error types. Never panic in library code.
|
||||
2. **Error handling** — `AlkTypeError` (hand-rolled enum in `src/error.rs`) is
|
||||
the library error type. No `anyhow` or `thiserror` — this is a library crate
|
||||
with a single error enum. Never panic in library code.
|
||||
3. **No `unwrap()` or `expect()` outside tests** — These are debug signals that
|
||||
something wasn't clear. If you reach for `unwrap()`, it means the error
|
||||
handling path wasn't specified — stop and think about what should actually
|
||||
happen on that error. For poisoned locks, use
|
||||
`unwrap_or_else(|e| e.into_inner())` or explicit error propagation. A panic
|
||||
in one operation must not cascade to other operations.
|
||||
4. **Cryptographic nonces use `OsRng`** — AES-GCM IVs and any other cryptographic
|
||||
nonces must use `OsRng` (or equivalent CSPRNG), never `rand::random()`. IV
|
||||
reuse under the same key is catastrophic for GCM.
|
||||
5. **Secret material is zeroized on drop** — Any type holding derived keys,
|
||||
decrypted credentials, or other secret material must derive `Zeroize` and
|
||||
`ZeroizeOnDrop`. Secrets must not linger in freed heap memory.
|
||||
6. **Feature flags** — Transports are feature-gated (`tls`, `iroh`, `acme`). Base
|
||||
crate should compile lean.
|
||||
7. **Async runtime** — `tokio` is the async runtime. All I/O is async.
|
||||
8. **Naming conventions** — Rust standard: `snake_case` for functions/variables/
|
||||
`unwrap_or_else(|e| e.into_inner())` or explicit error propagation.
|
||||
4. **No async runtime** — The engine is fully synchronous. No tokio, no async.
|
||||
5. **No feature flags** — The crate has no feature flags currently.
|
||||
6. **WASM-clean** — Only `serde_json` + `jsonschema` dependencies. No platform
|
||||
deps. Must compile to `wasm32-unknown-unknown`.
|
||||
7. **Naming conventions** — Rust standard: `snake_case` for functions/variables/
|
||||
modules, `PascalCase` for types/traits, `SCREAMING_SNAKE_CASE` for constants.
|
||||
9. **Module structure** — One module per component under `src/`. Re-export via
|
||||
`mod.rs` or `lib.rs` as appropriate.
|
||||
8. **Module structure** — One module per component under `src/`. Re-export via
|
||||
`lib.rs`.
|
||||
|
||||
## Key Principles
|
||||
|
||||
|
||||
+17
-11
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
@@ -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.
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
+1
-1
@@ -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
|
||||
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
//! Data access layer: primitive read/write functions for all 17 AlkType
|
||||
//! Data access layer: primitive read/write functions for all 19 AlkType
|
||||
//! kinds with endianness support, bounds checking, and zero-copy access.
|
||||
//!
|
||||
//! These are the building blocks used by the layout types ([`crate::offset_map`],
|
||||
|
||||
+1
-1
@@ -17,7 +17,7 @@
|
||||
//! - **TUnion dispatch** ([`tunion`]): Byte-offset and field-name
|
||||
//! discriminator dispatch.
|
||||
//! - **Validation** ([`validation`]): Custom keyword validators for all
|
||||
//! 17 `AlkType:*` kinds, delegated to the `jsonschema` crate.
|
||||
//! 19 `AlkType:*` kinds, delegated to the `jsonschema` crate.
|
||||
//! - **Engine** ([`engine`]): `AlkTypeEngine` — the compiled form of a
|
||||
//! schema, combining layout and validation.
|
||||
|
||||
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
//! Macros for generating repetitive code across the 17 AlkType kinds.
|
||||
//! Macros for generating repetitive code across the 19 AlkType kinds.
|
||||
//!
|
||||
//! These macros eliminate boilerplate in validation, data access, and
|
||||
//! dispatch. Each macro takes a compact specification and generates the
|
||||
|
||||
+2
-2
@@ -1,4 +1,4 @@
|
||||
//! Custom keyword validators for all 17 `AlkType:*` kinds, registered
|
||||
//! Custom keyword validators for all 19 `AlkType:*` kinds, registered
|
||||
//! via `jsonschema::options().with_keyword(...)`.
|
||||
//!
|
||||
//! Per ADR-098: the `jsonschema` crate handles all structural validation;
|
||||
@@ -14,7 +14,7 @@ use crate::error::AlkTypeError;
|
||||
use jsonschema::{Keyword, ValidationError};
|
||||
use serde_json::{Map, Value};
|
||||
|
||||
/// Build a jsonschema validator with all 17 `AlkType:*` custom keywords
|
||||
/// Build a jsonschema validator with all 19 `AlkType:*` custom keywords
|
||||
/// registered.
|
||||
///
|
||||
/// The returned validator can validate JSON representations of data
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
//! POC round-trip tests adapted from `/workspace/alknet-typedef-poc/`.
|
||||
//! POC round-trip tests adapted from the `@alkdev/alknet: alknet-typedef-poc/`
|
||||
//! workspace.
|
||||
//!
|
||||
//! These tests re-validate the byte-identical round-trip behaviour that
|
||||
//! the POC verified: fixed-size primitives, length-prefixed strings and
|
||||
|
||||
Reference in new issue
Block a user