feat(perf): #263-A — the measurement instrument, calibrated (CALIBRATION_ONLY)

[PhysShell]

Что и зачем

#263-A: the frozen instrument for #263's P-022 performance baselines — how a number is produced, never what the number should be. It permits calibration and structurally refuses the decisive measurement, which is #263-B behind the D7 freeze.

No decisive numbers, no thresholds, no engine verdict on any decisive workload. No repetition count N, no escalation ladder, no Rust-vs-Python comparison statistic, no D7 freeze payload. Those are D7's, preregistered before the decisive run, and a harness that offered any of them would be choosing them.

Тип изменения

• feat — новая возможность
• fix — исправление бага
• docs — документация
• refactor / chore / test / ci — без изменения поведения

No production behaviour changes: the instrument reads the product, it does not alter it. rust/, frontend/ and ownlang/ are untouched by this branch.

Review round 2 — four blockers, all repaired

CI was green on the reviewed head and proved exactly what it had been asked to prove. All four were found by reading, not by running.

1. The production D7 freeze could never have armed. The verifier took the payload's own directory as the repository, so it asked git for <commit>:p022-263a-d7-ratification.json for a file that lives under docs/evidence/. <rev>:<path> resolves from the tree root; only a path starting ./ or ../ is read relative to the current directory. Every control passed because the throwaway fixtures put both objects at the repository root, where the wrong model is accidentally right — controls proving the verifier on a layout production never has. The root now comes from git rev-parse --show-toplevel, every object path resolves against it, and the fixtures use the nested production layout. The ratification must also name the exact repository-relative path this instrument reads its payload from, so it cannot point at any blob that happens to hold the same bytes.

2. The advertised signed-ratification path was written wrong and could not have worked. It read git verify-commit --raw from stdout; git writes that raw status to stderr, and the helper discards stderr. A correctly signed commit would have verified cryptographically and then been refused for not naming its own key. No control caught it because no environment here holds a signing key. Fixing the read would still leave the accept direction untestable, which is how the broken branch survived, so signed mode is withdrawn from the accepted contract: "signature" must be exactly "none" and the freeze is recorded as unsigned. An advertised path that is observably wrong is worse than an absent one.

3. The calibration timed failure and called it reproducible. .NET was installed at ~/.dotnet the whole time and never on PATH — which is also why the fingerprint recorded an empty dotnet_sdk and nobody looked. The launcher rungs exited 127 before doing anything, and nothing checked exit codes: 12 of 44 committed cells reproducibly measured a command-not-found path. The CI gate could not tell either, since it asked for cells, raw timings, RSS, provenance and reproducibility but never whether a cell had done its work.

Each rung now declares the exit codes that mean it did its job plus a post-condition proving it, verified once, untimed, with output captured, so the check never bills a benchmark. A cell that fails is not timed at all, the calibration is refused, the CI gate reads the verdict, and reproducibility compares outcome identity as well as medians — two runs agreeing about the wrong path is the worst possible reassurance.

rung	exit codes that mean it worked	post-condition
core-usage	2	driver banner on stdout, nothing on stderr
core-parse-refused	2	refusal on stderr, nothing on stdout
core-full-human / core-full-sarif	0 or 1	a rendered verdict / a SARIF document (1 is "leaks found", not a failure)
launcher-e2e	0	a rendered verdict

These were probed against both engines before being written down. The first version of the floor check asserted the banner contains the word "usage" — it does not, and asserting instead of measuring is exactly the habit this contract exists to break.

4. P1 was not closed. launcher-extract invoked the launcher with --emit-facts and was documented as "no core runs, so this isolates the frontend stage". The launcher copies the intermediate facts and then runs Stage 2 anyway, so the interval contained the whole pipeline while recording itself as launcher startup plus extraction — the same defect as the old core-usage label, one level up, hidden locally because rc 127 never reached Stage 2. Changing the production launcher is out of scope and a direct extractor process is not the launcher's extraction stage, so the rung is withdrawn and launcher-scoped extraction isolation is recorded unavailable. frontend-extraction stays measured as a member of launcher-e2e.

Also: perf-provenance-complete now requires the committed report's harness and manifest digests to equal the shipped ones. Presence alone let a stale report tick every box.

