vrr/ruvector
2
0
Fork 0
mirror of https://github.com/ruvnet/RuVector.git synced 2026-07-09 17:28:42 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs(adr): update ADRs with implementation details from rvf-types

Browse source 
- ADR-029: Add complete segment type registry (23 variants) with source references
- ADR-030: Phase 1 complete — KernelHeader (128B), EbpfHeader (64B), WasmHeader (64B),
  all enums and flag constants implemented with 32+ tests. Updated GOAP world state.
- ADR-032: Add WASM bootstrap types implementation section (WasmHeader, WasmRole,
  WasmTarget, 8 feature flags, 10 tests)
- ADR-036: Status updated to Partially Implemented. Documented AGI container
  implementation (972 lines, 24 tests) including AgiContainerHeader, ExecutionMode,
  AuthorityLevel, ResourceBudget, CoherenceThresholds, ContainerSegments, and
  22 TLV tags with domain expansion integration (0x0112-0x0115)

https://claude.ai/code/session_01RnwD4x5cbpB7FPvoyYQz8G
This commit is contained in:
Claude 2026-02-16 02:58:43 +00:00
parent 227c46db4f
commit 9cff4e46f2
4 changed files with 131 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

34
docs/adr/ADR-029-rvf-canonical-format.md
View file

@ -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<u8>` 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<u8>` round-trip tests in rvf-types. |

71
docs/adr/ADR-030-rvf-cognitive-container.md
View file

@ -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<u8>` 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<u8>` 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<u8>`
- `KernelType` enum (Hermit, MicroLinux, Asterinas, WasiPreview2, Custom, TestStub) with `TryFrom<u8>`
- `ApiTransport` enum (TcpHttp, TcpGrpc, Vsock, SharedMem, None) with `TryFrom<u8>`
- 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<u8>`
- `EbpfAttachType` enum (XdpIngress, TcIngress, TcEgress, SocketFilter, CgroupIngress, CgroupEgress, None) with `TryFrom<u8>`
- `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<u8>`
- `WasmTarget` enum (Wasm32, WasiP1, WasiP2, Browser, BareTile) with `TryFrom<u8>`
- 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. |

17
docs/adr/ADR-032-rvf-wasm-integration.md
View file

@ -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<u8>` round-trip tests.
---
## Verification
```bash

33
docs/adr/ADR-036-agi-cognitive-container.md
View file

@ -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<u8>` | 1 |
| `AuthorityLevel` | `u8` enum | ReadOnly (0), WriteMemory (1), ExecuteTools (2), WriteExternal (3) with `TryFrom<u8>`, `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. |