Apply family plans in bulk and after virtual-chassis changes

[marcinpsk]

Parent

#73

What to build

Route bulk application and module-family reapplication after virtual-chassis changes through family plan sets. Operators must keep the existing foreground, background, and signal behavior while rule/template loading and query growth remain bounded across multiple families.

Acceptance criteria

• Bulk discovery creates one plan per installed family and does not duplicate members across plans.
• Selected-interface and limit behavior remains compatible with existing foreground and background operations.
• Foreground views and background jobs render counts, skips, collisions, and member facts from explicit outcomes rather than mutable private conflict structures.
• Virtual-chassis reapplication plans and executes every module-attached family that depends on virtual-chassis position.
• Existing device-level interface rules continue to run with their current behavior when the device path also contains module families.
• Shared enabled-rule and template data is loaded once per applicable batch rather than once per family or member.
• One blocked family does not prevent later families in the batch from being attempted.
• Unexpected module failures remain visible and preserve the existing boundary-level continuation policy.
• Real PostgreSQL tests cover bulk apply, selected subsets, one and eight same-type families, one and eight channelized families, virtual-chassis changes, and mixed module/device interface rules.
• Query counts and scaling do not regress against the existing implementation baseline.
• Existing foreground messages, job summaries, signal results, and final interface names remain compatible.

Blocked by

• Build channelized families and reconcile deferred names #78

[marcinpsk]

Implemented on perf/issue-74-signal-baseline (PR #83), commits 556475b and 270a93a.

What moved

family/batch.py is the new batch layer. apply_rule_to_modules plans every family a rule intends on each module and executes each family on its own, and apply_rule_to_existing is a facade over it. Two plan kinds complete the executable set the bulk path needed: a FlatCreationPlan that expands one plain interface into its sibling family, and a one-member installed plan for a rule that renames an interface which belongs to no family. A module's installed families claim their members first, and each leftover interface is planned as the family the rule would build there, so no interface belongs to two plans.

apply_rule_to_existing returns a BatchOutcome and no longer takes a conflicts list. The Apply view and the background job read the renamed count and the skipped interfaces from that outcome. engine._find_channel_base, _apply_channel_rule_to_module, _apply_plain_rule_to_module, _apply_family and _raw_matchers are gone.

pinned_template_cache shares one module type's interface templates across a batch, and raw_name_matchers now derives its names from resolved_template_names, so the two callers no longer resolve the same templates twice. reapply_module_rules makes a virtual-chassis change one batch under that pin and one pinned enabled-rule snapshot.

Deliberate behaviour changes

• A module type with several ports and a breakout rule builds and previews one family per port. Before, one base was picked per module and the other ports were left out. Two bases that intend the same names still build that family once, through the base the family already names, so completing a half-built family is unchanged. Preview and apply share that choice in one_family_per_name_set.
• Bulk apply recovers an installed flat family from the module type's templates, so a family whose template name changed is renamed as a family instead of being renamed from its current channel-0 name.
• A blocked channelized family reports every member it left unchanged, so the skipped count covers the family rather than only its parent.

Query measurements

Measured on the same fixtures before and after, statements per operation:

scenario	before	after
flat breakout, first apply, one module	78	76
flat breakout, marginal cost per further module	76.8	73.5
flat breakout re-apply, eight modules	42	27
simple rename, marginal cost per further module	27.3	30.5
virtual-chassis reapplication, eight modules	245	230

A simple rename costs three more statements per module, a savepoint pair and the row lock, because it now goes through the family executor. That buys it stale-plan rejection and per-family isolation, which that path did not have. Scaling is unchanged and pinned by tests: the templates are read once per module type, no module is refetched, and the marginal cost of the eighth module is no higher than the first.

Review

An adversarial review raised two findings.

Accepted: the structural guard that refuses to build a channelized family on a module which already carries a flat breakout counted the family's own channel rows as stranded siblings. A module with two ports lost the second one, and a later apply could never give it a family, although the preview offered it. Fixed in 270a93a, with the failing case confirmed red first.

Deferred to #82: virtual-chassis reapplication still reaches the families through the installation entry point, so it reads one module's interfaces at a time and still renames a leftover interface outside the family executor. Contracting that entry point is #82's scope, and ADR 0009 now says so rather than implying the batch already covers it.

Verification

The full suite passed 788 tests on the local NetBox 4.6 release and 798 on the channelized release, with the same known query-baseline failure in both, an unrelated pre-existing local environment issue that CI is not affected by. Coverage met the 97% gate, with family/batch.py, family/targets.py and family/template_names.py at 100%.