v2 Ruview kernel and governance/provenance subsystem
Overview
This area is the Rust v2 trust spine plus its Node-facing portable kernel. v2/Cargo.toml wires the covered crates into the workspace as the ADR-300 perception substrate (ruview-attest, ruview-evidence, ruview-witness, ruview-certify, ruview-scorecard, ruview-policy, ruview-hal, ruview-unified) and the ADR-368 compute package (ruview-kernel). PROOF.md is the project-level public contract: claims must be reproducible, and synthetic/data-gated/hardware-gated evidence must be labelled rather than implied.
The compute kernel is v2/…/lib.rs. It exposes one bounded string ABI, call(op, json) -> JSON envelope, and the binary fast path call_f64, shared by WASM and napi. The operations are info, validate_config, analyze, synthesize, session_open, session_push, session_summary, session_close, analyze_flat, and session_push_flat. Requests are bounded by MAX_INPUT_BYTES, frame counts by MAX_FRAMES_PER_CALL, subcarriers by MAX_SUBCARRIERS, and live streaming sessions by MAX_SESSIONS. Session validates every frame before processing, then runs the wifi-densepose-vitals EMA/preprocess, breathing, heart-rate, anomaly, and summary path. synthesize uses deterministic SplitMix64 and returns evidence: "SYNTHETIC".
The kernel transports deliberately share that same ABI. v2/…/wasm_abi.rs exports a zero-import C ABI (rvk_alloc, rvk_free, rvk_call, rvk_call_f64) and consumes input buffers before returning a packed pointer/length. v2/…/lib.rs wraps ruview_kernel::call and call_f64 through napi-rs and catches Rust panics into an internal error envelope. The npm loader in harness/…/index.js, src/abi.js, and src/wasm.js verifies artifact checksums when SHA256SUMS is present, rejects WASM modules with host imports, enforces the JS-side operation and input-size allow-list, and exposes the high-level analyze, analyzeFlat, synthesize, and session APIs. harness/…/kernel.js treats @ruvnet/ruview-kernel as an optional peer: absence is reported as kernel_not_installed, and the self-test is explicitly marked SYNTHETIC.
Authentication is v2/crates/ruview-auth. src/verify.rs verifies Cognitum access tokens offline as a resource server: ES256 only, key by JWKS kid, no aud/iss checks because production tokens do not carry them, and client_id is the audience substitute via VerifierConfig::allowed_client_ids. It rejects non-access tokens, setup/workload credentials, missing account_id, and missing route-specific scope before constructing Principal. src/principal.rs keeps scopes exact: sensing:admin does not imply sensing:read. src/jwks.rs owns the JWKS cache, releases its mutex before blocking fetches, rate-limits both routine and unknown-kid refetches, keeps stale keys on network failure after a successful warm, and fails closed only when no key set has ever been fetched. The optional login feature in src/…/flow.rs drives PKCE browser or OOB login and persists sessions, but verification does not depend on login.
Measurement provenance starts in v2/…/lib.rs. SignedMeasurement binds DeviceId, strictly monotonic per-device sequence, injected Timestamp, PayloadHash, optional CalibrationRef, and a fixed-width Signature over deterministic length-prefixed canonical bytes. AttestationVerifier holds enrolled device verifiers and last accepted sequence numbers. Its ingest check is device enrollment → signature → presented payload hash → replay sequence → freshness policy; only full success advances sequence state and emits VerifiedMeasurement. The bundled Blake3MacSigner is explicitly a SYNTHETIC-grade symmetric MAC reference, not production non-repudiation.
Accuracy evidence is v2/…/lib.rs. EvidenceLedger is append-only and bounded; EvidenceRecord fields are private and minted as synthetic, claimed, or measured. Synthetic records are forced to EvidenceLevel::L0; measured records require a non-empty reproducer. EvidenceContext keys every record by (room, device, subject_class, model_version). EvidenceLedger::query creates a single-context EvidenceSlice, and EvidenceSlice::summarize returns either NoEvidence or sample-weighted metrics with the evidence-level floor and a downgraded aggregate provenance class, never a pooled cross-room/global number.
Capability certification is v2/…/lib.rs. mint signs a CapabilityCertificate from one EvidenceSlice, a room SpaceId, an attested DeviceId, model version, calibration certificate, requested expiry, and requested evidence level. It refuses to mint if the slice has no evidence, the context does not match the room/device/model, the calibration room differs, the requested evidence level exceeds the slice floor, the expiry outlives calibration, or the model id is over the bound. A certificate is valid for use only when signed, not expired, and the live DomainState is Known; degraded/unknown domains invalidate the claim.
Witnessing is v2/…/lib.rs. WitnessChain::from_measurement roots a chain in an ADR-305 VerifiedMeasurement; stages can then append in strict order: RF observation, DSP evidence, model inference, independent corroboration, spatial state, and policy decision. Each Stage carries typed evidence, Confidence (including Unknown), evidence level, and prior-stage hash. WitnessChain::verify recomputes links, enforces monotonic stage order, verifies the terminal head hash, and reports the effective evidence level as the minimum across stages. Corrections are new chains referencing a prior head, not in-place edits.
Action authorization is split between the pure policy gate and governed receipts in v2/crates/ruview-policy. src/lib.rs maps assurance inputs to Authorization: certificate validity, certificate class, calibration age, domain state, uncertainty, and evidence level are evaluated in a fixed fail-closed order against ActionClass requirements (Convenience, Security, SafetyCritical). authorize_from_certificate is the real adapter from ruview-certify::CapabilityCertificate and ruview_ood::DomainState, deliberately separating signature/time validity from domain-denial attribution. src/governed.rs adds executable governance: ActionIntent canonical bytes and digest, registered ActionRules, exact authority grants, signed SignedApprovals, and signed hash-chained ActionReceipts from GovernanceEngine. Observe/recommend modes produce receipts without executing; execute requires policy match, authority, target allow-list, enough distinct valid approvals, and the assurance gate. Receipts authorize at most; they do not assert physical actuation.
Benchmark promotion discipline is v2/…/lib.rs. Metric computes deterministic Wilson confidence intervals and carries one EvidenceLevel; Metric::synthetic forces L0. Scorecard stores one Cell per operating domain (presence known/unseen/device/stationary, pose matched/unseen, OOD rejection, calibration drift) plus optional domain-state fractions. worst_domain treats NoEvidence as worse than any scored cell, pooled_accuracy is labelled insufficient, and promotion_gate fails on any per-domain regression or coverage loss even if pooled accuracy improved.
The HAL and unified model provide governed ingest context. v2/…/lib.rs and src/adapter.rs define SensorHal::describe and infallible normalize, mapping native modality samples to ontology Observations wrapped in HalObservation. Synthetic CSI and IMU adapters stamp EvidenceLevel::L0 and the synthetic calibration handle; malformed native input yields an UNKNOWN/degraded observation rather than an error or panic. v2/…/lib.rs is the RF world-model core: canonical RF tensors/adapters, encoder/pretraining/heads, Gaussian spatial memory, synthetic RF worlds, and privacy policy. Its exported boundary is policy::BoundedEvent, and its crate docs state raw RF should not cross the trust boundary.
The JS harness has a separate least-authority surface. harness/…/policy.js assigns each CLI/MCP tool a policy class, required grant, read-only/destructive/open-world annotations, and confirmation requirement for workspace or hardware writes. harness/…/repo-trust.js refuses CLI access unless the repository root is the configured trusted root and carries RuView markers. This is not the same as Rust ruview-policy; it is the harness-side tool authorization layer.
Coupling
- If v2/…/lib.rs changes
ABI_VERSION,OPERATIONS, request fields, response envelopes, or flat-frame layout, also update harness/…/abi.js, harness/…/wasm.js, v2/…/wasm_abi.rs, and v2/…/lib.rs. Both npm backends rely on one operation-name/string-in/string-out ABI; drift creates backend parity bugs. - If kernel artifact handling changes in harness/…/index.js, verify harness/…/kernel.js still reports backend, fallback, integrity, and SYNTHETIC self-test status honestly. The umbrella harness treats the kernel as optional and must not turn missing native/WASM artifacts into a fabricated pass.
- If Cognitum token claims or client registration rules change, update v2/…/verify.rs and src/principal.rs together.
client_idis the audience substitute, scopes are exact and non-hierarchical, and setup/workload tokens are refused because revocation is unverifiable offline. - If JWKS caching policy changes in v2/…/jwks.rs, verify async server callers still avoid holding a blocking mutex across network I/O. The verifier is designed for Pi-class offline operation: startup warm fails closed, later WAN loss serves stale known keys rather than stalling every request.
- If
ruview-attestcanonical bytes change, all consumers that store or re-serialize verified lineage need review: v2/…/lib.rs rootsRfObservationinVerifiedMeasurement, v2/…/lib.rs reuses theSigner/Verifiersignature abstraction, and v2/…/governed.rs signs approvals/receipts with the same fixedSignaturetype. - If
ruview-evidence::EvidenceLevelor summary semantics change, update v2/…/lib.rs, v2/…/lib.rs, and v2/…/lib.rs. Certification inherits the ledger floor, policy compares evidence floors for action classes, and scorecards re-export the evidence ladder for benchmark cells. - If OOD/domain-state types change in
ruview_ood, update both adapters in v2/…/lib.rs and v2/…/lib.rs. Certificate validity and policy authorization intentionally apply the domain gate at different layers, andauthorize_from_certificatekeeps domain denials attributable asDomainNotKnown/DomainDegradedrather than generic certificate invalidity. - If
wifi_densepose_calibration::CalibrationCertificatefields change, update v2/…/lib.rs. Minting binds calibration version, capture date, room id, and expiry ceiling into signed certificate content. - If ontology identifiers or
Observationfields change, update v2/…/adapter.rs and certification room binding in v2/…/lib.rs. HAL constructs ontology observations directly, while certificates bindSpaceIdand device identities into claims. - If a new CLI/MCP tool is added under
harness/ruview, add an entry in harness/…/policy.js before exposing it. Unknown tools deny by default, but missing policy will surface aspolicy_missingrather than an intentional capability decision.
Risks
- v2/…/jwks.rs and v2/…/verify.rs have auth fragility history:
git logshows7a054174 fix(auth): scope gate was fail-OPEN; JWKS lock held across a blocking fetchfollowed by89cce79 fix(auth): close P1/P2/P3 — JWKS stall, 12h session, cookie shadowing. If scope, audience, token lifetime, or JWKS refresh logic changes, a mistake can either accept tokens that should be denied or stall all concurrent requests during WAN loss. - v2/…/lib.rs and v2/…/lib.rs had a later wiring fix (
73e82313 fix: issue triage batch (#1521-1557) + wire the certificate spine together) after the initial dependent-wave feature. The fragile point is composition: hand-built local enum tests can pass while real certificate/OOD values never reach the authorization gate. Changes here should exerciseauthorize_from_certificateand theruview_oodadapters, not only localDomainStateconstructors. - v2/…/lib.rs, v2/…/wasm_abi.rs, and harness/…/abi.js added a binary fast path after the initial npm kernel (
43f16e56 perf(npm): binary kernel transport, faster device e2e, and CI fixesafter1938f025 feat(npm): @ruvnet/ruview-kernel). Flat data layout is therefore a parity-sensitive surface: if the amplitude/phase packing orMAX_INPUT_BYTESchecks diverge, WASM/napi/JSON paths can analyze different frames or reject at different boundaries. - v2/…/lib.rs uses
Blake3MacSigneras a reference signer. If that type is reused in production provisioning, verifiers hold the signing secret and there is no non-repudiation; spoof-resistance claims would be overstated. Production deployments need a real asymmetricSigner/Verifierimplementation and hardware evidence.