Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

docs(adr): make ADR-322C recomputation reproducible from the spec alone

ruv66fbe7ce12d8
diff --git a/v3/docs/adr/ADR-322C-receipt-ledger-verification.md b/v3/docs/adr/ADR-322C-receipt-ledger-verification.md
index f845f43860..b17a4abd46 100644
--- a/v3/docs/adr/ADR-322C-receipt-ledger-verification.md
+++ b/v3/docs/adr/ADR-322C-receipt-ledger-verification.md
@@ -150,3 +150,159 @@ The adapter projects ruflo policy and evidence into `@metaharness/flywheel` type
6. Key revocation and rotation produce the declared historical/current verification behavior.
7. The Flywheel adapter round-trips without loss of ruflo-authorizing evidence; projection loss blocks interoperability claims.
8. Removing optional packages does not disable native receipt or ledger verification.
+
+## Update (2026-08-19) — normative recomputation procedure, ledger status, projection status
+
+Raised by ruflo#3069 during the ADR-322C contract extraction for the RuV Perpetual
+Intelligence Runtime (ruflo#3066, PR #3067). Appended rather than edited into the
+text above, per this repo's norms around honest documentation.
+
+**The problem.** This ADR's central claim is that a verifier *recomputes* the
+statistics rather than trusting the proposer's reported numbers. But the sections
+above specify only the bootstrap **seed**, not the generator it drives, the
+resampling procedure, or the decimal encoding of the results. An independent
+verifier therefore could not reproduce a receipt's statistics from this document —
+the only way to recompute correctly was to read `flywheel-receipt.ts`, which is a
+copy, not an independent check. The recomputation requirement was unverifiable in
+practice. The procedure below closes that; it is transcribed from
+`flywheel-receipt.ts:206-307` and is normative from this Update onward.
+
+### 1. Deterministic PRNG
+
+```text
+digest = SHA-256("ruflo/bootstrap/v1" || corpusHash || candidateId ||
+ baselineRef || evaluationRunId) # concatenation, no separator
+seedHex = lowercase hex of the full 32-byte digest # recorded in the receipt
+state = uint32 big-endian read of digest[0..4] # FIRST FOUR BYTES ONLY
+```
+
+Each draw advances a linear congruential generator and returns a value in `[0, 1)`:
+
+```text
+state = (1664525 * state + 1013904223) mod 2^32
+draw = state / 2^32
+```
+
+The multiplier, increment, and modulus are exact. `state` is unsigned throughout.
+The first draw uses the *advanced* state, never the seed value itself.
+
+### 2. Resampling procedure
+
+`iterations` defaults to 10,000, must be an integer, and must be `>= 100`. Let `n`
+be the length of `heldOutDeltas`.
+
+```text
+if n == 0:
+ every resample mean is 0
+else:
+ for b in 0 .. iterations-1:
+ total = 0
+ for i in 0 .. n-1:
+ total += heldOutDeltas[ floor(draw() * n) ]
+ means[b] = total / n
+```
+
+Draw order is load-bearing: exactly `n` draws per iteration, consumed in sequence.
+An implementation that draws indices in a different order, or draws once per
+iteration, produces a different — and non-conforming — result.
+
+```text
+pairedBootstrapProbability = count(means[b] > 0) / iterations # strictly greater
+pairedBootstrapDeltaCILow95 = the floor(0.025 * iterations)-th smallest of means
+ # 0-based order statistic (selection, not sorting;
+ # any correct selection algorithm is conforming)
+```
+
+### 3. Decision
+
+```text
+relativeLift = (candidateScore - baselineScore) / max(|baselineScore|, metricEpsilon)
+metricEpsilon defaults to 1e-12
+significant = pairedBootstrapProbability >= 0.95 AND pairedBootstrapDeltaCILow95 > 0
+accepted = relativeLift >= 0.02 AND significant AND frozenAnchorRegression <= 0
+decision = "accepted" if (accepted AND every value in gates is true) else "rejected"
+```
+
+Comparisons are on the numeric values, before decimal encoding.
+
+### 4. Decimal encoding of results
+
+The `statistics` object must reproduce **byte-for-byte** under JCS, so its encoding
+is part of the contract. Every fractional field is encoded by:
+
+```text
+1. fixed-point render at scale 12 (twelve digits after the decimal point)
+2. strip trailing zeros, then a trailing decimal point if one remains
+3. if the result is "" or "-0", emit "0"
+```
+
+So `0.0928571428571...` renders `"0.092857142857"`, `1` renders `"1"`, and `0`
+renders `"0"`. This applies to `relativeLift`, `pairedBootstrapProbability`,
+`pairedBootstrapDeltaCILow95`, and `frozenAnchorRegression`, and to the
+`baselineScore`, `candidateScore`, and `heldOutDeltas` fields.
+
+**A producer must compute the statistics from the encoded values, not from its
+internal full-precision values.** A verifier has only the encoded strings, so any
+precision the producer used but did not record is precision the verifier cannot
+reproduce. Stated as a rule: decode `baselineScore`, `candidateScore`, and
+`heldOutDeltas` back from their encoded form and compute from *those*, so producer
+and verifier are evaluating identical inputs by construction.
+
+**Known divergence (2026-08-19).** `createFlywheelReceipt` currently violates this:
+it computes `statistics` from full-precision means while storing scale-12 strings,
+so a receipt whose mean needs more than twelve decimals fails its own
+`verifyFlywheelReceipt` with `statistical decision does not recompute`. Reproduced
+with twenty-four 3-decimal task scores (mean `0.7687083333333332`, stored
+`"0.768708333333"`), which shifts `relativeLift` by one unit in the last place.
+Receipts with exactly-representable means are unaffected, which is why existing
+fixtures pass. This is a defect against the rule above, not a change to it.
+
+### 5. Ledger: what is implemented, what is aspirational
+
+The §Ledger section above describes content-addressed segments binding
+`segmentId`/`previousSegmentId`/`firstSequence`/`lastSequence`/`commits[]`/
+`segmentMerkleRoot`/`createdAt`, plus a **signed** head under
+`ruflo/flywheel-ledger-head/v1`. **That is not what `main` implements.** The
+implementation (`flywheel-transaction.ts:553-568`, `619-636`) is a flat,
+sequence-numbered `commits[]` array inside one transaction-state file:
+
+```text
+commitId = SHA-256(JCS(commit with commitId omitted))
+ledgerHead = SHA-256(JCS({ previous: <prior head>, commitId: <commitId> }))
+genesis = sha256:<64 zeros>
+```
+
+There are no segments, no `segmentMerkleRoot`, and **the head is not signed** — the
+`ruflo/flywheel-ledger-head/v1` domain is specified but unused on `main`. Chain
+integrity today rests on the hash chain plus the signed receipt each commit
+consumes, not on a head signature.
+
+Consumers anchoring across a repo boundary must therefore anchor the **receipt**
+(`ruflo.flywheel-receipt/v1`), the only record type whose signature is implemented.
+Anchoring a ledger head today means anchoring an unsigned hash-chain value, and
+must be described that way. Segments and head signing remain the intended target;
+this Update records the divergence rather than leaving consumers to read the ADR as
+a description of what exists.
+
+### 6. Flywheel projection is disabled
+
+Per ADR-322 §"Current Metaharness capability inventory", external Flywheel receipt
+projection is intentionally disabled until a projection can preserve ruflo's gate
+and evidence semantics without information loss. No upstream round-trip is
+available, so a consumer cannot export state and feed it back to confirm the
+round-trip preserves meaning. Re-enabling it is gated on the ADR-322 phase-3
+projection cross-check landing in CI; until then §Flywheel projection describes an
+intended capability, not a shipped one.
+
+### 7. Strictness is versioned
+
+Unknown fields fail verification for a given schema version (§Canonical format).
+A consequence worth stating: a verifier implementing `ruflo.flywheel-receipt/v1`
+will reject a receipt from a future version that adds fields. That is the correct
+behavior for a security property — fail closed on the unrecognized — but it means
+schema evolution requires consumers to upgrade before they can verify newer
+receipts, not merely to tolerate them.
+
+A language-neutral extraction of this protocol, with JSON Schemas, worked examples,
+and a conformance checklist, is maintained at
+[`../spec/witness-receipt-contract.md`](../spec/witness-receipt-contract.md).
diff --git a/v3/docs/spec/conformance-checklist.md b/v3/docs/spec/conformance-checklist.md
index 73c42e2658..b4582c134a 100644
--- a/v3/docs/spec/conformance-checklist.md
+++ b/v3/docs/spec/conformance-checklist.md
@@ -49,10 +49,22 @@ consequences of the same rules.
promotion signature (contract §4).
- [ ] **B5** The statistical decision is **recomputed**, not read. Your bootstrap
reproduces `relativeLift`, `pairedBootstrapProbability`,
- `pairedBootstrapDeltaCILow95`, and `accepted` **exactly** for the reference
- fixture, using the seed and PRNG in contract §6.1. Expected values for that
- fixture: `0.092857142857`, `1`, `0.0425`, `true`, with
- `seedHex = be51f05643bce93feb04b7da659e290a203a1a62b5cb408b9c46554df528da84`.
+ `pairedBootstrapDeltaCILow95`, and `accepted` **exactly** for
+ [`examples/receipt-bootstrap-reference.example.json`](./examples/receipt-bootstrap-reference.example.json),
+ using the procedure now normative in ADR-322C §Update (2026-08-19). Expected:
+ `0.100428571429`, `1`, `0.0489`, `true`, with
+ `seedHex = 167c9185d76163dfa69ae57c11af813669a6353abcb49d7af673acf918f3a7c3`.
+ Use **that** fixture, not `receipt-accepted.example.json` — only its deltas are
+ heterogeneous enough to discriminate. Verified: a wrong seed slice, wrong byte
+ order, or different LCG constants all produce `0.0425` on the accepted-receipt
+ fixture (indistinguishable) but `0.04975` / `0.04965` / `0.04915` on this one.
+ [`conformance/recompute_reference.py`](./conformance/recompute_reference.py) is a
+ runnable oracle you can diff your implementation against.
+- [ ] **B5a** Your producer computes statistics from the **encoded** scores, not
+ from internal full-precision values — a verifier only ever sees the encoded form.
+ Note contract gap G5: ruflo's own producer does not yet do this, so a receipt
+ whose mean needs more than twelve decimals fails its own verifier. Distinguish
+ that failure from tampering when triaging.
- [ ] **B6** Float and decimal fixtures produce identical hashes across every
runtime you support (Rust and TypeScript both matter here). **[322C]**
- [ ] **B7** Corpus-role disjointness is checked — a task ID appearing in both
diff --git a/v3/docs/spec/conformance/recompute_reference.py b/v3/docs/spec/conformance/recompute_reference.py
new file mode 100644
index 0000000000..a9f60b3743
--- /dev/null
+++ b/v3/docs/spec/conformance/recompute_reference.py
@@ -0,0 +1,126 @@
+"""
+Independent reference implementation of the ADR-322C bootstrap recomputation.
+
+Written ONLY from the prose of ADR-322C's "Update (2026-08-19)" amendment, with
+no reference to flywheel-receipt.ts. Deliberately in a different language from
+the reference implementation: an independent check written by reading the TypeScript
+would be a copy, not a check (ruflo#3069).
+
+It exists to answer one question -- is the specification sufficient to reimplement
+from? -- and doubles as a runnable oracle for consumers building their own verifier.
+
+Usage:
+ python3 recompute_reference.py ../examples/receipt-bootstrap-reference.example.json
+
+Exits 0 when the recomputed statistics match the receipt's recorded ones.
+Use receipt-bootstrap-reference.example.json, not receipt-accepted.example.json:
+only the former has heterogeneous per-task deltas, so only the former actually
+discriminates a wrong PRNG (see witness-receipt-contract.md section 6.1).
+"""
+import hashlib
+import json
+import sys
+
+
+def seed_state(corpus_hash, candidate_id, baseline_ref, evaluation_run_id):
+ """Section 1: SHA-256 over the concatenation, no separator."""
+ data = ("ruflo/bootstrap/v1" + corpus_hash + candidate_id
+ + baseline_ref + evaluation_run_id).encode("utf-8")
+ digest = hashlib.sha256(data).digest()
+ seed_hex = digest.hex()
+ state = int.from_bytes(digest[0:4], "big") # FIRST FOUR BYTES ONLY
+ return seed_hex, state
+
+
+def make_rng(state):
+ """Section 1: LCG. First draw uses the advanced state."""
+ s = state
+
+ def draw():
+ nonlocal s
+ s = (1664525 * s + 1013904223) % (2 ** 32)
+ return s / (2 ** 32)
+
+ return draw
+
+
+def bootstrap(deltas, draw, iterations=10000):
+ """Section 2: exactly n draws per iteration, consumed in sequence."""
+ n = len(deltas)
+ if n == 0:
+ return [0.0] * iterations
+ means = []
+ for _ in range(iterations):
+ total = 0.0
+ for _ in range(n):
+ total += deltas[int(draw() * n)]
+ means.append(total / n)
+ return means
+
+
+def decimal12(value):
+ """Section 4: scale 12, strip trailing zeros then trailing point, '' or '-0' -> '0'."""
+ rendered = f"{value:.12f}"
+ if "." in rendered:
+ rendered = rendered.rstrip("0").rstrip(".")
+ if rendered in ("", "-0"):
+ return "0"
+ return rendered
+
+
+def recompute(receipt_payload):
+ p = receipt_payload
+ deltas = [float(d) for d in p["heldOutDeltas"]]
+ baseline = float(p["baselineScore"])
+ candidate = float(p["candidateScore"])
+ frozen_anchor = float(p["statistics"]["frozenAnchorRegression"])
+ iterations = p["statistics"]["iterations"]
+ metric_epsilon = 1e-12
+
+ seed_hex, state = seed_state(
+ p["corpusHash"], p["candidateId"], p["baselineRef"], p["evaluationRunId"]
+ )
+ means = bootstrap(deltas, make_rng(state), iterations)
+
+ probability = sum(1 for m in means if m > 0) / iterations
+ ci_low = sorted(means)[int(0.025 * iterations)] # 0-based order statistic
+
+ # Section 3
+ relative_lift = (candidate - baseline) / max(abs(baseline), metric_epsilon)
+ significant = probability >= 0.95 and ci_low > 0
+ accepted = relative_lift >= 0.02 and significant and frozen_anchor <= 0
+ decision = "accepted" if (accepted and all(p["gates"].values())) else "rejected"
+
+ return {
+ "seedHex": seed_hex,
+ "relativeLift": decimal12(relative_lift),
+ "pairedBootstrapProbability": decimal12(probability),
+ "pairedBootstrapDeltaCILow95": decimal12(ci_low),
+ "frozenAnchorRegression": decimal12(frozen_anchor),
+ "significant": significant,
+ "accepted": accepted,
+ "decision": decision,
+ }
+
+
+if __name__ == "__main__":
+ receipt = json.load(open(sys.argv[1]))
+ payload = receipt["payload"]
+ got = recompute(payload)
+ want = {
+ "seedHex": payload["statistics"]["seedHex"],
+ "relativeLift": payload["statistics"]["relativeLift"],
+ "pairedBootstrapProbability": payload["statistics"]["pairedBootstrapProbability"],
+ "pairedBootstrapDeltaCILow95": payload["statistics"]["pairedBootstrapDeltaCILow95"],
+ "frozenAnchorRegression": payload["statistics"]["frozenAnchorRegression"],
+ "significant": payload["statistics"]["significant"],
+ "accepted": payload["statistics"]["accepted"],
+ "decision": payload["decision"],
+ }
+ ok = True
+ for k in want:
+ match = got[k] == want[k]
+ ok = ok and match
+ print(f"{'OK ' if match else 'FAIL'} {k}: got={got[k]!r} want={want[k]!r}")
+ print("\nRESULT:", "spec is sufficient" if ok else "SPEC INSUFFICIENT")
+ sys.exit(0 if ok else 1)
diff --git a/v3/docs/spec/examples/receipt-bootstrap-reference.example.json b/v3/docs/spec/examples/receipt-bootstrap-reference.example.json
new file mode 100644
index 0000000000..d25c9eabc7
--- /dev/null
+++ b/v3/docs/spec/examples/receipt-bootstrap-reference.example.json
@@ -0,0 +1,261 @@
+{
+ "payload": {
+ "schemaVersion": "ruflo.flywheel-receipt/v1",
+ "lineageId": "0198f2a0-0000-7000-8000-00000000b1c2",
+ "candidateId": "sha256:61c84d2769efc8fa1f5e76d2c3d645763cf013a38fa658edaccaede460a172a2",
+ "evaluationRunId": "0198f2a0-0000-7000-8000-00000000d3e4",
+ "baselineRef": "sha256:3f786850e387550fdab836ed7e6dc881de23001b0b4b1b0f0a1a2b3c4d5e6f70",
+ "expectedLedgerHead": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
+ "candidatePolicy": {
+ "hnswEf": 128,
+ "hybridWeight": "0.65",
+ "rerankDepth": 24
+ },
+ "gateVersion": "ruflo.flywheel-gate/v1",
+ "policySchemaVersion": "ruflo.retrieval-policy/v1",
+ "safetyEnvelopeRef": "sha256:9a271f2a916b0b6ee6cecb2426f0b3206ef074578be55d9bc94f6f3fe3ab86aa",
+ "anchorRef": "sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
+ "requestedProposer": "auto",
+ "effectiveProposer": "local",
+ "corpusVersion": "pir-conformance-corpus/2026-08-19",
+ "corpusHash": "sha256:fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9",
+ "baselineScore": "0.7",
+ "candidateScore": "0.7703",
+ "heldOutDeltas": [
+ "0.021",
+ "0.137",
+ "0.048",
+ "0.092",
+ "0.006",
+ "0.113",
+ "0.034",
+ "0.159",
+ "0.017",
+ "0.071",
+ "0.128",
+ "0.055",
+ "0.083",
+ "-0.012",
+ "0.101",
+ "0.029",
+ "0.146",
+ "0.064",
+ "0.038",
+ "0.076"
+ ],
+ "pairedOutcomes": [
+ {
+ "taskId": "task-01",
+ "baselineScore": "0.7",
+ "candidateScore": "0.721"
+ },
+ {
+ "taskId": "task-02",
+ "baselineScore": "0.7",
+ "candidateScore": "0.837"
+ },
+ {
+ "taskId": "task-03",
+ "baselineScore": "0.7",
+ "candidateScore": "0.748"
+ },
+ {
+ "taskId": "task-04",
+ "baselineScore": "0.7",
+ "candidateScore": "0.792"
+ },
+ {
+ "taskId": "task-05",
+ "baselineScore": "0.7",
+ "candidateScore": "0.706"
+ },
+ {
+ "taskId": "task-06",
+ "baselineScore": "0.7",
+ "candidateScore": "0.813"
+ },
+ {
+ "taskId": "task-07",
+ "baselineScore": "0.7",
+ "candidateScore": "0.734"
+ },
+ {
+ "taskId": "task-08",
+ "baselineScore": "0.7",
+ "candidateScore": "0.859"
+ },
+ {
+ "taskId": "task-09",
+ "baselineScore": "0.7",
+ "candidateScore": "0.717"
+ },
+ {
+ "taskId": "task-10",
+ "baselineScore": "0.7",
+ "candidateScore": "0.771"
+ },
+ {
+ "taskId": "task-11",
+ "baselineScore": "0.7",
+ "candidateScore": "0.828"
+ },
+ {
+ "taskId": "task-12",
+ "baselineScore": "0.7",
+ "candidateScore": "0.755"
+ },
+ {
+ "taskId": "task-13",
+ "baselineScore": "0.7",
+ "candidateScore": "0.783"
+ },
+ {
+ "taskId": "task-14",
+ "baselineScore": "0.7",
+ "candidateScore": "0.688"
+ },
+ {
+ "taskId": "task-15",
+ "baselineScore": "0.7",
+ "candidateScore": "0.801"
+ },
+ {
+ "taskId": "task-16",
+ "baselineScore": "0.7",
+ "candidateScore": "0.729"
+ },
+ {
+ "taskId": "task-17",
+ "baselineScore": "0.7",
+ "candidateScore": "0.846"
+ },
+ {
+ "taskId": "task-18",
+ "baselineScore": "0.7",
+ "candidateScore": "0.764"
+ },
+ {
+ "taskId": "task-19",
+ "baselineScore": "0.7",
+ "candidateScore": "0.738"
+ },
+ {
+ "taskId": "task-20",
+ "baselineScore": "0.7",
+ "candidateScore": "0.776"
+ }
+ ],
+ "statistics": {
+ "ruleVersion": "ruflo.flywheel-gate/v1",
+ "relativeLift": "0.100428571429",
+ "pairedBootstrapProbability": "1",
+ "pairedBootstrapDeltaCILow95": "0.0489",
+ "frozenAnchorRegression": "0",
+ "iterations": 10000,
+ "seedHex": "167c9185d76163dfa69ae57c11af813669a6353abcb49d7af673acf918f3a7c3",
+ "significant": true,
+ "accepted": true
+ },
+ "gates": {
+ "heldOutImproves": true,
+ "frozenAnchorNoRegression": true,
+ "driftWithinBound": true,
+ "replayDeterministic": true,
+ "receiptCoverage": true,
+ "canaryNoWorse": true
+ },
+ "resourceEvidence": {
+ "p95LatencyMicros": 412000,
+ "costMicrosPerTask": 1850,
+ "tokensPerTask": 3120,
+ "failureRate": "0",
+ "evaluationCostMicros": 29600,
+ "currency": "USD"
+ },
+ "evidence": {
+ "corpusRoles": {
+ "selectionTaskIds": [
+ "sel-01",
+ "sel-02",
+ "sel-03"
+ ],
+ "promotionHoldoutTaskIds": [
+ "task-01",
+ "task-02",
+ "task-03",
+ "task-04",
+ "task-05",
+ "task-06",
+ "task-07",
+ "task-08",
+ "task-09",
+ "task-10",
+ "task-11",
+ "task-12",
+ "task-13",
+ "task-14",
+ "task-15",
+ "task-16",
+ "task-17",
+ "task-18",
+ "task-19",
+ "task-20"
+ ],
+ "guardTaskIds": [
+ "anchor-01",
+ "anchor-02"
+ ]
+ },
+ "verification": {
+ "replayTranscriptRef": "sha256:1b16b1df538ba12dc3f97edbb85caa7050d46c148134290feba80f8236c83db9"
+ },
+ "canary": {
+ "rollbackRate": "0",
+ "sliceRef": "sha256:0263829989b6fd954f72baaf2fc64bc2e2f01d692d4de72986ea808f6e99813f"
+ }
+ },
+ "termVerification": [
+ {
+ "term": "heldOutImproves",
+ "verification": "recomputed",
+ "evidenceRef": "inline:pairedOutcomes"
+ },
+ {
+ "term": "frozenAnchorNoRegression",
+ "verification": "recomputed",
+ "evidenceRef": "inline:statistics.frozenAnchorRegression"
+ },
+ {
+ "term": "driftWithinBound",
+ "verification": "recomputed",
+ "evidenceRef": "inline:evidence.verification"
+ },
+ {
+ "term": "replayDeterministic",
+ "verification": "recomputed",
+ "evidenceRef": "sha256:1b16b1df538ba12dc3f97edbb85caa7050d46c148134290feba80f8236c83db9"
+ },
+ {
+ "term": "receiptCoverage",
+ "verification": "recomputed",
+ "evidenceRef": "inline:evidence.corpusRoles"
+ },
+ {
+ "term": "canaryNoWorse",
+ "verification": "signature-verified",
+ "evidenceRef": "sha256:0263829989b6fd954f72baaf2fc64bc2e2f01d692d4de72986ea808f6e99813f",
+ "attestor": "ruflo-canary-runner/v1"
+ }
+ ],
+ "decision": "accepted",
+ "issuedAt": "2026-08-19T00:00:00.000Z",
+ "expiresAt": "2026-08-20T00:00:00.000Z",
+ "receiptId": "sha256:013a3ab18ec9ddec4cb0a2544bdd1bb9189b3859a9f919ce1d7dcbc6b1b7b913"
+ },
+ "signature": {
+ "algorithm": "ed25519",
+ "domain": "ruflo/flywheel-receipt/v1",
+ "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAqNSpk4jp2Y7WJ3jzCgOiXnVFKQKm5R7266xFiPWUU0s=\n-----END PUBLIC KEY-----\n",
+ "signatureBase64": "LWwGMjiZtZbt5mEB4MGl4HAWfxGO5j4H/n19gLJ9dswmjCdmkIJaPD0Xnp6tfeAPuvcxMALx16Wx80MKQdMlBw=="
+ }
+}
diff --git a/v3/docs/spec/witness-receipt-contract.md b/v3/docs/spec/witness-receipt-contract.md
index aa226880a9..8a8007f72f 100644
--- a/v3/docs/spec/witness-receipt-contract.md
+++ b/v3/docs/spec/witness-receipt-contract.md
@@ -150,19 +150,35 @@ Seed (ADR-322C): `SHA-256("ruflo/bootstrap/v1" || corpusHash || candidateId ||
baselineRef || evaluationRunId)`, concatenated with no separator. The full digest
hex is recorded as `seedHex`.
-**The ADR does not specify the PRNG driven by that seed, but recomputation is
-impossible without it.** Transcribed from `flywheel-receipt.ts:212-293` and
-normative for any independent verifier:
+The PRNG driven by that seed, the resampling procedure, and the decimal encoding
+of the results are now normative in **ADR-322C §Update (2026-08-19)** — added by
+ruflo#3069, which this spec's first draft raised. Consult that section as the
+authority; in summary:
- PRNG state = first 4 bytes of the seed digest, big-endian uint32.
- Step: `state = (1664525 * state + 1013904223) mod 2^32`; draw = `state / 2^32`.
-- 10,000 resamples by default; each draws `n` indices as `floor(draw * n)` and
- averages the corresponding `heldOutDeltas`.
+- 10,000 resamples by default; each draws `n` indices as `floor(draw * n)`, in
+ sequence, and averages the corresponding `heldOutDeltas`.
- `pairedBootstrapProbability` = fraction of resample means strictly `> 0`.
- `pairedBootstrapDeltaCILow95` = the `floor(0.025 * iterations)`-th order
statistic (0-based) of the resample means.
-
-Filed as gap G1 in §7: this belongs in ADR-322C, not only in source.
+- Results are encoded at scale 12 with trailing zeros stripped.
+
+**Test your implementation against
+[`examples/receipt-bootstrap-reference.example.json`](./examples/receipt-bootstrap-reference.example.json),
+not the accepted-receipt example.** Only the former has heterogeneous per-task
+deltas. The latter's deltas take two distinct values, which makes its 2.5th
+percentile identical under a wrong seed slice, a wrong byte order, or entirely
+different LCG constants — it would pass a non-conforming verifier.
+[`conformance/recompute_reference.py`](./conformance/recompute_reference.py) is a
+runnable oracle written from the ADR prose alone; it reproduces that fixture
+exactly and is the demonstration that the spec is sufficient to reimplement from.
+
+**Caveat consumers will hit:** a producer must compute the statistics from the
+*encoded* scores, since that is all a verifier has. `createFlywheelReceipt`
+currently computes from full-precision means while storing scale-12 strings, so a
+receipt whose mean needs more than twelve decimals fails ruflo's own verifier with
+`statistical decision does not recompute`. Gap G5 in §7.
### 6.2 Sequential evidence (ADR-381)
@@ -185,10 +201,11 @@ bound must quote the per-epoch qualifier and the `Proposed` status together.
| # | Gap | Consumer impact |
|---|---|---|
-| G1 | Bootstrap PRNG algorithm is in source only (§6.1) | Blocking for independent recomputation; consumers must transcribe §6.1 |
+| G1 | ~~Bootstrap PRNG algorithm is in source only~~ — **closed** by ADR-322C §Update (2026-08-19) (ruflo#3069) | Resolved; recompute from the ADR, verify against the reference fixture |
| G2 | ADR-322C §Ledger specifies content-addressed segments with `segmentMerkleRoot` and a **signed** head under `ruflo/flywheel-ledger-head/v1`. `main` implements a flat `commits[]` array in one state file with an **unsigned** SHA-256 chain (`flywheel-transaction.ts:553-568,619-636`) | A ledger head cannot currently be signature-verified across a repo boundary; anchor the **receipt**, whose signature is implemented |
| G3 | No unknown-field whitelist in `verifyFlywheelReceipt` (§2.4) | Consumers must enforce it via `schemas/` |
| G4 | ADR-322C §Flywheel projection (external receipt export) is deliberately disabled (ADR-322 §Current inventory) | Do not assume an upstream `@metaharness/flywheel` round-trip is available |
+| G5 | `createFlywheelReceipt` computes statistics from full-precision means but stores scale-12 strings, so a receipt whose mean needs >12 decimals fails ruflo's own verifier (§6.1) | A legitimately produced receipt can be unverifiable. Compute from the encoded values; treat a `statistical decision does not recompute` error on a receipt you trust as this defect, not tampering |
Per ADR-322 §"Phased rollout", phases 0–2 are implemented; phases 3–4 (signed
`SafetyEnvelope`, `toolPolicy`/`modelPolicy` evolution, unattended promotion) are