Variable contracts: see the value that crosses an activity boundary undeclared

[m2ux]

Summary

An activity declares the session variables it reads and the variables it writes, and a guard holds
the corpus to those declarations. It could not see a variable that no declaration mentioned at all.

The guard derives what an activity reads and writes, then narrows both sets to the workflow's
declared namespace — and that namespace is assembled from the very declarations being checked. So a
name nobody declared dropped out of both sides at once: its production vanished from the derived
writes, its consultation vanished from the derived reads, and the pair of silences was
indistinguishable from a name no activity uses. The check could police a name someone had already
declared and nothing else.

Stacked on #501 so the two can be reviewed apart and land together. Base is
feat/496-activity-exits; the diff here is the guard and the contracts, not the routing.

How it surfaced

A layer-3a smoke run of work-package — a real worker, two activities — failed its session-contract
assertion: the run wrote prior_feedback_triage and rating_cap while exiting start-work-package,
which declared neither. The corpus guard was green at the time.

start-work-package binds review-existing-feedback, whose declared outputs are those two names.
submit-for-review binds review-summary, whose prose interpolates both. Nothing declared either.
So the producing side and the consuming side were both invisible, for the same circular reason, and
the run was the only thing that could see it.

The change

The derived contract now carries two sets before the narrowing: what a step produces (a bound
operation's declared output, a remap target, a checkpoint's setVariable key, a set target, a
loop's item variable) and what a step mentions. A new finding family reads them:

undeclared-crossing — a name produced in one activity, consulted in another, and declared by no
contract in the workflow. The value crosses an activity boundary with nothing accounting for it at
either end.

Only that shape. Two wider readings were tried and rejected, because the namespace filter turns out
to be doing real work:

Reading	Findings	Why rejected
Every production not declared as a write	584	Most technique outputs are local to the activity. body, title, file_count are consumed by a later step and never become session state.
…minus locally-consumed and artifact outputs	197	Still flags a utility operation's confirmation value — written_artifact at 15 sites — which legitimately dies with its step.
Produced here, consulted there, declared nowhere	79	No false positives of either kind.

A production nothing else consults is not reported, and neither is one whose technique declares an
#### artifact: its destination is a file. The exemption means a declaration is not required
there, not that it is wrong — prior_feedback_triage is an artifact output that a worker also
relays into the bag, so it is declared, and the two checks now agree about it.

What the corpus owed

79 findings, 55 values, 7 workflows. All of them are now declared: the write on every producing
activity, carrying the description the producing technique already gives the output, and the read on
every activity the guard finds consulting it.

Three things came out of the fixing that are worth stating.

A read can be reached before its producer runs. 54 of the declarations landed on activities that
consult a value earlier in the order than the activity producing it, or on a loop-back. Those writes
carry a default, so the reader finds the empty value rather than nothing. requirements (29 sites),
changed_files (10) and review_summary (5) account for most of them.

A borrowed activity is bound by the workflow running it. remediate-vuln opens on its own
start rather than work-package's start-work-package, so the two review-mode values that opener
produces have no producer there. Declaring the write upstream left the borrowing workflow with a
reader and no writer — the #491 borrowed-scope class, reported exactly as designed. remediate-vuln
now owns both as the empty constants they are in a workflow that never reviews a pull request.

A description does not travel with its links. 13 of the descriptions copied from technique files
carried relative markdown links that resolve from techniques/ and not from activities/; one broke
check:resource-anchors. The declarations keep the words and drop the links.

Verification

• npm run check:all — 30 guards, all pass. The new family is at hard zero, like the other five.
• npm run test:ci — 1,097 pass.
• The assertion that failed the smoke run now passes against the session that failed it.
  Re-running check-session-contract over the saved smoke-20260824083443/session.json:
  23 write(s) measured … OK — every write the run recorded is one the activity that made it declares.
  That is the original defect confirmed fixed on the original evidence, without a second paid run.
• Walk snapshots unchanged apart from the corpus SHA stamp: declaring a contract moves no path.

Non-goals

The guard reports a crossing, not a design. Where a value ought not to cross an activity boundary at
all, this declares the crossing that exists rather than redesigning the flow.

Two near-duplicate names in substrate-node-security-audit — dispatch_results and
dispatched_results — are both declared here because both are produced and consulted. That they
coexist is a smell worth its own look; it is not this change's business.

🤖 Generated with Claude Code