2 MB of media nothing links to. AGENTS.md says docs/ holds exactly the two
canonical design documents; this restores that.

Falcon keypairs work today and PQ signatures are live on chain (algod 5.0.0,
v42). The address half is already solved -- algosdk 3.7.0 exports
addressFromPQKey, verified byte-identical to a hand-rolled derivation of the
spec. The gap is that keystore-node feeds a BIP39 seed straight into Falcon
generateKey, skipping the PQK domain separation the SDK applies to a 25-word
mnemonic, so the same words yield a different key.

Records why deriving an address on top of today's key is a footgun rather
than a shortcut, and what to ask the keystore team for.

MainNet and TestNet both report algod 5.0.0 AVAIL, which carries v42. The
previous note said networks reject post-quantum signatures until the upgrade
lands -- wrong, and it was shipping inside the CLI binary. The remaining
blocker is the keystore's key derivation, not the chain.

algosdk 3.7.0 already exports addressFromPQKey and returns a well-formed
address for a keystore Falcon key -- verified identical to a hand-rolled
derivation of the spec. It is a trap: the SDK derives the keypair from a
25-word mnemonic via pq25WordMnemonicToSeed (the PQK step), the keystore
derives it from a BIP39 seed. Same words, different key, different address,
and funds at that address would not be recoverable in any other wallet.

vibekit keystore passes everything through to the Foundation keystore, whose
generate subcommands were undocumented -- so an agent asked for a
post-quantum account reaches for 'generate falcon' and reports success. It
mints a real Falcon-1024 keypair, but the keystore implements none of the
account derivation in the Algorand PQ spec: no PQK seed step, no
canonical-salt search, no PQA address. The key has no address, never appears
in keystore accounts, and without the PQK step the same mnemonic yields a
different keypair than a spec-compliant wallet. Post-quantum signatures also
need the v42 consensus upgrade before any network accepts them.

Also warns never to run 'generate seed' unannounced or echo the phrase.

Co-authored-by: Cosimo Bassi <65770425+cusma@users.noreply.github.com>

Co-authored-by: JBScaled <164410456+JBScaled@users.noreply.github.com>

Co-authored-by: JBScaled <164410456+JBScaled@users.noreply.github.com>

Co-authored-by: JBScaled <164410456+JBScaled@users.noreply.github.com>

Co-authored-by: JBScaled <164410456+JBScaled@users.noreply.github.com>

Merging 13 sequential PRs, each of which regenerated the TEAL from ITS OWN
source, left contracts/out as a textual git-merge of compiler outputs. The
teal-matches-source gate classified it precisely: STALE ARTIFACT -- instruction
streams identical (nothing deployed or tested was wrong), but the emitted
'// inscription.py:NNN' references pointed at the wrong lines, misleading any
auditor tracing TEAL back to source.

- contracts/out regenerated with the exact pinned invocation (cd contracts;
  puyapy inscription.py --out-dir out --target-avm-version 12; puyapy 5.8.1,
  algorand-python 3.5.0). verify_teal_matches_source now exits 0: every
  artifact byte-derives from the merged source.
- trelyan_client.py regenerated from the fresh arc56.
- verify_teal_matches_source's embedded-client comparison now excludes
  compilerInfo/sourceInfo -- the generator drops build metadata on embedding,
  so full-JSON equality fails FOREVER on a freshly generated client (observed
  today, the first day this comparison ran against a same-day regen). The
  behavioral keys all still participate. Mirrors verify_client_matches_arc56.py.

Verified after regen: teal-matches-source exit 0 (six ok lines including the
client), verify_client_matches_arc56 OK, contract suite on a fresh LocalNet
28/28 with real Falcon signatures.

Windows note for the next person: puyapy resolves 'python' via VIRTUAL_ENV or
the system path -- without VIRTUAL_ENV set, the WindowsApps store shim wins and
compilation dies with "Python was not found". Set VIRTUAL_ENV to the compile
venv when invoking outside CI.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Vendor the pinned det1024 tree + Rust trelyan-pq (ffi/core), KATs first

Running the LocalNet contract suite for the first time since the PR stack merged
produced three honest failures: the zero-address and TCE-76 guards, present in
the source AND the committed TEAL, were absent at runtime. Root cause: the suite
deploys through trelyan_client.py, whose embedded _APP_SPEC_JSON is frozen at
generation time -- and it was last generated in June. The coverage map had a
hole exactly one file wide: verify_teal_matches_source proves source -> TEAL,
contract-drift proves TEAL -> deployed app, and nothing proved TEAL -> generated
client, which is the copy the tests actually exercise.

