C-104: one honest failure instead of twenty-five misleading ones

[Polichinel]

The problem

On 2026-08-16 a pytest run in this repository reported 25 failures across five modules, and none was a defect. The virtualenv held views-pipeline-core 2.3.0 and pyarrow 23.0.1 while poetry.lock pinned 3.0.1 and 16.1.0.

Two majors of drift produce:

• ModuleNotFoundError: views_pipeline_core.modules.dataloaders.datafactory_contract at the import of both managers — which takes out every test that constructs or inspects one, i.e. the only coverage the two largest modules in the package (387 lines each) have;
• five byte-parity failures against the ADR-013 §10 golden fixture, because parquet bytes are not stable across pyarrow majors (C-72).

From the failure output, neither is distinguishable from a real regression. "You broke the wire contract" is the available reading, and it is the one that costs an afternoon.

What this adds

tests/test_locked_environment.py — two checks:

1. installed versions of the runtime dependencies declared in pyproject.toml match poetry.lock;
2. everything declared in pyproject.toml is actually in the lock — the other direction, which would otherwise be reported as a virtualenv problem when it is a stale lock.

Declared, not hardcoded. A literal list goes stale the first time a dependency is added, which is exactly the failure mode tests/conftest.py::PARTNER_PACKAGES exists to prevent one level up.

The failure a developer actually sees:

Failed: this virtualenv is not the one poetry.lock describes:
    views-pipeline-core      installed=2.3.0        locked=3.0.1
    pyarrow                  installed=23.0.1       locked=16.1.0

Run `poetry install`.

Any OTHER failures in this run are most likely consequences of the drift above, not
defects. Two majors of views-pipeline-core remove `modules.dataloaders.datafactory_
contract`, which both managers import at module scope — so every test that touches a
manager dies at collection. A pyarrow major changes emitted parquet bytes, which fails
the ADR-013 §10 byte-parity fixture (C-72). Fix the environment before reading them as
bugs.

If the drift is deliberate — trialling an upgrade — this test is telling you the truth
and the rest of the suite is not testing the locked contract.

What it deliberately does not do

It does not fix the drift and it does not skip. The 25 failures stay until someone runs poetry install. What changes is that a contributor can tell in one line which kind of problem they have — the failures were never wrong, they were unreadable, and that is the whole of C-104's cost.

Dev-group tools are out of scope on purpose: ruff's reported version varies with how it was installed, and the thing that actually broke CI on 2026-08-03 was its rule set, which pyproject.toml already pins explicitly.

Proof

A natural experiment rather than a mutation, and a better one:

environment	expected
this developer venv (drifted)	fails, with the table above — confirmed
CI (poetry install from the lock)	passes — this PR's own run is the check

If CI goes green on this PR, that is simultaneously the negative case for the new test and the standing evidence that the 25 local failures were only ever environment drift.

ruff check . clean. C-104 updated with a Partial mitigation note.

[Polichinel]

Review round — /review-diff + /code-review high

/review-diff — 1 note, not acted on

tests/test_release_version.py:30 parses pyproject.toml with a regex where this file uses tomllib. The regex is the more fragile of the two and its own message admits it ("no longer declares a version in the form this guard reads"), but converting it is scope creep into a file this PR does not otherwise touch. tests/seam_registry.py already uses tomllib, so the new file follows the newer pattern and the regex is the outlier. Noted, deliberately left.

Also verified rather than defended: poetry.lock has 118 packages, no duplicate names, so building a {name: version} dict cannot silently take the last of two entries. No defensive code added for a case the format does not produce.

/code-review high — 8 findings, all fixed

The first is the one that matters, because it was in the diagnosis itself. The message said "every test that touches a manager dies at collection". It does not — the manager tests import lazily (test_framework_contract.py:50), so the drift produces ordinary failures and the session completes. Measured in the drifted venv: 26 failed, 441 passed, 0 errors. The claim was also self-defeating: pytest interrupts the session on collection errors, so had it been true, this diagnostic would never have run in the scenario it was written for.

The rest:

#	finding	fix
2	the consequences paragraph was hardcoded to pipeline-core and pyarrow but fired for any drift — a views-frames bump would have been explained in terms of parquet bytes	conditional on the actual drift set
3	no PEP 503 normalization: PyYAML or views_frames would never match a lock entry, failing with "run poetry lock" when the lock was fine	both sides normalized
4	optional / python / markers deps treated as must-be-installed — would have gone red in CI on the 3.11 runner for a python-gated dep	skipped (verified extras-carrying deps are still kept, since that is our real views-pipeline-core declaration)
5	the claimed ordering guarantee did not hold — a stale lock was reported twice, once misleadingly as locked=None	the version check skips unlocked names and defers
6	installed=None, expected=None was a silent pass	same fix as 5
7	bare KeyError on a PEP 621 migration — the unreadable failure this module was written against	fails with the form it expects, per test_release_version.py's precedent
8	register Last Updated stale since C-103	bumped

Findings 2 and 3 are worth dwelling on: a guard that names the wrong packages, or that says "run poetry lock" when the lock is correct, is the same defect this file exists to remove, reintroduced one layer up.

Verification

environment	result
CI (poetry install from the lock)	465 passed, 5 skipped, 37 xfailed, 0 failed
this developer venv (drifted)	fails with the table, naming only the two packages that actually drifted

That pair is the whole proof: the test passes where the lock is honoured and fails where it isn't — and it is simultaneously the standing evidence that the local failures were only ever environment drift.

Also verified directly: normalization on PyYAML / views_frames / Foo.Bar_baz, and the conditional-skip rule against optional / python / markers / extras shapes.