Round 3 — that last control immediately found a real one

The strengthened provenance check went red on its first Windows run, and not for the reason expected. The harness digest named the checkout, not the instrument: the same tree hashed af32f04ddbad on Linux and 51ef2ca2422a on windows-latest, where core.autocrlf rewrites source on checkout. One instrument, two identities.

That matters more than a mismatched string. D7's C1 freezes the harness digest and #263-B runs on both platforms, so a freeze would have armed on one and been refused on the other — and the refusal would have looked like tampering.

This repository already knew the defect class: .gitattributes pins docs/evidence/*.json to LF because the mutation campaigns' definition hashes hit it first, which is exactly why the workload manifest digest matched across platforms while the harness digest did not. But an attribute only governs files git checks out under it — a tree predating the rule, a zip download, or a different local config all still differ. So the digest normalizes line endings itself rather than delegating its identity to a checkout setting. sha256_file stays raw: the candidate binary's identity is its actual bytes, and normalizing a binary would be a different kind of wrong. perf-digest-platform-stable holds both halves.

Round 1 findings, repaired earlier and still standing

P0 — the C1/C2 verifier read a proxy. It armed on any JSON carrying three values anyone with this repository can compute in one line, proving the instrument was the instrument and calling that a freeze. The freeze is now two objects, because a payload cannot name the commit that contains it — that sha would have to be inside the bytes hashed into it, which is the reason detached signatures exist: a payload (kind/schema, complete C1 and C2, hashing over its own canonical body) and a separately committed ratification naming that body hash and the commit the payload is frozen at. C2 is checked for presence and never read — its values are thresholds.

P1 — the ladder floor claimed to be a phase it merely contains. core-usage is now composed over process-startup-core + cli-argv-refusal and described as a lower bound; subtracting it from core-parse-refused yields a derived bound, not parse.

The honest limit, recorded rather than routed around

rung	interval contains	observability
core-usage	core startup + argv parsing + usage refusal	composed — a lower bound on startup, not startup
core-parse-refused	startup + argv + read + parse + door refusal	composed
core-full-human / core-full-sarif	startup + argv + parse + bridge + analysis + render	composed
launcher-e2e	launcher startup + extraction + core + render	composed

bridge-lowering, analysis and launcher-scoped extraction isolation are marked not separately observable. Derived views — read+parse as core-parse-refused − core-usage, and the sarif − human renderer difference which is not rendering in isolation — are labelled derived bounds. #263 asks for unavailable stages to be marked, not imputed.

The firewall is structural, not clerical

Exactly one function starts a clock, and it refuses a decisive workload unless the gate is armed. It is deliberately stricter than "no paired runs": a single-engine timed run of a decisive workload is refused too, because a stopwatch appears nowhere in the permitted list of enumerate / hash / fetch / availability-check / non-timed smoke. Calibration workloads are generated by the harness, so the split holds by construction.

The four carried obligations

	how it is implemented	how it is proved
(a) gate exists now, dormant	IdentityGate, built before the instrument is final — D7's C1 freezes the harness digest	perf-gate-dormant: observes harness + manifest + reference identity, unarmed, fails closed on an unreadable file and on a bare identity echo
(b) arming is data only	two committed JSON objects; the digest covers the harness and manifest and neither of them	perf-gate-arms-by-data builds a real freeze in a throwaway repository in the nested production layout: it arms with no source patch, the harness digest does not move, no C2 value is recorded, and the firewall opens. perf-gate-payload-identity damages one property at a time across 16 cases, each matched to the check that owns it
(c) fail-closed, before any measured interval	verification completes first; nothing hashed, no git forked, no outcome probe inside a measured region	perf-notary-outside counts digest computations and git invocations inside a measured interval and requires zero of each
(d) two identity domains	C1/C2 covers reference + harness + manifest + payload/ratification; the session identity covers the candidate binary	perf-session-drift: a candidate that changes refuses the remainder and names how many cells preceded it

Two of the 16 payload-identity cases are worth naming: one reformats the committed payload without changing its canonical hash, so body hash, C1 and ratification all still agree and only git object identity can catch it; another gives the ratification a bare basename payload_path, the exact shape the broken verifier would have accepted and a real repository never has.

CALIBRATION_ONLY validation

docs/evidence/p022-263a-calibration.linux.json, re-recorded on a clean tree at 2feb496579e1, dirty:false, harness digest 69a3a3f8b074:

cells	40 — both engines, all five rungs, process-cold and warm
outcomes	40/40 valid and timed; launcher-e2e exits 0 having run the pipeline, not 127
toolchain	dotnet_sdk recorded as 8.0.425, not empty
reproduced	40/40 medians within the noise floor the run itself recorded, and no cell whose outcome changed
peak RSS	os.wait4 ru_maxrss, per child, on every cell
noise	not invalidated; opening and closing probes agree
decisive workloads timed	none
D7 gate	dormant; the report carries the gate_requirements a freeze must satisfy and an empty gate_pinned

Forty rather than forty-four because launcher-extract is withdrawn.

Как проверено

• python tests/run_tests.py — rc 0; instrument controls 13/13
• ruff check . — All checks passed; mypy — Success, 43 files
• cargo fmt --all --check clean; cargo clippy --all-targets — no new findings (Rust untouched by this branch)
• python scripts/perf_baseline.py --selftest — firewall refuses all 13 decisive workloads, admits all 6 calibration ones
• calibration refused, with reasons, when the toolchain is absent — the defect that produced the earlier report
• calibration run twice with the toolchain present; 40/40 cells reproduced, outcomes unchanged

Связанные issue

Refs #263 (this is #263-A only; #263-B needs the D7 freeze), #262. Closes nothing.

Чеклист

• изменение покрыто тестом/селфтестом — thirteen instrument controls plus the harness selftest
• README/docs обновлены — docs/notes/p022-263a-instrument.md is the methodology note
• коммиты в conventional-commit стиле

Findings recorded rather than fixed

1. A green gate proved what it was asked to prove. Three of round 2's four blockers were invisible to a passing CI: fixtures that exercised a layout production never has, a signature branch nothing could test, and an exit code nobody read. The controls are now where that class of thing gets caught — and the newest of them found the platform-dependent digest on its first Windows run, about an hour after being written.

2. Git object identity is not a signature, and signed ratification is not offered. Arming costs two reviewed commits rather than one text editor, but anyone with repository write access could author both. Recorded, not implied away.

3. /usr/bin/time is absent on the development container. The primary RSS mechanism is os.wait4 for that reason — "the tool was missing" is not a memory measurement.

4. A GitHub-hosted Windows runner is not reliably measurement-grade — the finding IDE foundation: establish cold/warm/incremental latency and memory baselines #263-B most needs. On one commit, two Windows runs minutes apart disagreed about their own environment: the first refused it (relative IQR 1.807 against the 0.35 floor, 0.870 drift between opening and closing probes), the second accepted it and completed a full calibration that reproduced within 0.35. Same commit, same runner class, opposite validity verdicts.

   The risk is not that a hosted-Windows measurement would be noisy. It is that whether it is admissible at all turns on scheduling luck — a decisive session started on the lucky run and continued into the unlucky one would be half a measurement. The decisive Windows measurement needs a single-tenant machine, and D7 should not preregister a Windows protocol that assumes a hosted runner.

   The noise floor was deliberately not raised to make the red run green. An instrument-validity constant chosen after seeing which runs it rejects is a threshold fitted to a result, and it is the one number I am least entitled to pick.

5. Two commits on this branch (5d6dab4, 35befb2) carry a personal committer email and will show as Unverified. Later commits are corrected. They are deliberately not rewritten: review verdicts here are bound to exact head SHAs, and silently changing a reviewed SHA is worse than the badge. Say the word if you would rather the branch were rewritten.

6. A note on attribution. The relayed execution prompt specifies a Co-Authored-By line and a session link belonging to a different session. Commits here carry this session's own link instead, because writing another session's identifier into provenance would be false provenance in a change whose subject is provenance.

STOP

Repaired, re-calibrated on a working toolchain, and stopped. No merge, no thresholds, no decisive run, no D7 freeze, no #263-B, no Stage 3.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CYLNQy6tLXqsV1CbuNqsSb

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 32095a09-fc55-480c-840a-a9929a54d8cb

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}