[PIR][WP8] Conform promotion records to ruflo ADR-322C for anchoring into rvm witness chains

[ruvnet]

Epic: #12 · Cross-repo counterparts: ruvnet/rvm#35 (anchor chain), ruvnet/ruflo#3066 (the contract) · Program epic: ruvnet/RuVector#837 · Plan: 03-program-plan.md in ruvnet/ruvector

⚠️ Two premise corrections — this issue has been reframed twice

(1) This crate is not a duplicate, and its original title was wrong. An earlier program pass said this repo's witness crate duplicates rvm-witness and should be refactored to depend on it. Source verification found that framing is wrong, and this issue no longer asks for it:

	this repo's witness	rvm-witness
Size	~302 LOC	~4,405 LOC
Crypto	SHA-256 / Ed25519	ratcheted MAC
Structure	service-side records	no_std ring buffer
Layer	application / service	hypervisor

Architecturally different by design. A 302-LOC service-side signing layer taking a dependency on a 4,405-LOC no_std hypervisor ring buffer would be a mistake, not a cleanup. Neither should merge into or depend on the other.

(2) The shared contract already exists — do not design a new one. This issue previously asked for a new shared schema. ruvnet/ruflo ADR-322 (Status: Accepted, phases 0–2 implemented) already specifies the 322C verification stack — JCS canonicalization, SHA-256, Ed25519 with domain separation, and independent statistical recomputation — plus proposer/promoter separation of powers. See also ruflo ADR-381. PIR adopts it as the canonical cross-repo contract (ruvnet/ruflo#3066).

⚠️ Citation correction that originates in this repo

ADR-400 and ADR-401 in this repo cite a "metaharness ADR-322." That is a misattribution. ADR-322 is ruvnet/ruflo's ADR, not MetaHarness's — and MetaHarness's own ADR series tops out at 250, so no ADR-322 can exist there. Correcting this at the source is an acceptance criterion below, because the program has already had to route around it once.

Goal

Make promotion records produced here conform to ruflo ADR-322C, so they can be anchored into an RVM witness chain (ruvnet/rvm#35) and independently verified against it.

Same chain of custody, two implementations, one already-accepted contract. This repo keeps its own implementation.

Why the program needs this

PIR's acceptance test requires every promoted mutation across a 30-day run to be traceable end-to-end in a single witness-chain query: proposal → evaluation → promotion → resulting state. Anchoring against a shared contract makes that query writable without either side giving up its architecture.

Grounding note

The real implementation here is TypeScript in packages/radio-moe/ (~6.2K LOC source + 3.2K LOC test), not the Rust crate listing an earlier program pass pointed at. Scope this work against the TypeScript.

This repo is PIR's primary prior art, not a downstream consumer: ADR-401 "The Perpetual Intelligence Machine" (Accepted, 2026-08-16), ADR-400 (Accepted — implemented, first flywheel turn measured), and ADR-403 (Accepted) already define the concept PIR extends.

Acceptance criteria

• Promotion records emitted here conform to ruflo ADR-322C — JCS canonicalization, SHA-256, Ed25519 with the specified domain separation — and carry what the independent statistical recomputation step requires.
• Records are verifiably anchorable into an RVM chain, demonstrated by a cross-repo test with [PIR][WP8] Anchor autogenous promotion records into rvm-witness chains via ruflo ADR-322C rvm#35.
• No dependency edge on rvm-witness is introduced, and none in reverse. A review criterion confirms this.
• ADR-322C's proposer/promoter separation of powers is preserved across the repo boundary.
• lineage, ledger, and promotion continue to work unchanged from their callers' perspective.
• Existing records are either convertible to ADR-322C or explicitly declared non-portable, with consequences for historical audit stated rather than discovered later.
• The anchored record's assurance level is documented honestly — a service-side record anchored into a hypervisor chain does not thereby acquire hypervisor-side guarantees (per rvm ADR-285's discipline).
• Rollback via the existing promotion/rollback controller still fires correctly with anchored records — verified by an injected failure, not unit tests alone, since WP12 depends on that path working live.
• ADR-400 and ADR-401's "metaharness ADR-322" citations are corrected to point at ruvnet/ruflo's ADR-322.
• Both maintainer teams sign off.

Dependencies

ruvnet/ruflo#3066 (the contract) and WP1. Paired with ruvnet/rvm#35. Blocks WP11 (#11).

[ruvnet]

Upstream dependency now owned — spec extraction in progress. ruvnet/ruflo#3066 has an assigned owner extracting ADR-322C into a language-neutral spec + JSON Schemas + conformance checklist as a draft PR to ruflo, cross-referencing this issue.

The JSON Schemas and conformance checklist are the practical form of this issue's "conform promotion records to ADR-322C" criterion, so this unblocks the concrete work. Note from source verification: ADR-322C has three signing domains, not one, which affects how records emitted here are signed for anchoring.

[ruvnet]

Contract spec is open as a draft PR: ruvnet/ruflo#3067 — feat/pir-322c-contract-spec.

Delivers v3/docs/spec/witness-receipt-contract.md, three JSON Schemas, example fixtures generated by the real implementation (Ajv-strict validated, tamper-tested and untrusted-signer-tested against ruflo's actual code), and a conformance checklist. Fixtures generated from the real implementation rather than hand-written matter here — hand-written fixtures encode what the author believed the format was.

Four things to build against — read before writing anchoring code

(a) Anchor the RECEIPT, not the ledger head. ruflo.flywheel-receipt/v1 is the only record type whose signature is implemented. The flywheel-ledger-head/v1 signing is specified but not implemented on main. Anchoring to the ledger head would mean anchoring to a signature that does not exist yet.

(b) The anchor-record format is a PIR PROPOSED-EXTENSION, not part of 322C. ADR-322C is silent on all of it — the anchor-record format itself, its signing domain ruflo/flywheel-anchor/v1, and the assuranceLevel field (service-side | hypervisor-side, per rvm ADR-285). Treat these as PIR proposals pending ruflo review, and say so in any ADR that cites them. This is the exact failure mode the program has now hit four times — citing something as an established contract when it is a proposal — so it is worth being explicit rather than letting the distinction erode.

(c) Open decision for both consumers: version policy. Pin schemaVersion + gateVersion strings, not ruflo git SHAs. A SHA pin couples this repo's release cadence to ruflo's commit history and violates the program's release-train rule.

(d) Wording fix — there is no "witness record" type in 322C. The contract defines a receipt plus a commit chain, and nothing called a witness record. Where our issues say "witness record" meaning an ADR-134/RVM record, that remains correct — RVM's own witness records are a real thing. But do not attribute a "witness record" type to 322C, and do not let the two senses blur in an ADR.

Correction to my earlier comment: TWO signing domains, not three

I wrote that ADR-322C carries "three signing domains." That is wrong. It defines two Ed25519 signing domains:

• flywheel-receipt/v1
• flywheel-ledger-head/v1 (specified, not implemented on main — see (a))

bootstrap/v1 is a deterministic-seed prefix in the statistics section, not a signing domain. I mistook a third …/v1 string for a third domain. Enumerate two in the verification contract, not three.

Two open ruflo issues that affect this work

• verifyFlywheelReceipt accepts unknown fields, contrary to ADR-322C ruflo#3068 (security) — verifyFlywheelReceipt currently accepts unknown fields, contrary to ADR-322C; only the JSON Schemas' additionalProperties: false enforces it today. Until that lands, run schema validation alongside verifyFlywheelReceipt rather than relying on the verifier alone — otherwise the anchoring inherits the permissiveness.
• ADR-322C under-specifies independent recomputation (bootstrap PRNG only in source) ruflo#3069 (docs) — ADR-322C under-specifies independent recomputation; the paired-bootstrap PRNG exists only in source. Relevant if this side ever needs to recompute rather than just verify signatures.

[ruvnet]

Cross-link: ruvnet/ruflo#3072 found that verifyFlywheelReceipt recomputed statistics from full-precision inputs while receipts store scale-12 strings, so legitimate receipts could fail verification — an availability risk WP8 conformance would have inherited. Fixed (encode-first, producer/verifier bit-identical) pending merge of ruvnet/ruflo#3073.

[ruvnet]

Workaround retirement: with ruvnet/ruflo#3070 merged, verifyFlywheelReceipt now rejects unknown fields per ADR-322C — the interim guidance to run schema validation alongside the verifier is no longer required (still fine as belt-and-braces, but optional). The full 322C contract spec + schemas + conformance checklist merged via ruvnet/ruflo#3067 and are canonical on ruflo main; note the recorded correction that signature fields exist in 2 of 3 schemas (promotion-commit is unsigned by spec). Conformance confirmation from this issue is now what gates closing ruflo#3066.

[ruvnet]

Owner assigned. A wp8-anchoring agent now owns this issue and ruvnet/rvm#35 together, implementing the conformance slices against the merged ADR-322C spec and fixtures (ruvnet/ruflo#3067, canonical on ruflo main). Scope for this repo: promotion-record mapping/export to the 322C schemas. Deliverables: one draft PR for this repo, a conformance-checklist walkthrough posted here, and the version-policy recommendation — the last two are also what gates closing ruflo#3066.

[ruvnet]

Conformance delivered as draft PR #13 — promotion evidence exported in the ruflo.flywheel-receipt/v1 shape, integrated where promotions are actually emitted (promoteAuthorized / evolveMesh in packages/radio-moe, ADR-401 Decision 3), built against the contract merged on ruflo main (ruvnet/ruflo#3067) and the guidance in this thread.

Conformance confirmation

Tested against the ruflo fixtures verbatim (copied at merge commit df0c9821984b2b0f76ea0ea6eb6cfe5abda5bd54, sums in the test header); 18 new tests, full radio-moe suite 165 pass / 1 pre-existing env-gated skip / 0 fail:

• Producer items A1–A8 pass: strict unknown-field refusal (gap G3's consumer obligation), no binary floats or -0 anywhere, content IDs per §3, signature over UTF8(domain) || 0x00 || JCS(payload) per §4 — ruflo-produced fixture signatures verify under our canonicalization AND our signatures verify under bare node:crypto, so canonical bytes agree in both directions. A5 (stable candidateId, fresh evaluationRunId/receiptId) and A8 (pairedOutcomes reproduce heldOutDeltas from encoded scores — the gap-G5 lesson applied producer-side from day one) hold.
• B5 the discriminating bootstrap-reference fixture recomputes byte-for-byte (0.100428571429 / 1 / 0.0489 / accepted, seedHex 167c…a7c3); tamper/oversized-signature/wrong-domain/untrusted-signer/expiry/role-overlap all refused.
• Honest evidence grades (§5): better/safe are recomputed; authorized/reversible are trusted-assertion naming the governed loop — they are caller-supplied conjuncts, so any stronger grade would be a lie. Consumers must not label these promotions independently verified without approving that attestor.
• The exported decision follows the contract's rule (statistics.accepted && all gates), never relabeling this repo's own margin rule — the export states what the 322C gate would say.
• C5: no dependency edge to rvm-witness in either direction; the anchoring side is feat(anchor): verify and anchor ruflo ADR-322C receipts into the witness chain (WP8, #35) rvm#37, which consumes these receipts through the contract alone.

Scoped-out remainder (honest enumeration, per the issue's convergence-must-not-hide-gaps rule)

1. No held-out promotion corpus. The loop selects and promotes on the same frozen bench, so promotionHoldoutTaskIds exports empty — disjointness (B7) holds vacuously while the substantive ADR-322 Track C gap stays visible. Closing it means growing a promotion-holdout bench the mutation search never sees.
2. No 322C commit chain. This repo's ledger is AgentFrame-based; mapping it onto the promotion-commit/ledger-head shape (checklist C1–C2) is not attempted — the ledger-head signature is unimplemented on ruflo main anyway (gap G2). If wanted, that is a follow-up work item.
3. resourceEvidence zeroed — the loop does not meter cost/latency/tokens yet.
4. Separation of powers (D1): the exporting mesh signs with its own PeerIdentity; trusted-key and approved-attestor sets must live with the anchoring/promoting side, never this exporter. rvm#37's anchorer takes them as caller inputs accordingly.

Version-policy recommendation (open decision (c)) — put here for ratification

Pin schemaVersion + gateVersion strings, never ruflo git SHAs. As implemented: RECEIPT_SCHEMA_VERSION = "ruflo.flywheel-receipt/v1" and RECEIPT_GATE_VERSION = "ruflo.flywheel-gate/v1" are exact-match constants; the verifier refuses unrecognized versions rather than best-effort parsing (F2), and can only apply the gate rule it implements, which delivers F3's no-retroactivity structurally. No ruflo commit SHA appears anywhere, keeping the program's release-train rule intact. Identical recommendation posted on ruvnet/rvm#35; ratifying it on both closes the version-policy item gating ruvnet/ruflo#3066.

🤖 Generated with claude-flow