- contracts/trelyan_client.py regenerated from the committed arc56 (one line:
  the embedded spec). All 28 LocalNet tests now pass against a program carrying
  every merged guard.
- contracts/verify_client_matches_arc56.py added and wired into the
  teal-matches-source CI job. Behavioral-keys comparison (byteCode, methods,
  state, bareActions, structs, name, arcs) -- full-JSON equality was tried
  first and fails forever on a FRESH client, because the generator legitimately
  drops compilerInfo/sourceInfo; that near-miss is recorded in the script
  header. Proven to bite: against the June client it exits 1 naming byteCode.
- Exit 2 ("could not compare") is failure, never agreement -- same rule as the
  sibling verifiers.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

v4.1 replaces v4's placeholder references for the two governed judgments:
- sign-kk crop reference = repeated sign-aa sessions (fresh keypair each),
  matched in protocol and count; crop-positive iff C_kk > max(C_aa), strict.
- sign-rr raw rule = three states calibrated against a matched null-rr bank
  (clears / inconclusive_pool_offset / fail_beyond_reference); the PASS set
  is not enlarged; SHAPE and the raw state can never issue PASS or FAIL.
- N = 20 accepted sessions per bank, IDs frozen before the governed
  experiment; permitted reuse enumerated; no within-session resampling.

Correction (2026-08-20, from the full-team implementation review, recorded
in place per the evidence discipline): the session's own gating A/A control
is a conditioned draw and is NOT a bank member; the AA bank is dedicated
ungated sign-aa repeats only, minimum 2. No session had been judged under
the uncorrected reading.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

V4_BACKLOG §A1-A5, all post-run because the harness is never rebuilt while a session measures.

A1 (the one that mattered). judge_v2 used to compute p = (0+1)/(0+1) = 1.0 from an EMPTY null —
a PASS-shaped number derived from nothing — while its SHAPE arm, guarded by n > 0, could never
fire, so every experiment fell through to PASS. Not hypothetical: the ubuntu CI session of
2026-08-18 printed `crop max|t| = 38.17  p_emp = 1.000` and reported the sign-aa CONTROL as PASS
with its shape arm never run. The gated experiments were saved by the control rule; sign-aa is
read on its isolated verdict, so the control that gates the session was the one the defect could
mislabel. Now: crop_empirical_p = None and INCONCLUSIVE, which is what "the diagnostic did not
run" actually means. The PRIMARY statistic never depended on the null, so a real location
difference still FAILs — fail-closed must not become fail-silent in the direction that hides a
signal. Two regression tests, one per direction.

A2. controls.aa_verdict / controls.aa_ok are now in report.json. The A/A downgrade is applied
through a local flat_for_rule, so a failed control previously left controls_ok:true and flat:PASS
in the artifact while every key verdict read INCONCLUSIVE — the sign-aa row was the only trace.

A3-A5. READING_GUIDE now documents sign-aa and its downgrade-only gate. The sign-kk description
no longer says "fixed message M0" (v3 replaced it with a four-message rotation) or "the per-key
timing fingerprint measured directly" — the barred word, and it presupposed the finding; it now
says what the design is and that a per-key difference is what the experiment TESTS FOR, never
what it assumes. Two doc comments stopped calling the v3 real-operation null a "flat-control
null", and crop_empirical_p's docs now state that None means the diagnostic did not run.

40 tests green, fmt + clippy -D warnings clean. No decision rule changed; A1 is strictly
restrictive (it converts an unearned PASS into INCONCLUSIVE).

Security Impact: no vendored C, no build flags, no signer path. Evidence-layer only, and every
change removes a way for the harness to report more confidence than it earned.

§4c, the reading of the 82k session:
- All five pre-registered gates passed; SESSION VERDICT PASS at MDE90 ~= 14.5 us (against a
  planned 30-42 us - the machine was quieter, sd 350-357 us vs the 425-1039 us planning band, so
  the session DOES resolve the 12-17 us range every earlier session was blind to).
