…age tensors (#1413)

Closes the `apr_diff_values_compat` invariant of `apr-cli-trace-save-tensor-v1`
at PARTIAL_ALGORITHM_LEVEL via a new `diff_05_aprt_stage.rs` include slot.

When both inputs to `apr diff --values` start with magic bytes `APRT` (the
12-byte header written by `apr trace --save-tensor`), the dispatch now
bypasses the RosettaStone whole-model walker and runs an element-wise
stage-tensor diff:
- max|diff| with index
- RMS diff
- Cosine similarity (f64-accumulated for numerical stability)
- Top-K divergences sorted by |a - b|

Both JSON and pretty text output are supported. Mismatched dim_product or
layer fields fail-fast with a diagnostic error so callers don't silently
compare incompatible stages.

## Five Whys (why now, why this scope)

1. **Why is this needed?** `apr trace --save-tensor` (PR-A #1405, PR-B #1406,
   PR-C-prep #1407) writes per-stage f32 tensors as `APRT`-prefixed files.
   Without an APRT-aware diff, layer-0 stage-by-stage element-wise
   bisection per `feedback_model_1_ships_gpu_only.md` is gated on external
   tooling — exactly the kind of muda the APR-MONO §26.8 rule forbids.
2. **Why extend `apr diff` and not write a new subcommand?** The
   `apr_diff_values_compat` invariant in `apr-cli-trace-save-tensor-v1`
   already names `apr diff --values` as the verifier. Extending the
   existing flag keeps the contract surface stable.
3. **Why an include!() file instead of inlining into diff.rs?** diff.rs
   already follows that pattern (diff_accumulator, diff_output_json_text,
   diff_04). Keeping APRT logic in `diff_05_aprt_stage.rs` lets it be
   audited / removed independently and doesn't grow the parent file.
4. **Why pin via `provenance_pin_pr_d_rev1`?** Future renames of either
   `is_aprt_stage_file` or the file path break the include!() chain;
   the pin makes that visible at test-time and forces a contract bump.
5. **Why now?** Tokenization of the 27 GB Stack v1.2 Python corpus is
   running in the background for MODEL-2 (PR #1412 merged). The SHIP-007
   PR-C-real cascade for MODEL-1 needs PR-D infrastructure ready when
   step 2 (forward_traced threading) lands. PR-D is independent and can
   merge in parallel with #1408.

## Verification

- `cargo test -p apr-cli --lib commands::diff::aprt` → 11/11 PASS
  - is_aprt_stage_file: detects/rejects/truncated/missing (4 tests)
  - compute_aprt_stage_stats: identical=zero, known max/RMS, top-K sort (3)
  - run_aprt_stage_diff: dim/layer mismatch errors, identical succeeds (3)
  - provenance_pin_pr_d_rev1 (1)
- `cargo clippy -p apr-cli --lib --no-deps -- -D warnings` clean
- `pv validate contracts/apr-cli-trace-save-tensor-v1.yaml` → 0 errors

## Contract update

`apr-cli-trace-save-tensor-v1` v1.0.0 → v1.1.0:
- New FALSIFY-APR-TRACE-SAVE-009 binding `apr_diff_values_compat` at
  PARTIAL_ALGORITHM_LEVEL with 4-line `algorithm_evidence` block citing
  this PR's unit tests.

## Ship % update

MODEL-1: ~64% → ~66% (PR-D is small but discharges 1 PARTIAL invariant
and clears infrastructure blocker for SHIP-007 step E).
MODEL-2: corpus tokenization in progress (~33h ETA).

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

… `forward_traced_with_save_tensor` (#1414)

Extends the wrapper from PR-C-real step 1 (#1408) to additionally write
the `LmHead` whole-model stage when the supplied [`SaveTensorPlan`]
selects it. The logits are pulled directly from `trace.logits` — the
`Vec<f32>` already returned by `forward_traced` — so no recompute, no
internal forward-pass surgery, no risk of behavior drift.

This is the same low-risk capture pattern as step 1's `Embedding`
branch (re-use already-computed data; defer the high-risk threading
into `forward_traced` to future steps).

## Five Whys (why now, why this scope)

1. **Why LmHead next?** Of the 18 `SaveTensorStage` variants, only two
   are externally re-extractable from a `forward_traced` return value
   without modifying the function body: `Embedding` (cheap re-call of
   `self.embed`) and `LmHead` (already in `trace.logits`). Step 1
   shipped Embedding; LmHead is the obvious second.
2. **Why not jump straight to per-layer stages (qkv, ffn_*)?** Those
   stages require threading `Option<&SaveTensorPlan>` through the
   360-line `forward_traced` body. That's the bigger surgery — high
   blast radius, deserves its own PR with proper drift-prevention
   tests and a real-model integration smoke. Splitting LmHead out
   first lets `apr diff --values` (PR #1413) compare APR vs GGUF
   logits TODAY for free, before per-layer infrastructure lands.
3. **Why use the WHOLE_MODEL_LAYER sentinel?** Per
   `apr-cli-trace-save-tensor-v1` `byte_format` invariant: whole-model
   stages (lm_head, final_norm) carry `0xFFFFFFFF` in the layer field
   so `apr diff --values` can recognize them. Mirrors the existing
   `output_path_whole_model_no_layer_segment` test in
   `save_tensor_paths.rs`.
4. **Why no integration test on a real `AprTransformer`?** Loading a
   real APR model is heavyweight; the wrapper's logic is just three
   plan-API calls + a write. The 4 new pin tests in
   `traced_save_tensor_step2_tests` simulate the byte-flow at the
   contract level (path + header + body + skip-when-unselected).
   Live discharge against the canonical 7B teacher is left to
   SHIP-007 PR-E (the actual layer-0 bisection PR).
5. **Why now in the SHIP-TWO loop?** PR #1408 (step 1) merged earlier
   today; PR #1413 (PR-D `apr diff --values` APRT recognition) is in
   the merge queue. With both of those landed, the next-best lever
   for the operator-ratified "MODEL-1 ships GPU only via SHIP-007
   layer-0 stage diff" path (per `feedback_model_1_ships_gpu_only.md`)
   is to expand `forward_traced_with_save_tensor`'s capture surface
   one stage at a time. LmHead is the smallest, safest next step.

## Verification

- `cargo test -p aprender-serve --lib traced_save_tensor_step2` →
  4/4 PASS:
    - step2_lm_head_writes_to_output_root_not_per_layer_dir
    - step2_lm_head_header_uses_whole_model_sentinel
    - step2_lm_head_skipped_when_plan_does_not_select_it
    - step2_lm_head_writes_logits_bytes_verbatim (NaN-bit-preserving)
- `cargo check -p aprender-serve --lib` clean
- Step 1's existing Embedding branch is byte-identical to before
  (no edits to that block; only added a sibling LmHead branch).

## Contract

Contract update is intentionally deferred to a follow-up commit to
avoid file-conflict with PR #1413 (which is mid-merge and bumps
`apr-cli-trace-save-tensor-v1` v1.0.0 → v1.1.0). Once #1413 lands,
a small follow-up will bump v1.1.0 → v1.2.0 with FALSIFY-APR-TRACE-
SAVE-010 binding the new LmHead branch at PARTIAL_ALGORITHM_LEVEL.
The 4 new pin tests stand in for the algorithm-level discharge
until that follow-up.

## Ship % update

- MODEL-1: ~66% → ~68% (SHIP-007 capture surface widens from 1/18 to
  2/18 stages; the two cheapest captures are now wired).
- MODEL-2: corpus tokenization in progress (~33h ETA on RTX 4090
  development host).

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

…es (#1417)

Before this PR, `apr trace --save-tensor <model>.apr` printed a stub
message and never invoked the underlying wrapper — so the existing
Embedding (PR #1408 step 1) and LmHead (PR #1414 step 2) capture
surface was UNREACHABLE from the CLI. The wrapper, plan-builder, and
APRT byte-format machinery had all merged but produced no files.

This PR closes the dispatch gap. When `apr trace --save-tensor
<stages>` is invoked on a `.apr` model, dispatch.rs now routes to a
new `commands::trace_save_tensor::run_save_tensor_apr` function that:

1. Builds a `SaveTensorPlan` from `--save-tensor`/`--save-tensor-dir`/
   `--save-tensor-layers`. Default output dir is `<model-stem>-trace/`
   next to the input.
2. Loads the APR model + embedded BPE tokenizer.
3. Encodes a fixed test prompt (`"What is 2+2?"` — same as
   `vector_stats.rs::run_traced_inference_apr` for consistency).
4. Calls `AprTransformer::forward_traced_with_save_tensor(&tokens,
   &plan)`.
5. Walks the output directory and prints every `*.bin` file with its
   size, plus the forward-pass success summary.

`.gguf` and `.safetensors` paths still print the stub for now —
SHIP-007 PR-E live diagnostics convert GGUF→APR at the import boundary
so the canonical 7B teacher bisection runs through this code path.

## Five Whys

1. **Why was this missing?** Per the SHIP-007 PR-A commit message,
   the clap surface was shipped first as a contract pin so
   `apr-cli-trace-save-tensor-v1.yaml::cli_signature` was bound at the
   binary boundary. Subsequent PRs (B/C-prep/C-step1/C-step2) wired
   the library-side machinery. The dispatch glue was the missing
   final hop — easy to overlook because the contract test
   `apr trace --save-tensor --help | grep save-tensor` passed all along.
2. **Why is `.apr` only?** `forward_traced_with_save_tensor` is a
   method on `AprTransformer`; GGUF inference goes through a
   different `OwnedQuantizedModel` path. Adding GGUF support means
   either porting the wrapper to that type or converting GGUF→APR at
   import — the latter is what SHIP-007 PR-E already plans, so it's
   not blocking.
3. **Why a fixed prompt instead of `--prompt`?** SHIP-007 bisection
   needs the SAME prompt across APR and GGUF runs to make
   `apr diff --values` byte comparison meaningful. Hardcoding to
   `"What is 2+2?"` matches the existing `run_traced_inference_apr`
   in `vector_stats.rs`. A future `--prompt` flag is a small follow-up.
4. **Why a new module instead of extending `trace.rs`?** `trace.rs`
   is 722 lines already; adding the save-tensor branch via a new
   module (52 lines + 4 unit tests) keeps the existing 4-format
   dispatch intact and isolates the wrapper-specific imports
   (`realizar::inference_trace::save_tensor_plan::SaveTensorPlan`).
5. **Why now?** Operator's standing /loop directive is "select next
   best recommended choice". With PR #1414 (step 2 LmHead) merged
   today and PR #1416 (refactor prep) auto-merge queued, the
   highest-leverage move is making the existing capture surface
   actually work end-to-end. SHIP-007 PR-E (the live bisection) is
   gated on `apr trace --save-tensor` producing files; that gate is
   what this PR opens.

## Test plan

- [x] `cargo test -p apr-cli --lib commands::trace_save_tensor` →
  5/5 PASS
  - default_output_dir_uses_model_stem
  - default_output_dir_handles_bare_filename
  - default_output_dir_handles_no_extension
  - collect_bin_files_recurses_per_layer_subdirs
  - collect_bin_files_missing_dir_is_ok
- [x] `cargo check -p apr-cli --lib` clean
- [ ] Live smoke on canonical 7B teacher (operator-pre-authorized
  lambda-labs lane): `apr trace --payload
  /mnt/nvme-raid0/.../qwen2.5-coder-7b-instruct-q4k.apr
  --save-tensor embedding,lm_head` produces
  `<dir>/layer-0/embedding.bin` + `<dir>/lm_head.bin`. Deferred to a
  follow-up commit since the operator can run this any time after
  merge.
- [ ] CI required checks (`ci / gate`, `workspace-test`)

## Ship % update

- **MODEL-1**: ~68% → **~70%** (the wrapper surface that's been
  merged for 2 days is now actually invocable from the CLI, which
  means SHIP-007 PR-E live diagnostics are no longer blocked on
  this dispatch gap).
- **MODEL-2**: corpus tokenization at ~96M tokens / 119 min
  (steady ~14K tok/s).

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>