dearsky/wifi-densepose
1
0
Fork 0
Code Issues 20 Pull Requests 5 Actions Packages Projects Releases 1 Wiki Activity
Files
fc409dfd6a72ca28ac12127c0927170eac45e65b
wifi-densepose/vendor/ruvector/docs/adr/ADR-034-qr-cognitive-seed.md

20 KiB
Raw Blame History

ADR-034: QR Cognitive Seed — A World Inside a World

Status: Implemented Date: 2026-02-15 Depends on: ADR-029 (RVF Canonical Format), ADR-030 (Cognitive Container), ADR-033 (Progressive Indexing Hardening) Affects: rvf-types, rvf-runtime Zero external dependencies: All crypto, compression, and FFI implemented from scratch.

Context

RVF files are self-bootstrapping cognitive containers: they carry their own WASM interpreter, signed manifests, and progressive index layers. But distribution still assumes a filesystem — a URL, a disk, a cloud bucket.

What if intelligence could live in printed ink?

A QR code can carry up to 2,953 bytes (Version 40, Low EC). That's enough for:

  • A 64-byte RVQS header
  • A 5.5 KB WASM microkernel (LZ-compressed to ~2.1 KB)
  • A 32-byte HMAC-SHA256 signature
  • A 500-byte progressive download manifest with host URLs + content hashes

Total seed: ~2,700 bytes. Fits in a single QR code with 229 bytes headroom.

The result: scan a QR code and mount a portable brain. The AI literally exists in the data printed on a piece of paper. Offline-first, signed, verifiable, capable of bootstrapping into a streamed universe.

Decision

1. QR Seed Format (RVQS — RuVector QR Seed)

A QR Cognitive Seed is a binary payload with this wire format:

Offset  Size  Field                    Description
------  ----  -----                    -----------
0x000   4     seed_magic               0x52565153 ("RVQS")
0x004   2     seed_version             Seed format version (1)
0x006   2     flags                    Seed flags (see below)
0x008   8     file_id                  Unique identifier for this seed
0x010   4     total_vector_count       Expected vectors when fully loaded
0x014   2     dimension                Vector dimensionality
0x016   1     base_dtype               Base data type (DataType enum)
0x017   1     profile_id               Domain profile
0x018   8     created_ns               Seed creation timestamp (nanos)
0x020   4     microkernel_offset       Offset to WASM microkernel data
0x024   4     microkernel_size         Compressed microkernel size
0x028   4     download_manifest_offset Offset to download manifest
0x02C   4     download_manifest_size   Download manifest size
0x030   2     sig_algo                 Signature algorithm (0=Ed25519, 1=ML-DSA-65, 2=HMAC-SHA256)
0x032   2     sig_length               Signature byte length
0x034   4     total_seed_size          Total payload size in bytes
0x038   8     content_hash             SHA-256-64 of microkernel+manifest data
0x040   var   microkernel_data         LZ-compressed WASM microkernel
...     var   download_manifest        Progressive download manifest (TLV)
...     var   signature                Seed signature (covers 0x000..sig start)

1.1 Seed Flags

Bit  Name                  Description
---  ----                  -----------
0    SEED_HAS_MICROKERNEL  Embedded WASM microkernel present
1    SEED_HAS_DOWNLOAD     Progressive download manifest present
2    SEED_SIGNED           Payload is signed
3    SEED_OFFLINE_CAPABLE  Seed is useful without network access
4    SEED_ENCRYPTED        Payload is encrypted (key in TEE or passphrase)
5    SEED_COMPRESSED       Microkernel is LZ-compressed
6    SEED_HAS_VECTORS      Seed contains inline vector data (tiny model)
7    SEED_STREAM_UPGRADE   Seed can upgrade itself via streaming

1.2 Signature Algorithms

ID Algorithm Size Dependencies Use Case
0 Ed25519 64 B ed25519-dalek Asymmetric, production
1 ML-DSA-65 3,309 B pqcrypto Post-quantum (requires 2-QR)
2 HMAC-SHA256 32 B None (built-in) Symmetric, zero-dep default

sig_algo=2 (HMAC-SHA256) is implemented from scratch with zero external dependencies.

2. Progressive Download Manifest

The download manifest tells the runtime how to grow from seed to full intelligence. It uses a TLV structure:

Tag     Length  Description
------  ------  -----------
0x0001  var     HostEntry: Primary download host
0x0002  var     HostEntry: Fallback host (up to 3)
0x0003  32      content_hash: SHA-256 of the full RVF file
0x0004  8       total_file_size: Expected size of the full RVF
0x0005  var     LayerManifest: Progressive layer download order
0x0006  16      session_token: Ephemeral auth token for download
0x0007  4       ttl_seconds: Token expiry
0x0008  var     CertPin: TLS certificate pin (SHA-256 of SPKI)

