6.5.1 Affected-Target Service Contract

An affected-target selector answers a narrower question than “what changed?”: for two repository states, a declared build universe, and a declared set of configurations, which requested roots might need validation? That answer can save substantial CI work, but only if the service can also say when it does not have enough evidence to answer safely. Treat target selection as a versioned service contract, not as a clever query that happens to print labels.

The Answer Is Meaningless Without Its Universe

Suppose a selector returns:

//app:binary
//app:test

The labels look precise, but they do not yet support a CI decision. You cannot tell which base and head revisions were compared, whether //app/... or the whole repository was examined, which platforms and flags were represented, or whether a missing target means “unaffected” or “not analyzed.”

Bazel's query tools provide useful graph evidence, but they answer different questions. query operates on the declared target graph, while cquery analyzes configured targets for declared roots and options; transitions can produce several configured instances of one label.¹ The choice can change both the cost and the coverage of a selector; bazel-diff therefore exposes both query modes rather than pretending they are interchangeable.² 5.2.2 bazel cquery — Configured Graph develops that configured-target distinction, and 5.2.7 Query in CI Pipelines shows how to use both tools as bounded CI evidence.

A useful selector request names at least:

• the immutable base and head revision identities;
• the candidate roots or target patterns whose validation is being decided;
• the configurations, platforms, and toolchains the service claims to represent;
• the comparison mode and selector version;
• any repository state or generated snapshot needed to reproduce the comparison.

The universe is the combination of those boundaries. “Affected” never means affected everywhere; it means affected within this request's declared universe. This is the service-level extension of the bounded graph work in 5.3.2 Practical Graph Analysis.

Return a Decision, Not Just Labels

Use three outcomes:

An empty affected set and unknown are therefore opposites. The first is a completed negative result. The second says that no trustworthy negative result exists.

Represent that distinction explicitly in the response rather than encoding it through an empty file, a warning line, or a process exit status that every caller must interpret independently:

{
  "outcome": "affected",
  "base_revision": "<immutable-id>",
  "head_revision": "<immutable-id>",
  "universe": {
    "roots": ["//app/..."],
    "configurations": ["linux-x86_64-release"]
  },
  "targets": ["//app:binary", "//app:test"],
  "selector": {
    "implementation": "graph-hash",
    "version": "<version>"
  },
  "explanations": [
    {
      "target": "//app:test",
      "evidence": "depends on changed target //lib:parser"
    }
  ]
}

This is an interface sketch, not a mandatory wire format. The important properties are typed outcome, immutable comparison identity, explicit scope, implementation identity, and evidence that a human or another service can inspect.

Make the Result Reproducible and Explainable

Target-selection systems commonly sit before the expensive part of CI. Tinder's published design uses graph hashes from two revisions to produce impacted targets, then feeds that output into a separate orchestration layer that schedules builds, tests, and artifacts.³ The separation is useful: the selector establishes impact evidence; the CI system decides what to run.

Preserve enough information to replay that boundary. A diagnostic record should answer:

1. Which exact request produced this result?
2. Which evidence connected each selected root to a changed input or target?
3. Why was an expected-looking root omitted?
4. Which unsupported or missing input would have changed the outcome to unknown?
5. Which selector and schema versions interpreted the snapshots?

Do not promise one universal explanation shape. A reverse-dependency selector may report a path through the graph; a hash comparator may report old and new fingerprints; a metadata rule may report that a special file invalidated the ordinary calculation. The portable contract is that the explanation identifies the evidence and its scope, not that every implementation exposes the same algorithm.

bazel-diff is one concrete implementation: it generates hashes for two graphs and emits impacted targets, with query and cquery modes and optional seed files for changes that require broader rebuilding.⁴ It is evidence that an affected-target service can be built, not evidence that every selector has identical completeness or failure semantics. 6.5.2 Comparing Bazel Graphs Across Revisions continues with the mechanics of comparing base and head graphs.

Test the Contract at Its Boundaries

A selector test suite needs more than a fixture where one source edit selects one test. Begin with three contract cases:

• Known affected: a supported change reaches a candidate root; the response selects it and explains the connection.
• Known unaffected: a supported change is outside the candidate roots' modeled dependencies; the response is unaffected, with the compared universe recorded.
• Unknown: remove or corrupt required comparison evidence; the response is unknown, never an empty successful result.

Run the affected-target-contract snippet to see those three cases through one deterministic selector interface. Its contract verifier checks the echoed identity envelope, the affected root's explanation, completed evidence for an empty unaffected result, and the missing-configuration gap that keeps unknown out of the empty-result path.

Then verify identity errors: swap the requested head revision, use a snapshot produced by another selector version, or omit one supported configuration. These cases test whether the service refuses to make a narrower claim than its evidence supports. 6.5.2 Comparing Bazel Graphs Across Revisions implements base/head comparison; 6.5.3 Global Target-Selection Invalidators classifies global invalidators; 6.5.4 Selecting Affected Targets Across Configurations proves configuration coverage; 6.5.5 Incomplete Selector Evidence detects deletes, renames, and stale evidence; and 6.5.6 Fail-Closed Target Selection defines the conservative response.

Do not store a selector response as if it were a Bazel action-cache result. An action cache key describes a Bazel action and its declared execution inputs. A selector response describes a comparison between repository states under a service-specific universe and algorithm. Both may use hashes, but their identities and correctness claims are different.

Keep Policy Outside the Technical Answer

The selector should report what its supported evidence establishes. It should not silently decide whether a team may skip integration tests, whether a merge queue may advance, or how much false-negative risk is acceptable. Those are consumer policies.

That boundary lets multiple workflows consume one technical result without changing its meaning. H.7.6 Speculation can use selection evidence when scheduling speculative work; H.7.3 Evidence Selection can define which test scopes a change must protect; and H.7.2 Evidence Portfolio can apply different cadences to different test layers. H.10.3 Service Capacity helps determine when the cost of broad validation makes such infrastructure worthwhile. None of those policies turns unknown into unaffected.