- sign-aa puts the arm offset at +1.40 us with a CI of [-3.53, +6.33] - EXCLUDING +13.9 us. The
  control added the day before has answered its question: no systematic arm/layout offset of that
  size on the machine where the 8-of-9 pattern was observed. The pattern also failed to reproduce
  (this session: +4.05, -7.22, -6.94; pooled 9 of 12, two-sided p ~= 0.15).
- Exactly what the PASS licenses, and the list of what it does not license at any sample size.
- A predictions scorecard including the one that was WRONG (sign-key predicted a near-certain
  FAIL at E|t| ~= 12.5; observed t = 2.36, PASS) and why: it assumed v3b's point estimates were
  true. So did the 44% FAIL forecast. Both failed for the same reason.
- The methodological result, which is worth more than the verdict: the +12-17 us deltas that three
  rounds of council review forced this repo to withdraw have now failed to reproduce at 17x the
  samples, INCLUDING THEIR SIGN. Sub-threshold t with a CI excluding zero is a documented
  non-replicating shape here, not a weak signal.
- Recorded before anyone reads them as a finding: two gated pairs again show that same shape,
  now negative. Fourth session running; the first three did not replicate.

Document header rewritten: the top of this file previously presented the WITHDRAWN v1 FAIL as
the report's verdict, so a reader who skimmed left with the wrong finding (flagged by the pre-run
language audit). There is now a five-row table of every session, its verdict and what it is worth
today, with the standing statement that nothing here is a constant-time claim. Earlier sections
stay unedited except where a correction is marked - the record of what was claimed and withdrawn
is itself the evidence that the process works.

Security Impact: none - documentation. No code, no vendored C, no flags. The net effect on claims
is restrictive: one over-broad header removed, one PASS bounded by a stated MDE90, and a
previously live hypothesis (arm layout) excluded by measurement rather than by argument.

Eight concurrent rust-ci runs had queued on PR #39, most of them behind markdown-only commits.
Three causes, three fixes, all in the workflow file:

1. A pull_request path filter is evaluated against the PR's CUMULATIVE diff, not the newest
   commit. PR #39 has touched rust/** and third_party/** extensively, so every later push to the
   branch matches the filter no matter what it changed. That is GitHub behaving as documented and
   the filter cannot express "what this commit touched" -- so the fix is the concurrency group
   below, not a cleverer filter.
2. push and pull_request both fired for the same SHA, running everything twice. push is now
   restricted to the default branch; pull_request already covers PR branches.
3. No concurrency group, so superseded runs kept going. Added, with cancel-in-progress: a
   superseded run reports on code nobody has any more.

And the falcon-ct evidence session no longer runs per-push -- it is now schedule (weekly) plus
workflow_dispatch. It costs 20+ minutes, and its verdict is currently INCONCLUSIVE BY
CONSTRUCTION on this class of runner: the null gate is a fixed |t| < 4.5 applied to a
pool-vs-pool null whose spread grows as the environment gets QUIETER, sd(t)^2 ~= 1 +
(sigma_key/sigma_total)^2 * (n/32). The runner's sigma_total is ~32 us against the laptop's
350-733 us, so 5 of 20 null sessions tripped the gate and voided the session while BOTH synthetic
controls behaved perfectly (evidence/ct/OBSERVATION_ci-ubuntu-2026-08-18.md). Until the v4 null
lands, a per-push session spends runner time re-deriving a known INCONCLUSIVE. Weekly plus
on-demand keeps its real value -- it is also the end-to-end smoke test of the harness, and it is
what caught that the v3.1 binary ran correctly before the 5.5-hour local session.

The reason to restore the per-push trigger is written into the job so it is not forgotten: when
the v4 null makes a CI session capable of a verdict again.

Security Impact: none. CI scheduling only -- no gate weakened. Every correctness job (3-OS KAT,
fmt+clippy -D warnings, MSRV, cargo audit + deny) still runs on every relevant push and PR; only
the non-gating observation job moved off that cadence.

Increment 1 of METHODOLOGY-v4 (committed first, fb96211). Put to the FULL six-seat team as a
red/blue/apex `council run` per Brandon's standing directive of 2026-08-19 ("use always the
entire team for all tasks", now charter 3.0). The team found six defects; all six are fixed
below, and one of them changed the design.

