Skip to content

contract(trace-attn-sub-stages-v1): v1.2.0 — SUB-003 fn-name drift fix + SUB-004 BLOCKER → PARTIAL_ALGORITHM_LEVEL#1459

Merged
noahgift merged 4 commits into
mainfrom
contract/trace-attn-sub-stages-v1-2-0-fn-name-drift
May 4, 2026
Merged

contract(trace-attn-sub-stages-v1): v1.2.0 — SUB-003 fn-name drift fix + SUB-004 BLOCKER → PARTIAL_ALGORITHM_LEVEL#1459
noahgift merged 4 commits into
mainfrom
contract/trace-attn-sub-stages-v1-2-0-fn-name-drift

Conversation

@noahgift

@noahgift noahgift commented May 4, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Contract drift fix: trace-attn-sub-stages-v1.yaml v1.1.0 → v1.2.0 PROPOSED.
  • SUB-003 algorithm_evidence.function_names previously listed load_tensor_apr_aprt (does not exist). Replaced with the 3 real wired functions.
  • Contract-only YAML change, no Rust touched.

What landed

Field Before (v1.1.0) After (v1.2.0)
function_names [load_tensor_apr_aprt] [is_aprt_stage_file, compute_aprt_stage_stats, run_aprt_stage_diff]
file_paths [diff.rs] [diff_05_aprt_stage.rs, diff.rs]
invariants_enforced 1 line 3 lines (now names the 2 specific PR #1456 tests)
notes brief explicit algorithm-level evidence trail

How drift was discovered

While authoring PR #1456 (falsify_attn_sub_003_new_stages_per_stage_agnostic + falsify_attn_sub_003_cosine_detects_softmax_divergence) I went to verify the contract's claimed function_names matched the real code. grep -rn 'load_tensor_apr_aprt' crates/ returned zero matches; the real wired functions are is_aprt_stage_file (line 18), compute_aprt_stage_stats (line 41), and run_aprt_stage_diff (line 94) in crates/apr-cli/src/commands/diff_05_aprt_stage.rs.

Caught here at the cheapest layer (contract YAML, no implementation roll-back). Per feedback_no_guessing.md.

Test plan

  • pv validate contracts/trace-attn-sub-stages-v1.yaml reports 0 error(s), 0 warning(s)
  • CI green
  • Auto-merge

Five whys

  1. Why now and not in §47/§48? Drift was discovered during PR test(apr-cli): FALSIFY-ATTN-SUB-003 — apr diff --values per-stage-agnostic for attn_scores + attn_softmax #1456 but mixing contract YAML + Rust test = scope creep. Now test(apr-cli): FALSIFY-ATTN-SUB-003 — apr diff --values per-stage-agnostic for attn_scores + attn_softmax #1456 is merged so the YAML can be fixed cleanly without conflict.
  2. Why separate from PR feat(scripts): HF FP16 oracle extension — capture 4 attention sub-stages (q/k_post_rope, attn_scores, attn_softmax) #1457? PR feat(scripts): HF FP16 oracle extension — capture 4 attention sub-stages (q/k_post_rope, attn_scores, attn_softmax) #1457 is Python script extension. Mixing contract-YAML changes with Python script = coupling. This PR is contract-only.
  3. Why v1.2.0 not v1.1.1? Convention in this contract family treats algorithm_evidence corrections as MINOR (v1.0.0 → v1.1.0 was Toyota Way scope correction, also algorithm_evidence-level).
  4. Why not also flip SUB-004 BLOCKER → PARTIAL? SUB-004's algorithm-bind requires feat(scripts): HF FP16 oracle extension — capture 4 attention sub-stages (q/k_post_rope, attn_scores, attn_softmax) #1457's script on main. feat(scripts): HF FP16 oracle extension — capture 4 attention sub-stages (q/k_post_rope, attn_scores, attn_softmax) #1457 is in flight. Bumping SUB-004 status here would claim more than the codebase proves.
  5. Why is the loader genuinely per-stage-agnostic? Stage names are encoded only in OUTPUT FILENAMES, not in the APRT binary (which is just b"APRT" + layer_u32_le + dim_u32_le + f32_le_body). So is_aprt_stage_file (magic-byte check) + compute_aprt_stage_stats (operates on &[f32]) are stage-name-agnostic by construction — exactly what 0 LOC production change in PR test(apr-cli): FALSIFY-ATTN-SUB-003 — apr diff --values per-stage-agnostic for attn_scores + attn_softmax #1456 demonstrated.

Plain ship % (unchanged)

  • MODEL-1: 91% (drift fix; ship % moves at SUB-004 LIVE DISCHARGE step 7)
  • MODEL-2: 57%

🤖 Generated with Claude Code

…rift fix in SUB-003 algorithm_evidence

## Why

Contract drift discovered after PR #1456 (FALSIFY-ATTN-SUB-003 drift-prevention test) merged on main. The algorithm_evidence block named:

```yaml
function_names:
  - load_tensor_apr_aprt
```

But this function does not exist anywhere in the codebase. The actual functions wired in `crates/apr-cli/src/commands/diff_05_aprt_stage.rs` and exercised by PR #1456's tests are:
- `is_aprt_stage_file`     (magic-byte detection)
- `compute_aprt_stage_stats`  (cosine + RMS + top-K)
- `run_aprt_stage_diff`    (e2e reader + emitter)

Per `feedback_no_guessing.md`. Contract author defect that pre-existed PR #1450's merge — likely speculation from the parent contract's `apr_diff_values_compat` invariant naming convention. Caught here at the cheapest layer (contract YAML, no implementation rolled back).

## What landed

- Bumped `metadata.version` 1.1.0 → 1.2.0 with v1.2.0 changelog block describing the fix.
- Replaced `load_tensor_apr_aprt` with the 3 real wired functions in `algorithm_evidence.function_names`.
- Added `crates/apr-cli/src/commands/diff_05_aprt_stage.rs` to `algorithm_evidence.file_paths` (the actual location of the wired functions).
- Added 2 new `invariants_enforced` lines naming the 2 specific drift-prevention tests from PR #1456.
- Expanded `notes` field to make the algorithm-level evidence trail explicit (which tests, what shapes, why per-stage-agnostic by construction).

## Test plan

- [x] `pv validate contracts/trace-attn-sub-stages-v1.yaml` reports `0 error(s), 0 warning(s) — Contract is valid.`
- [ ] CI green
- [ ] Auto-merge

## Five whys

1. **Why now and not in §47/§48?** The drift was discovered while authoring PR #1456 but not fixed there because PR #1456 modified Rust code, not contract YAML — single-piece flow says don't mix. Now that #1456 is merged on main, the contract drift can be addressed cleanly without conflict against an in-flight PR.

2. **Why a separate PR rather than in PR #1457?** PR #1457 is the HF FP16 oracle script extension (Python-only). Modifying the contract there would couple two independent fixes. This PR is contract-only YAML and lands independently.

3. **Why bump to v1.2.0 rather than v1.1.1?** Convention in this contract family treats `algorithm_evidence` corrections as MINOR bumps (v1.0.0 → v1.1.0 for the Toyota Way scope correction, also algorithm_evidence-level). v1.1.1 would suggest "PATCH = no semantic change", but renaming functions in the evidence block is a semantic improvement (readers can now find the real code).

4. **Why not also bump SUB-004 from BLOCKER_FIXTURE_ABSENT to PARTIAL_ALGORITHM_LEVEL here?** SUB-004's algorithm-bind requires PR #1457 (HF FP16 oracle ext) to be on main — the script is the fixture. PR #1457 is in flight. Bumping SUB-004 status here would claim more than the codebase can prove. Keeping single-piece flow: this PR ships the SUB-003 drift fix only.

5. **Why is the loader genuinely per-stage-agnostic?** `is_aprt_stage_file` checks the 4-byte magic `b"APRT"` only; `compute_aprt_stage_stats` operates on `&[f32]` slices; `run_aprt_stage_diff` reads APRT header (4-byte magic + u32 layer + u32 dim_product) + f32 LE body. Stage names are encoded only in the OUTPUT FILENAME (e.g., `layer_0_attn_scores.aprt`), never in the binary content. So the loader is shape/value-agnostic by construction, which is why FALSIFY-ATTN-SUB-003's drift-prevention tests need 0 LOC production change.

## Net effects

- Contract `trace-attn-sub-stages-v1.yaml` v1.1.0 → v1.2.0 PROPOSED.
- SUB-003 algorithm_evidence now correctly names the wired functions.
- **MODEL-1 ship %**: unchanged at **91%** (drift fix; ship % moves at SUB-004 LIVE DISCHARGE).
- **MODEL-2 ship %**: unchanged at **57%**.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@noahgift noahgift enabled auto-merge (squash) May 4, 2026 06:36
noahgift and others added 3 commits May 4, 2026 09:03
…PARTIAL_ALGORITHM_LEVEL — fixture is now on main

Bundles the SUB-004 status promotion into the v1.2.0 PR alongside the SUB-003 function-name drift fix already authored. Both changes ship as one v1.2.0 unit because they are the two contract-level updates that follow the §47.1 cascade roadmap closing at the algorithm level.

## Why now

PR #1457 (HF FP16 oracle script extension) merged on main. The fixture previously claimed "absent" is now generated by:

```
uv run --with torch --with transformers --with safetensors --with accelerate \
    scripts/generate_qwen25_coder_fp16_stages.py \
    --output /tmp/qwen25-coder-7b-hf-fp16-stages \
    --layers 0 --with-attn-substages
```

Per `feedback_no_guessing.md`: SUB-004's status is now provable from main. Promote.

## What landed

Updated SUB-004 algorithm_evidence:
- `status`: BLOCKER_FIXTURE_ABSENT → PARTIAL_ALGORITHM_LEVEL
- `file_paths`: added the actual script + APR-side wire files
- `function_names`: replaced placeholder `run_hf_fp16_reference` with the 6 real symbols (`install_attn_substages_patch`, `traced_forward`, plus 4 SaveTensorStage variants)
- `invariants_enforced`: 1 line → 4 lines explicitly naming what each PR pinned
- `notes`: documents the FUNCTIONAL discharge prerequisites (binary rebuild + driver/CPU)

Updated metadata.description v1.2.0 changelog to bundle (1) SUB-003 drift fix + (2) SUB-004 promotion as a coherent unit.

## Five whys

1. **Why combine SUB-003 drift fix + SUB-004 promotion in v1.2.0?** Both contract-level changes follow from the same upstream cause (PRs #1455 + #1456 + #1457 landed). Splitting into v1.2.0 + v1.3.0 would force a follow-up rebase + double-review with no audit benefit.
2. **Why PARTIAL_ALGORITHM_LEVEL not FUNCTIONAL?** FUNCTIONAL requires LIVE evidence. The 9-element cosine sequence has not been produced on actual hardware yet. Promoting to FUNCTIONAL without LIVE evidence would claim more than is true.
3. **Why isn't the LIVE run inside this PR?** Per `feedback_compute_pre_authorized.md`, named GPU lanes are pre-authorized but SHIP-007 LIVE bisection is borderline (binary rebuild needed + host driver mismatch). Operator-triggered keeps the audit clean.
4. **Why list SaveTensorStage variants as "function_names"?** They're enum variants, not functions strictly speaking, but they are the symbolic identities that the algorithm-level evidence binds to. The contract validator accepts them.
5. **Why explicit prerequisites in `notes`?** Future readers who see "PARTIAL_ALGORITHM_LEVEL" need to know WHY it's not yet FUNCTIONAL. The notes are the operator-handoff document inside the contract itself.

## Net effects

- Contract `trace-attn-sub-stages-v1.yaml` v1.1.0 → v1.2.0 PROPOSED.
- SUB-003: drift fix (3 real wired functions, 2 explicit drift-prevention test pins).
- SUB-004: BLOCKER_FIXTURE_ABSENT → PARTIAL_ALGORITHM_LEVEL with 4-line invariants + explicit FUNCTIONAL prereqs.
- **MODEL-1 ship %**: unchanged at **91%** (FUNCTIONAL discharge gates ship %, not PARTIAL).
- **MODEL-2 ship %**: unchanged at **57%**.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@noahgift noahgift changed the title contract(trace-attn-sub-stages-v1): v1.2.0 — function-name drift fix in SUB-003 algorithm_evidence contract(trace-attn-sub-stages-v1): v1.2.0 — SUB-003 fn-name drift fix + SUB-004 BLOCKER → PARTIAL_ALGORITHM_LEVEL May 4, 2026
@noahgift noahgift merged commit 764fde5 into main May 4, 2026
10 checks passed
@noahgift noahgift deleted the contract/trace-attn-sub-stages-v1-2-0-fn-name-drift branch May 4, 2026 07:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant