# AFN-014 — Do not call a contract vector an upstream capture

> Pinned Transformers can author module outputs, but synthetic tokens, hashed PLE rows, and cache images need a different provenance label or the fixture overstates its authority.

- Status: verified checkpoint
- Phase: 5
- Published: 2026-08-30
- Canonical URL: https://andreabor.io/agents/label-contract-control-vectors/
- Project: Hebrus
- Hebrus source repository: https://github.com/andreaborio/hebrus
- Contribute to Hebrus: https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md
- Hebrus issue tracker: https://github.com/andreaborio/hebrus/issues
- Keywords: Hebrus, oracle provenance, golden vectors, Transformers, contract control, independent implementation, Qwen4Exp

## Retrieval capsule

- Estimated context: ≈366 tokens for this capsule; ≈717 for the full note
- Retrieve when: You are generating golden vectors from a framework that does not expose every cache image, token choice, tie policy, or synthetic control needed by the native test.
- Retrieval triggers: golden fixture generated by code under test; upstream framework does not expose cache state; per-array oracle provenance; synthetic control mislabeled as upstream
- Decision: Record provenance per fixture array and reserve the upstream-capture label for values actually emitted by pinned upstream code; label synthetic identities and state images as contract controls.
- Invariant: A fixture's provenance never claims that upstream produced an array which the collector constructed from the local contract.
- Failure signature: A generated file mixes upstream outputs and locally invented controls under one trusted label, allowing the implementation to validate its own assumption as external truth.
- Minimal safe implementation: Attach an origin to every array, execute pinned upstream for exposed values, independently recompute their math, and label synthetic token, state, tie, and overflow controls explicitly.
- Rejected shortcut: Calling the entire golden file upstream-backed because some arrays passed through the upstream runtime.
- Evidence: Graph fixtures execute pinned Transformers at 42ca97014c85d71a88ad60d55f08cb9fb4d26e2c, cross-check independent NumPy/scalar C, and label non-upstream arrays as contract-control in per-array provenance
- Evidence checkpoint: Hebrus 0626603
- Claim boundary: These tiny graph vectors prove primitive and transition semantics only; they do not contain checkpoint weights, full-layer intermediates, quantization error, or final model logits.
- Prerequisites: AFN-008
- Related notes: AFN-009, AFN-010
- Supersedes: none


## Decision

Fixture provenance belongs to each array, not merely to the file.

The Phase 5 collector executes the pinned Transformers Qwen4Exp implementation to capture values that upstream actually computes. An independent NumPy/scalar implementation checks the same math. That provides a strong oracle for exposed module outputs.

Some necessary test inputs and states do not have an upstream capture path. Token sequences are selected by the fixture author. Hashed PLE row identities and persistent cache images may need to be constructed so a specific transition can be tested. Tie, overflow, and rollback controls can also be contractual rather than upstream-authored.

Those arrays are useful—but they are not upstream captures.

## The self-approval trap

Suppose a local implementation defines a cache layout, generates an expected cache image using the same assumption, and stores both beside genuine upstream outputs. If the whole file is labelled “generated from Transformers,” a later agent may treat the cache image as independent evidence.

The implementation has then approved itself while borrowing upstream's authority.

## Provenance classes

A practical fixture can distinguish at least:

- **upstream capture** — emitted by the exact pinned implementation;
- **independent cross-check** — recomputed through a separate algorithm or language;
- **contract control** — deliberately selected input, state image, tie, overflow, or failure case;
- **derived metadata** — dimensions, offsets, or digests computed from already identified sources.

Each class answers a different question. None should silently inherit the authority of another.

## Regeneration rules

The networked collector may be needed to reproduce upstream arrays, but the normal repository test should stay offline. It can pin source revision, tool versions, source hash, per-array provenance, and aggregate fixture digests. Offline validation then detects drift without downloading a framework during every build.

The collector and the native implementation should not share the optimized helper being tested. Agreement is valuable only when likely defects are independent.

## Agent checklist

Before trusting a golden fixture, ask:

1. which exact function produced each expected array;
2. whether that function is upstream, independent, or part of the implementation;
3. which arrays are intentionally synthetic controls;
4. whether regeneration pins immutable source identity;
5. whether ordinary checks detect changes without network access;
6. what the fixture cannot say about full-model behavior.

## Failure boundary

Phase 5's fixture is intentionally tiny and model-free. It closes graph ordering and state-transition questions; it does not replace checkpoint-backed layer captures, final-logit parity, quality evaluation, or performance measurement.