Default layer order:

Priority Layer Size Purpose
0 Level 0 manifest 4 KB Instant boot
1 Hot cache (centroids + entry points) ~50 KB First query capability
2 HNSW Layer A ~200 KB recall >= 0.70
3 Quantization dictionaries ~100 KB Compact search
4 HNSW Layer B ~500 KB recall >= 0.85
5 Full vectors (warm tier) variable Full recall
6 HNSW Layer C variable recall >= 0.95

3. Bootstrap Sequence

┌─────────────────────────────────────────────────────────────────┐
│                     QR Code (≤2,953 bytes)                      │
│  ┌──────────┬──────────────┬────────────┬──────────────────┐    │
│  │ RVQS Hdr │ WASM μkernel │ DL Manifest│  HMAC-SHA256 Sig │    │
│  │ 64 bytes │ ~2.1 KB (LZ) │ ~500 bytes │    32 bytes      │    │
│  └──────────┴──────────────┴────────────┴──────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ Phase 0: Scan & Verify (offline, <1ms)                          │
│  1. Parse RVQS header, validate magic 0x52565153                │
│  2. Verify content hash: SHA-256(μkernel ‖ manifest)[0..8]      │
│  3. Verify HMAC-SHA256 signature (constant-time comparison)     │
│  4. Decompress WASM microkernel (built-in LZ decompressor)     │
│  5. Instantiate WASM runtime                                    │
│  6. Seed is now ALIVE — cognitive kernel running                 │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼ (if network available)
┌─────────────────────────────────────────────────────────────────┐
│ Phase 1: Progressive Download (background, priority-ordered)    │
│  1. Fetch Level 0 manifest (4 KB) → instant full boot           │
│  2. Fetch hot cache → first query capability (50% recall)       │
│  3. Fetch HNSW Layer A → recall ≥ 0.70                          │
│  4. Fetch remaining layers in priority order                    │
│  Each layer: verify SHA-256-128 content_hash → append → index   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ Phase 2: Full Intelligence                                      │
│  1. All layers downloaded and verified                          │
│  2. Full HNSW index active, recall ≥ 0.95                       │
│  3. Seed has grown into a complete cognitive container           │
│  4. Can operate fully offline from this point                   │
│  5. Can re-export as a new QR seed (with updated vectors)       │
└─────────────────────────────────────────────────────────────────┘

4. Security Model

4.1 Built-in Cryptography (Zero Dependencies)

All cryptographic primitives are implemented from scratch in pure Rust:

Primitive Implementation Location Tests
SHA-256 FIPS 180-4 rvf-types/src/sha256.rs 11 (incl. NIST + RFC 4231 vectors)
HMAC-SHA256 RFC 2104 rvf-types/src/sha256.rs 3 RFC 4231 test cases
Constant-time compare XOR accumulator rvf-types/src/sha256.rs 2
LZ compression SCF-1 (4KB window) rvf-runtime/src/compress.rs 11
Content hashing SHA-256 truncated rvf-runtime/src/seed_crypto.rs 10

Signature verification flow:

let parsed = ParsedSeed::parse(&payload)?;

// Full verification: magic + content hash + HMAC signature.
parsed.verify_all(signing_key, &payload)?;

// Or step by step:
assert!(parsed.verify_content_hash());
parsed.verify_signature(signing_key, &payload)?;
let wasm = parsed.decompress_microkernel()?;

4.2 Content Integrity

  • Seed content hash: SHA-256(microkernel ‖ manifest) truncated to 64 bits. Stored in header at offset 0x38.
  • Layer content hashes: SHA-256 of each layer truncated to 128 bits. Verified on download.
  • Full file hash: SHA-256 of the complete RVF file. Stored in manifest TLV tag 0x0003.

4.3 Download Security

  1. Content hashes: Each layer has a SHA-256-128 hash. Downloaded data is verified before use.
  2. TLS certificate pinning: SHA-256 of host's SPKI. Prevents MITM even if a CA is compromised.
  3. Session tokens: Ephemeral 16-byte auth tokens with TTL.
  4. Host key verification: Each HostEntry contains the host's public key hash.

5. Mobile Integration

5.1 iOS App Clip — Scan. Boot. Intelligence.

The strongest UX story: QR opens an App Clip instantly, no install.

User scans QR with iOS Camera
         │
         ▼