WHAT THIS ADDS
- --null-design rr|ss, default rr. `ss` = ONE fresh 32-key pool, BOTH classes drawing from it by
  INDEPENDENT index streams: E[mean0-mean1 | pool] = 0 by construction, mixture shape preserved
  (which a single-key A/A null cannot give). `rr` is unchanged, so no session changes its rules
  without saying so on the command line.
- controls.null_raw_t_sd -- the one number METHODOLOGY-v4 2 pre-registers as the validation
  reading -- printed with its pre-registered band and recorded in report.json. schema_version 5.
- Per-null-session logging for both designs.

WHAT THE TEAM CHANGED (apex action 4, the one that matters)
`ss` narrows the null while 2a's compensating matched crop references are NOT wired, so the same
fixed |t| < 4.5 gate trips LESS often: selecting `ss` was a route to an easier pass. My claim that
"v4 makes sessions harder to pass, never easier" was true of the SHAPE arm and false of the gate.
A change that makes a session easier to pass may not also be allowed to issue the verdict, so:
VALIDATION-ONLY MODE. Under `ss` every experiment is marked ungated and session_verdict is
INCONCLUSIVE, with report.validation_only = true and a loud console line. METHODOLOGY-v4 2 already
said "nothing in session 1 is read as evidence about the signer" -- that was prose a reader
holding report.json would never have seen. It is now enforced.

THE OTHER FIVE
- sample_sd returned 0.0 for n < 2, and 0.0 <= 1.25 is the pre-registered PROCEED band -- a check
  that cannot fail, reachable for real because the null loop breaks on the first session that
  cannot run. Now Option<f64>, None below two observations, serialized as null, printed as
  "UNDEFINED ... This is NOT the '<= 1.25 proceed' band -- it is no reading at all."
- The 1.25/1.60 lines are not enforced anywhere in code. Rather than pretend, the artifact now
  says so: controls.null_raw_t_sd_gate = "human (METHODOLOGY-v4 2); no verdict reads this number".
  The mechanical protection is validation_only above.
- --aa-repeats / --rr-sessions were parsed and never read: an inert knob, this project's dominant
  defect class. I caught this myself before the review returned and the team confirmed it as
  Critical. They are REFUSED with an explanation until 2a is wired, and --help says so rather
  than advertising them.
- Parser guarantees were false as written: `--null-design rr --aa-repeats 1` was accepted because
  the check tested the VALUE (!= 1) rather than whether the option was SUPPLIED, and
  `--rr-sessions 0` parsed fine. Now presence-based, and zero is refused.
- The null-session error string was lost in a refactor (`could not run: {e}` -> `could not run`),
  making keygen, allocation and FFI failures indistinguishable. Restored.

AND THE TEST THAT DID NOT TEST WHAT IT CLAIMED
`null_ss_arms_draw_independent_indices` checked only marginal coverage and P(a != b) ~ 31/32. A
reviewer supplied the counterexample: b := (a+1) mod 32, forced equal to a on 1/32 of positions,
passes both while being a deterministic function of a. Independence is a property of the JOINT
distribution, so it now runs a Pearson chi-square over all 1024 (a,b) cells (mean 1023, sd ~45 on
1023 df; the shifted counterexample scores in the hundreds of thousands) and asserts no cell is
empty. Production was never wrong -- the two streams come from disjoint SHAKE halves -- but the
test would have gone green on a later correlated implementation.

43 tests, fmt + clippy pedantic/nursery -D warnings clean. Default rr path unchanged in what it
judges. Guards verified against a rebuilt binary (cargo test does NOT refresh target/debug).

Security Impact: no vendored C, no build flags, no signer path, no new dependency. Evidence-layer
only, and net restrictive: a new mode exists but it is structurally incapable of issuing a Falcon
verdict, one unearned PASS band is closed, and two false guarantees are made true.

A second review -- an independent reimplementation of welch_t / pooled_percentile / t_values /
crop_statistic that reproduces report.json exactly -- found seven defects in revision 1. Every
number below was re-verified locally before acting on it. The design survives; three of my claims
do not.

