Branch views

A branch view is one inventory read on one branch. Census builds it on the first query that names the branch, keeps it in the cache under the branch name as its view, and retires it when it is idle (crates/sync/src/branch.rs).

Build

On the first query for (inventory, branch), Census takes the view's build lock, so that concurrent first queries build it once, and refreshes every contribution of the inventory on the branch:

Connector answer	Contribution in the view	Recorded reason
The source does not support branches (NetBox)	Reads the contribution's default-view records	source does not branch
The source reports that the branch does not exist	Reads the contribution's default-view records	branch not found in source
The branch exists	Publishes branch records under the branch's view	none
Any other error	The build fails: 503 branch-unavailable

Census fetches every branching source before it writes anything. If one fails, nothing of the view is kept. If no contribution supplied branch data, the query returns 404 branch-not-found.

For an Infrahub connection, Census reads a branch through a second client bound to /graphql/{branch}. The branch name is passed unchanged.

Resolve

An entity in a branch view is resolved from the branch records of the contributions that supplied the branch, and the default-view records of the others, with the same rules as the default view. The writer remembers, for each held view, which contributions supply default data, so a write to a default-view record also recomputes the affected entities in those views.

Completeness and health in a branch response combine the branch view's contribution states with the default-view states of the contributions that supply default data.

Keep and retire

• A background task refreshes every held view on the shortest refresh_interval among all contributions, and retires views that no query has read for [branching].idle_ttl.
• Infrahub webhooks for the branch update a held view.
• At most [branching].max_views views are held across all inventories. Building one more retires the view read least recently.
• If a refresh of a held view fails, the view keeps its data and the contribution's health becomes degraded.
• When every source that supplied the branch reports that it no longer has it, the view is retired.
• Retiring a view deletes its records, entities and contribution states.

Background: research decision D22 in specs/008-named-inventory-federation/research.md, and feature 006 in specs/006-branch-scoped-queries/.