iOS launches App Clip instantly (no App Store, no login)
         │
         ▼
┌─────────────────────────────────────────┐
│ App Clip (~50 KB RVF static library)    │
│                                         │
│  1. rvqs_parse_header() — read RVQS     │
│  2. rvqs_verify_signature() — HMAC      │
│  3. rvqs_verify_content_hash() — SHA256 │
│  4. rvqs_decompress_microkernel() — LZ  │
│  5. Mount WASM runtime                  │
│  6. rvqs_get_primary_host_url()         │
│  7. Stream layers → progressive recall  │
└─────────────────────────────────────────┘
         │
         ▼
User sees intelligence in <2 seconds
Optional: "Get Full App" upgrade path

The App Clip contains the compiled rvf-runtime as a static library linked via C FFI:

// Swift calling the Rust FFI
var header = RvqsHeaderC()
let rc = rvqs_parse_header(qrData.baseAddress, qrData.count, &header)
guard rc == RVQS_OK else { return }

let verifyRc = rvqs_verify_signature(qrData.baseAddress, qrData.count,
                                      key.baseAddress, key.count)
guard verifyRc == RVQS_OK else { showError("Invalid signature"); return }

Build for iOS:

cargo build --release --target aarch64-apple-ios --lib
cargo build --release --target aarch64-apple-ios-sim --lib

5.2 Web App — Zero App Store

For zero App Store involvement, the QR URL opens a Progressive Web App:

QR contains: https://brain.ruvector.ai/s/{seed-id}
         │
         ▼
Browser opens instantly (Safari, Chrome)
         │
         ▼
┌─────────────────────────────────────────┐
│ PWA with WASM RVF Loader                │
│                                         │
│  1. Fetch RVQS seed from URL path       │
│  2. Parse + verify in WASM              │
│  3. Decompress microkernel              │
│  4. Stream layers via fetch() API       │
│  5. Render intelligence in browser      │
│                                         │
│  Works offline via Service Worker cache  │
└─────────────────────────────────────────┘

Build for WASM:

cargo build --release --target wasm32-unknown-unknown --lib

The RVF loader compiles to ~50 KB WASM. Service Worker caches the loader + downloaded layers for offline use.

5.3 Android

Same C FFI approach, compiled for NDK targets:

cargo build --release --target aarch64-linux-android --lib

Called from Kotlin via JNI or from a WebView with the WASM build.

5.4 Delivery Comparison

Method Install Required App Store Review Boot Time Offline
App Clip (iOS) No Yes (light) <1s Yes
PWA / Web App No No ~2s Yes (SW)
Android Instant App No Yes <1s Yes
Full native app Yes Yes N/A Yes

6. C FFI Reference

The following extern "C" functions are exported for mobile integration:

// Parse the 64-byte header from a QR seed payload.
int rvqs_parse_header(const uint8_t* data, size_t data_len, RvqsHeaderC* out);

// Verify HMAC-SHA256 signature. Returns RVQS_OK (0) or error code.
int rvqs_verify_signature(const uint8_t* data, size_t data_len,
                          const uint8_t* key, size_t key_len);

// Verify content hash integrity. Returns RVQS_OK (0) or error code.
int rvqs_verify_content_hash(const uint8_t* data, size_t data_len);

// Decompress the embedded microkernel into caller's buffer.
int rvqs_decompress_microkernel(const uint8_t* data, size_t data_len,
                                 uint8_t* out, size_t out_cap, size_t* out_len);

// Extract the primary download URL from the manifest.
int rvqs_get_primary_host_url(const uint8_t* data, size_t data_len,
                               uint8_t* url_buf, size_t url_cap, size_t* url_len);

Error codes:

Code Name Meaning
0 RVQS_OK Success
-1 RVQS_ERR_NULL_PTR Null pointer argument
-2 RVQS_ERR_TOO_SHORT Payload smaller than header
-3 RVQS_ERR_BAD_MAGIC Invalid RVQS magic bytes
-4 RVQS_ERR_SIGNATURE_INVALID Signature verification failed
-5 RVQS_ERR_HASH_MISMATCH Content hash doesn't match data
-6 RVQS_ERR_DECOMPRESS_FAIL LZ decompression failed
-7 RVQS_ERR_BUFFER_TOO_SMALL Caller's buffer too small
-8 RVQS_ERR_PARSE_FAIL General parse failure

7. Size Budget (Actual Measured)

