diff --git a/docs/adr/ADR-029-rvf-canonical-format.md b/docs/adr/ADR-029-rvf-canonical-format.md index 93e31c52e..6da4032ee 100644 --- a/docs/adr/ADR-029-rvf-canonical-format.md +++ b/docs/adr/ADR-029-rvf-canonical-format.md @@ -220,6 +220,39 @@ The canonical trust chain for public artifacts is: 2. Kernel signing key → signs KERNEL_SEG → covers boot image (ADR-030) 3. TEE measurement → binds both to hardware attestation quote +### Segment Type Registry (Implemented) + +All segment types below are implemented in `rvf-types/src/segment_type.rs` with `TryFrom` round-trip support and unit tests (23 variants total): + +| Value | Name | Description | Source | +|-------|------|-------------|--------| +| 0x00 | Invalid | Uninitialized / zeroed region | Core | +| 0x01 | Vec | Raw vector payloads (embeddings) | Core | +| 0x02 | Index | HNSW adjacency lists, entry points, routing tables | Core | +| 0x03 | Overlay | Graph overlay deltas, partition updates, min-cut witnesses | Core | +| 0x04 | Journal | Metadata mutations (label changes, deletions, moves) | Core | +| 0x05 | Manifest | Segment directory, hotset pointers, epoch state | Core | +| 0x06 | Quant | Quantization dictionaries and codebooks | Core | +| 0x07 | Meta | Arbitrary key-value metadata (tags, provenance, lineage) | Core | +| 0x08 | Hot | Temperature-promoted hot data (vectors + neighbors) | Core | +| 0x09 | Sketch | Access counter sketches for temperature decisions | Core | +| 0x0A | Witness | Capability manifests, proof of computation, audit trails | Core | +| 0x0B | Profile | Domain profile declarations (RVDNA, RVText, etc.) | Core | +| 0x0C | Crypto | Key material, signature chains, certificate anchors | Core | +| 0x0D | MetaIdx | Metadata inverted indexes for filtered search | Core | +| 0x0E | Kernel | Embedded kernel / unikernel image for self-booting | ADR-030 | +| 0x0F | Ebpf | Embedded eBPF program for kernel fast path | ADR-030 | +| 0x10 | Wasm | Embedded WASM bytecode for self-bootstrapping | ADR-030/032 | +| 0x20 | CowMap | COW cluster mapping | ADR-031 | +| 0x21 | Refcount | Cluster reference counts | ADR-031 | +| 0x22 | Membership | Vector membership filter | ADR-031 | +| 0x23 | Delta | Sparse delta patches | ADR-031 | +| 0x30 | TransferPrior | Cross-domain posterior summaries + cost EMAs | Domain expansion | +| 0x31 | PolicyKernel | Policy kernel configuration and performance history | Domain expansion | +| 0x32 | CostCurve | Cost curve convergence data for acceleration tracking | Domain expansion | + +Available ranges: 0x11-0x1F, 0x24-0x2F, 0x33-0xEF. Values 0xF0-0xFF are reserved. + ## Consequences ### Benefits @@ -399,3 +432,4 @@ Model) inference and fine-tuning pipelines: | Version | Date | Author | Changes | |---------|------|--------|---------| | 1.0 | 2026-02-13 | ruv.io | Initial adoption decision | +| 1.1 | 2026-02-16 | implementation review | Added complete segment type registry documenting all 23 implemented variants including Wasm (0x10), COW segments (0x20-0x23), and domain expansion segments (0x30-0x32). All types have `TryFrom` round-trip tests in rvf-types. | diff --git a/docs/adr/ADR-030-rvf-cognitive-container.md b/docs/adr/ADR-030-rvf-cognitive-container.md index ad47a0045..4f47d1e0a 100644 --- a/docs/adr/ADR-030-rvf-cognitive-container.md +++ b/docs/adr/ADR-030-rvf-cognitive-container.md @@ -540,6 +540,8 @@ Old readers see zeros at these offsets and continue working normally. New reader ### SegmentType Registry Update +All computational segment types are now implemented in `rvf-types/src/segment_type.rs`: + ```rust #[repr(u8)] pub enum SegmentType { @@ -548,10 +550,14 @@ pub enum SegmentType { Kernel = 0x0E, /// Embedded eBPF program for kernel fast path. Ebpf = 0x0F, + /// Embedded WASM bytecode for self-bootstrapping execution. + Wasm = 0x10, + // ... COW segments 0x20-0x23 (ADR-031) ... + // ... Domain expansion segments 0x30-0x32 ... } ``` -Values 0x10-0xEF remain available for future segment types. Values 0xF0-0xFF remain reserved. +The full registry (23 types) is documented in ADR-029. Available ranges: 0x11-0x1F, 0x24-0x2F, 0x33-0xEF. Values 0xF0-0xFF remain reserved. ## Performance Targets @@ -575,24 +581,44 @@ Values 0x10-0xEF remain available for future segment types. Values 0xF0-0xFF rem ### Phase 1: Segment Types and Headers (rvf-types) **Duration**: 1 week -**Status**: Partially complete (as of 2026-02-14) +**Status**: **Complete** (as of 2026-02-16) **Implementation notes**: -- `SegmentType::Kernel = 0x0E` and `SegmentType::Ebpf = 0x0F` have been added to the `SegmentType` enum in `rvf-types/src/segment_type.rs` with `TryFrom` round-trip support and unit tests. -- The `rvf-runtime` write path (`write_path.rs`) implements `write_kernel_seg()` and `write_ebpf_seg()` methods that accept raw 128-byte and 64-byte header byte arrays respectively, with round-trip tests. -- **Remaining**: Typed `KernelHeader` and `EbpfHeader` structs with `repr(C)` and compile-time size assertions are not yet defined as Rust structs in `rvf-types`. The `KernelArch`, `KernelType`, `ApiTransport`, `EbpfProgramType`, `EbpfAttachType` enums and `KernelFlags` bitfield are not yet implemented. `KernelPtr` has not been added to the Level0Root reserved area. +- `SegmentType::Kernel = 0x0E`, `SegmentType::Ebpf = 0x0F`, and `SegmentType::Wasm = 0x10` are all defined in `rvf-types/src/segment_type.rs` with `TryFrom` round-trip support and unit tests. +- The `rvf-runtime` write path (`write_path.rs`) implements `write_kernel_seg()` and `write_ebpf_seg()` methods that accept raw header byte arrays, with round-trip tests. +- **`KernelHeader`** (128-byte `repr(C)` struct) is fully implemented in `rvf-types/src/kernel.rs` with: + - `KernelArch` enum (X86_64, Aarch64, Riscv64, Universal, Unknown) with `TryFrom` + - `KernelType` enum (Hermit, MicroLinux, Asterinas, WasiPreview2, Custom, TestStub) with `TryFrom` + - `ApiTransport` enum (TcpHttp, TcpGrpc, Vsock, SharedMem, None) with `TryFrom` + - 15 `KERNEL_FLAG_*` bitfield constants (bits 0-14) + - `to_bytes()` / `from_bytes()` serialization with compile-time size assertion + - 12 tests: header size, magic, round-trip, bad magic, field offsets, enum round-trips, flag bit positions, api_port network byte order, reserved field zeroing +- **`EbpfHeader`** (64-byte `repr(C)` struct) is fully implemented in `rvf-types/src/ebpf.rs` with: + - `EbpfProgramType` enum (XdpDistance, TcFilter, SocketFilter, Tracepoint, Kprobe, CgroupSkb, Custom) with `TryFrom` + - `EbpfAttachType` enum (XdpIngress, TcIngress, TcEgress, SocketFilter, CgroupIngress, CgroupEgress, None) with `TryFrom` + - `to_bytes()` / `from_bytes()` serialization with compile-time size assertion + - 10 tests: header size, magic, round-trip, bad magic, field offsets, enum round-trips, max_dimension, large program size +- **`WasmHeader`** (64-byte `repr(C)` struct) is fully implemented in `rvf-types/src/wasm_bootstrap.rs` with: + - `WasmRole` enum (Microkernel, Interpreter, Combined, Extension, ControlPlane) with `TryFrom` + - `WasmTarget` enum (Wasm32, WasiP1, WasiP2, Browser, BareTile) with `TryFrom` + - 8 `WASM_FEAT_*` bitfield constants + - `to_bytes()` / `from_bytes()` serialization with compile-time size assertion + - 10 tests +- All types are exported from `rvf-types/src/lib.rs`. **Deliverables**: -- ~~Add `Kernel = 0x0E` and `Ebpf = 0x0F` to `SegmentType` enum~~ (done) -- Define `KernelHeader` (128-byte repr(C) struct) with compile-time size assertion -- Define `EbpfHeader` (64-byte repr(C) struct) with compile-time size assertion -- Define architecture, kernel type, transport, and program type enums -- Define kernel flags and eBPF flags bitfields -- Add `KernelPtr` to Level0Root reserved area -- Unit tests for all new types, field offsets, and round-trips +- [x] Add `Kernel = 0x0E` and `Ebpf = 0x0F` to `SegmentType` enum +- [x] Add `Wasm = 0x10` to `SegmentType` enum +- [x] Define `KernelHeader` (128-byte repr(C) struct) with compile-time size assertion +- [x] Define `EbpfHeader` (64-byte repr(C) struct) with compile-time size assertion +- [x] Define `WasmHeader` (64-byte repr(C) struct) with compile-time size assertion +- [x] Define architecture, kernel type, transport, and program type enums +- [x] Define kernel flags (15 bits) and WASM feature flags (8 bits) +- [ ] Add `KernelPtr` to Level0Root reserved area +- [x] Unit tests for all new types, field offsets, and round-trips (32+ tests) -**Preconditions**: rvf-types crate exists and compiles (satisfied by current state) -**Success criteria**: `cargo test -p rvf-types` passes, all new structs have offset tests +**Preconditions**: rvf-types crate exists and compiles (satisfied) +**Success criteria**: `cargo test -p rvf-types` passes, all new structs have offset tests -- **MET** ### Phase 2: eBPF Program Embedding + Extraction (rvf-ebpf) @@ -660,7 +686,7 @@ Values 0x10-0xEF remain available for future segment types. Values 0xF0-0xFF rem ## GOAP Plan -### World State (Current) +### World State (Current — updated 2026-02-16) ```yaml rvf_types_exists: true @@ -669,11 +695,15 @@ rvf_manifest_exists: true rvf_runtime_exists: true rvf_wasm_exists: true rvf_crypto_exists: true -segment_types_count: 14 # 0x00-0x0D -kernel_seg_defined: false -ebpf_seg_defined: false -kernel_header_defined: false -ebpf_header_defined: false +segment_types_count: 23 # 0x00-0x0D, 0x0E-0x10, 0x20-0x23, 0x30-0x32 +kernel_seg_defined: true # SegmentType::Kernel = 0x0E +ebpf_seg_defined: true # SegmentType::Ebpf = 0x0F +wasm_seg_defined: true # SegmentType::Wasm = 0x10 +kernel_header_defined: true # KernelHeader (128B repr(C)) in kernel.rs +ebpf_header_defined: true # EbpfHeader (64B repr(C)) in ebpf.rs +wasm_header_defined: true # WasmHeader (64B repr(C)) in wasm_bootstrap.rs +agi_container_defined: true # AgiContainerHeader (64B repr(C)) in agi_container.rs +domain_expansion_types: true # TransferPrior, PolicyKernel, CostCurve segments kernel_seg_codec: false ebpf_seg_codec: false hermit_kernel_built: false @@ -843,3 +873,4 @@ Parallel path (eBPF, runs alongside kernel path): | Version | Date | Author | Changes | |---------|------|--------|---------| | 1.0 | 2026-02-14 | ruv.io | Initial proposal | +| 1.1 | 2026-02-16 | implementation review | Phase 1 complete: KernelHeader (128B), EbpfHeader (64B), WasmHeader (64B), all enums and flag constants implemented in rvf-types with 32+ tests. Updated GOAP world state. Added WASM_SEG (0x10) and domain expansion types (0x30-0x32) to segment registry. AGI container header (64B) implemented. | diff --git a/docs/adr/ADR-032-rvf-wasm-integration.md b/docs/adr/ADR-032-rvf-wasm-integration.md index 71c2d1069..bdb4ad6f0 100644 --- a/docs/adr/ADR-032-rvf-wasm-integration.md +++ b/docs/adr/ADR-032-rvf-wasm-integration.md @@ -395,6 +395,23 @@ Applied security hardening across all three integration surfaces after audit. --- +## RVF Types Implementation (WASM Bootstrap) + +The WASM self-bootstrapping types are fully implemented in `rvf-types/src/wasm_bootstrap.rs` (402 lines, 10 tests): + +| Type | Size | Description | +|------|------|-------------| +| `WasmHeader` | 64 bytes (`repr(C)`) | Segment payload header with magic "RVWM" (0x5256574D), `to_bytes()`/`from_bytes()` serialization, compile-time size assertion | +| `WasmRole` | `u8` enum | Microkernel (0x00), Interpreter (0x01), Combined (0x02), Extension (0x03), ControlPlane (0x04) | +| `WasmTarget` | `u8` enum | Wasm32 (0x00), WasiP1 (0x01), WasiP2 (0x02), Browser (0x03), BareTile (0x04) | +| `WASM_FEAT_*` | 8 constants | SIMD, bulk memory, multi-value, reference types, threads, tail call, GC, exception handling | + +Key fields in `WasmHeader`: `bytecode_size`, `compressed_size`, `bytecode_hash` (SHAKE-256-256), `bootstrap_priority`, `interpreter_type`, `min_memory_pages`, `max_memory_pages`. + +All types are exported from `rvf-types/src/lib.rs` and available to downstream crates. The `SegmentType::Wasm = 0x10` discriminant is registered in `segment_type.rs` with `TryFrom` round-trip tests. + +--- + ## Verification ```bash diff --git a/docs/adr/ADR-036-agi-cognitive-container.md b/docs/adr/ADR-036-agi-cognitive-container.md index fe7b2c8da..78e59bf6a 100644 --- a/docs/adr/ADR-036-agi-cognitive-container.md +++ b/docs/adr/ADR-036-agi-cognitive-container.md @@ -1,6 +1,6 @@ # ADR-036: RuVector AGI Cognitive Container with Claude Code Orchestration -**Status**: Proposed +**Status**: Partially Implemented **Date**: 2026-02-15 **Decision owners**: RuVector platform team, Claude Flow orchestration team, RVF runtime team **Depends on**: ADR-029 (RVF Canonical Format), ADR-030 (Cognitive Container), ADR-033 (Progressive Indexing Hardening), ADR-034 (QR Cognitive Seed), ADR-035 (Capability Report) @@ -623,9 +623,33 @@ Unknown tags are ignored (forward-compatible). ### Implementation -Types are defined in `rvf-types/src/agi_container.rs`. The `AgiContainerHeader` -struct, `ExecutionMode`, `AuthorityLevel`, and `ContainerSegments` types provide -compile-time-checked serialization with round-trip tests. +Types are fully implemented in `rvf-types/src/agi_container.rs` (972 lines, 24 tests). + +**Implemented types:** + +| Type | Size / Kind | Description | Tests | +|------|-------------|-------------|-------| +| `AgiContainerHeader` | 64 bytes (`repr(C)`) | Wire-format header with magic "RVAG" (0x52564147), `to_bytes()`/`from_bytes()` serialization, compile-time size assertion | 4 | +| `ExecutionMode` | `u8` enum | Replay (0), Verify (1), Live (2) with `TryFrom` | 1 | +| `AuthorityLevel` | `u8` enum | ReadOnly (0), WriteMemory (1), ExecuteTools (2), WriteExternal (3) with `TryFrom`, `PartialOrd`/`Ord`, `permits()`, `default_for_mode()` | 4 | +| `ResourceBudget` | struct | Per-task resource caps with `DEFAULT`, `EXTENDED`, `MAX` presets and `clamped()` method | 3 | +| `CoherenceThresholds` | struct | Three configurable thresholds (`min_coherence_score`, `max_contradiction_rate`, `max_rollback_ratio`) with `DEFAULT`, `STRICT` presets and `validate()` method | 5 | +| `ContainerSegments` | struct | Segment presence tracker with `validate(mode)` and `to_flags()` | 7 | +| `ContainerError` | enum | 6 variants: MissingSegment, TooLarge, InvalidConfig, SignatureInvalid, InsufficientAuthority, BudgetExhausted with `Display` | 1 | + +**Constants defined:** +- 13 flag constants (`AGI_HAS_KERNEL` through `AGI_HAS_DOMAIN_EXPANSION`, bits 0-12) +- 22 TLV manifest tag constants (`AGI_TAG_CONTAINER_ID` 0x0100 through `AGI_TAG_COUNTEREXAMPLES` 0x0115) +- Includes 4 domain expansion tags: `AGI_TAG_TRANSFER_PRIOR` (0x0112), `AGI_TAG_POLICY_KERNEL` (0x0113), `AGI_TAG_COST_CURVE` (0x0114), `AGI_TAG_COUNTEREXAMPLES` (0x0115) + +**Key design properties:** +- `AuthorityLevel::permits()` enables level comparison: `WriteExternal` permits all lower levels +- `AuthorityLevel::default_for_mode()` maps Replay->ReadOnly, Verify->ExecuteTools, Live->WriteMemory +- `ResourceBudget::clamped()` enforces hard ceilings (`MAX` preset) that cannot be overridden +- `CoherenceThresholds::validate()` rejects out-of-range values +- `ContainerSegments::validate(mode)` enforces mode-specific segment requirements +- `ContainerSegments::to_flags()` computes the bitfield from present segments +- All types are `no_std` compatible and exported from `rvf-types/src/lib.rs` ## Acceptance Test @@ -659,3 +683,4 @@ Run the same RVF artifact on two separate machines owned by two separate teams. |---------|------|--------|---------| | 1.0 | 2026-02-15 | ruv.io | Initial proposal | | 1.1 | 2026-02-15 | architecture review | Resolved open questions (domain, authority, resource budgets, coherence thresholds). Added wire format section. Added cross-references to ADR-029/030/031/033. Added AuthorityLevel enum and resource budget types. Tightened ContainerSegments validation. | +| 1.2 | 2026-02-16 | implementation review | Status updated to Partially Implemented. Documented full wire-format implementation in rvf-types/src/agi_container.rs (972 lines, 24 tests). All header types, enums, constants, and validators are implemented and exported. Domain expansion TLV tags (0x0112-0x0115) integrated. |