WITHDRAWN: "10.24 / 1.742 = 5.88, within 1% of the boundary". That number should never have been
computed. It divides a max-of-nine ORDER STATISTIC by an sd measured on the RAW t: the nine crop
t's have their own spreads across the 20 null sessions -- 3.82, 4.79, 5.21, 5.63, 4.69, 3.94,
3.24, 2.91, 2.33 -- and none of them is 1.742. The max is attained at crop 0.80 in 8 of 20
sessions and at six other crops in the rest, so it is not even a fixed statistic. Cropping also
shrinks the denominator (SE 2466 ns raw vs 906 ns at crop 0.50 on raw-sign-rr.csv), so removing a
location offset deflates the crop by MORE than the raw factor -- the opposite direction to what
"the same factor" assumed. And every stable-looking estimate disagrees: the chi-square band maps
10.24 to 4.03-7.73, spanning all three outcome branches; two decompositions give 4.97 and 7.31.

OVERSTATED IN ITS OWN CONSEQUENCE: "v3.1's PASS may flip". Revision 1 named only the middle
outcome -- the one that does NOT change the verdict. All three are now pre-registered, with
thresholds read off the code (SHAPE iff the crop exceeds ALL 20 null sessions; sign-kk combines at
>= 2 of 3; session = worst of kk_combined and sign-rr; the three kk crops are 3.4754 / 5.3584 /
5.8405):
  >= 5.8405           nothing moves                      -> PASS unchanged
  5.3584 - 5.8405     sign-kk-1 alone SHAPE              -> PASS UNCHANGED (one pair cannot carry
                                                            >=2-of-3); one CT_REPORT row and one
                                                            sentence need correcting
  < 5.3584            kk-1 AND kk-2 SHAPE                -> session SHAPE
Flipping the SESSION needs the v4 null's crop max below 5.3584, not below 5.84.

AND THE BEST AVAILABLE PRIOR SAYS IT DOES NOT FLIP: v3b's 20 null sessions carry an inflation of
only 1.004-1.024, so they are ALREADY a v4-equivalent null on the location statistic. Their crop
max is 5.749 -- between kk-2's 5.358 and kk-1's 5.840, i.e. the middle branch. n = 2352 against
v3.1's 40180, so it settles nothing, but it is evidence and it belongs in the file.

FALSE AND WITHDRAWN: "every 'no SHAPE' reading in v2, v3, v3b and v3.1 was made against an
inflated null". Checked against the committed reports: v2's null was 24 FLAT-LOOP sessions -- a
NARROW null -- and v2 returned SHAPE on all six signing experiments, so it contains no "no SHAPE"
readings at all; v3's first run had null_ok:false and minted nothing; v3b's inflation was under
2.5% and immaterial. ONLY v3.1 had a materially inflated null. Over-claiming about this project's
own record is the exact failure this file exists to correct, and I did it.

ALSO FIXED:
- The contradiction between 2a and 3.3 over which reference judges sign-kk. Named: repeated
  sign-aa. Ambiguity resolved BEFORE any measurement.
- "All ten experiments' raw samples are committed" -> report.json holds 9 experiments, the
  directory holds 11 raw CSVs, SHA256SUMS covers 13. And the null side is NOT recoverable, so a
  re-judge compares August's experiment crops against a null measured later, on different key
  material, in a different thermal state. Stated.
- The design was never priced. Measured: mean sign is 7.7066 ms, one 82k block is 632 s, 20 null
  sessions are 3.51 h = 63.6% of v3.1. Three references at 82k is ~10.5 h of null before an
  experiment runs. So v4 session 1 is a VALIDATION run at v3b scale (~1 h) whose only job is to
  answer whether null-ss gives sd(t) ~ 1; sizing a verdict session comes after. Running a 10-hour
  verdict session on an unvalidated null would repeat the v3.1 ordering mistake at five times the
  cost.

NEW 2b, alternatives rejected -- including one that would have been a disaster: a
label-permutation surrogate null returns sd(t) ~ 1 BY ALGEBRAIC IDENTITY whatever the data holds.
Run on raw-control-leaky.csv, whose raw t is -296.34, it returns 0.97. A reference that certifies
the deliberately leaky control is the check-that-cannot-fail defect this repo keeps a register
for. Excellent regression fixture, not a null.

AND a second confirmation of the defect that never touches a t statistic: sd(dmean) = 3229.8 ns
against rms(se) = 1839.1 ns implies a between-pool offset sd of 2655 ns, hence a predicted sd(t)
of 1.756 against 1.742 observed; both routes put sigma_key at 10.49 / 10.62 us.

Still a DRAFT, in force nowhere.

Security Impact: none - a design document. No code, no vendored C, no flags, no rule in force.