Component                    Raw Size    Compressed    In QR
─────────────────────────    ────────    ──────────    ─────
RVQS Header                  64 B        64 B          64 B
WASM Microkernel            5,500 B     2,095 B       2,095 B
Download Manifest (2 hosts)  496 B       496 B         496 B
HMAC-SHA256 Signature        32 B        32 B          32 B
─────────────────────────    ────────    ──────────    ─────
Total (measured)                                       2,687 B

QR Version 40, Low EC capacity: 2,953 B
Remaining headroom: 266 B

8. Example Use Cases

8.1 Business Card Brain

Print a QR code on a business card. Scan it to mount a personal AI assistant that knows your work, your papers, your projects. Offline-first. When connected, it streams your full knowledge base.

8.2 Medical Record Seed

A QR code on a patient wristband contains a signed seed pointing to their medical vector index. Scan to query drug interactions, allergies, treatment history. Works offline in the ER.

8.3 Firmware Intelligence

Embedded in a product's QR code: a cognitive seed that can diagnose problems, suggest fixes, and stream updated knowledge from the manufacturer.

8.4 Paper Backup

Print your AI's seed on paper. Store it in a safe. In a disaster, scan the paper and your AI bootstraps from printed ink. The signature proves it's yours.

8.5 Conference Badge

NFC/QR on a conference badge. Tap to mount the speaker's research brain. Walk around, scan badges, collect intelligences. Each one is signed by the speaker.

Implementation

Files

File Lines Purpose
rvf-types/src/sha256.rs 230 Pure SHA-256 (FIPS 180-4) + HMAC-SHA256 (RFC 2104)
rvf-types/src/qr_seed.rs 370 RVQS wire format types, SeedHeader, LayerEntry, HostEntry
rvf-runtime/src/compress.rs 210 LZ77 compression (SCF-1 format, 4KB window)
rvf-runtime/src/seed_crypto.rs 100 Sign, verify, content/layer hashing
rvf-runtime/src/qr_seed.rs 1050 SeedBuilder, ParsedSeed, TLV manifest, bootstrap progress
rvf-runtime/src/ffi.rs 240 C FFI for App Clip / mobile (5 exported functions)
rvf-runtime/examples/qr_seed_bootstrap.rs 250 Full demo: build → sign → parse → verify → decompress → bootstrap
rvf-runtime/tests/qr_seed_e2e.rs 220 11 end-to-end integration tests

Test Coverage

Module Tests Verified Against
SHA-256 11 NIST FIPS 180-4 test vectors
HMAC-SHA256 3 RFC 4231 test cases 1, 2, 5
LZ compression 11 Round-trip + WASM patterns
Seed crypto 10 Sign/verify/tamper detection
QR seed types 9 Header round-trip, flags, magic
QR seed runtime 12 Builder, parser, manifest TLV
C FFI 7 Parse, verify, decompress, URL extract
E2E integration 11 Full pipeline with real crypto

Total: 74 QR seed tests, all passing.

Consequences

Positive

  • Intelligence becomes physically portable — printed on paper, etched in metal, tattooed on skin
  • Zero external dependencies — SHA-256, HMAC, LZ compression, FFI all built from scratch
  • Mobile-first — App Clip (iOS), PWA (web), Instant App (Android) all supported via C FFI
  • Offline-first by design — the seed is useful before any network access
  • Cryptographically verified — HMAC-SHA256 signatures with constant-time comparison
  • Progressive loading — first query at 50% recall after 6% download
  • Self-upgrading — a seed can re-export itself with new knowledge

Negative

  • QR capacity limits seed size to ~2,900 bytes
  • HMAC-SHA256 requires a shared secret (symmetric); for asymmetric signatures, add ed25519-dalek as optional dep
  • Download manifest URLs have finite TTL — seeds expire unless hosts are stable
  • Built-in LZ compression is simpler than Brotli (~1.4-2.5x vs ~3-4x ratio)

Migration

  • Existing RVF files can generate QR seeds via SeedBuilder::new().compress_microkernel(&wasm).build_and_sign(key)
  • QR seeds bootstrap into standard RVF files — no special runtime needed
  • Seeds are forward-compatible: unknown TLV tags are ignored by older runtimes

References

  • QR Code Specification: ISO/IEC 18004:2015
  • SHA-256: FIPS 180-4
  • HMAC: RFC 2104
  • HMAC-SHA256 Test Vectors: RFC 4231
  • Apple App Clips: developer.apple.com/app-clips
  • RVF Spec 02: Manifest System (Level 0 / Level 1)
  • RVF Spec 11: WASM Self-Bootstrapping
  • ADR-029: RVF Canonical Format
  • ADR-030: Cognitive Container
  • ADR-033: Progressive Indexing Hardening
Reference in New Issue View Git Blame Copy Permalink