Require a semantic check on a protected lane

Everything the symbol graph does is advisory except one thing: a protected lane can declare that a semantic check is required, and a land that would introduce a breaking interface change or an interface-level semantic conflict is then refused.

What the gate actually checks

At a diverged three-way land onto that lane, TOVIO runs two detectors over the symbol graphs of the commits involved:

• Semantic conflict — two textually-clean edits to the same exported symbol that disagree, or one side removing a symbol the other side started referencing.
• Breaking diff — an exported symbol removed, or its signature or supertypes changed.

Either one refuses the land with TVO-SEM-004, before the lane advances. The policy is only what decides whether a finding is a warning or a refusal — both detectors run on every diverged land regardless.

The gate runs on a diverged three-way land only. A land that fast-forwards, or that is already up to date, has no base-versus-both divergence to compare, so no semantic check happens on that path. Do not read an enabled gate as "every land onto this lane is interface-checked" — a fast-forwardable lane that removes an exported symbol will land without objection. Where that matters, require review as well, so the lane advances only through the Forge.

It fails closed

If the lane requires the check but the running binary was built without the semantic layer, the land is refused with TVO-SEM-005 rather than waved through. A required check that cannot be evaluated is never treated as passed. This is the one place where --no-default-features changes behaviour instead of just removing a feature.

The same gate applies on a Forge

A lane that also requires review advances only through the Forge. The Forge re-runs the same detectors against the pinned reviewed commit before it advances the ref, and refuses over HTTP 422. So the gate cannot be bypassed by getting a change approved and then landing something different.

Preview it before you land

tovio explain semantic --into main

tovio health --into main

explain semantic --into <lane> evaluates the gate for that lane and tells you whether a land would pass or fail, with the symbols and reasons. Run it before the land rather than after the refusal.

Turning it on

The requirement lives on the lane's protection record in the repository's policy manifest, as a semantic_check setting alongside the other protections for that lane pattern.

Worth knowing: tovio policy protect has flags for required checks, review requirements and reviewer eligibility, but no flag for the semantic check in the shipped CLI. The gate is fully implemented and enforced on both the client and the Forge; what is missing is a convenient way to switch it on. If you need it enabled today, ask support rather than hand-editing the manifest.

And a trap that follows from it: tovio policy protect rewrites a lane pattern's protection record wholesale rather than amending it. Running it again on a lane that already has the semantic gate enabled — to adjust reviewers, say — silently drops the gate, with no warning. If the gate matters on a lane, re-check it after any change to that lane's protection.

Choosing whether to require it

It suits a lane with published consumers — a release lane, a library's main lane, an API surface other teams build against. It suits an early-stage lane much less, where interfaces are supposed to move and every land would argue with you.

A reasonable middle path is to leave it advisory everywhere, read the warnings for a few weeks, and require it only where the warnings turned out to matter.