femic.rebuild_invariants Module

The femic.rebuild_invariants module owns FEMIC’s invariant metric collection and evaluation surface for instance rebuild runs. It measures key runtime outputs, expands species-account policy into concrete invariant entries, and evaluates configured invariants into pass/warn/fail results with remediation context.

If you are debugging why a rebuild report failed its regression gate, which metrics were actually measured from a run, or how species-account policy is translated into fatal invariants automatically, this is the first module to read. In practice it owns:

• metric collection from runtime outputs and Patchworks artifacts

• expansion of species-account policy into invariant entries

• invariant comparator evaluation and result payloads

Start Here If…

Use this page first if you are trying to:

• understand the metrics behind instance_rebuild_report-<run_id>.json

• debug a fatal invariant failure during instance rebuild

• inspect how required/absent/nonzero/zero species-account policy rules become concrete invariant checks

Typical maintenance path:

1. Start with collect_rebuild_metrics() for measured-value questions.

2. Read build_species_account_policy_invariants() for automatic policy expansion behavior.

3. Move to evaluate_invariants() when the question is about result status rather than raw metrics.

Typical Usage

The common pattern is to measure runtime outputs first and then evaluate the configured invariant list against those metrics:

from pathlib import Path
from femic.rebuild_invariants import collect_rebuild_metrics, evaluate_invariants

metrics = collect_rebuild_metrics(
    instance_root=Path("."),
    log_dir=Path("runtime/logs"),
    run_id="docs_example",
    patchworks_config_path=Path("config/patchworks.runtime.windows.yaml"),
)
results = evaluate_invariants(invariants=spec_payload["invariants"], metrics=metrics)

How This Fits Into The Pipeline

This module sits after rebuild execution but before final regression gating:

1. rebuild steps produce logs, Patchworks outputs, and other runtime artifacts

2. this module measures selected metrics from those artifacts

3. configured invariants are evaluated against those metrics

4. the resulting statuses feed the final rebuild report and regression gate

That means this module owns the invariant-evaluation contract, not step execution or baseline snapshotting.

Key Entry Surfaces

The highest-value entrypoints in this module are:

• collect_rebuild_metrics()

• build_species_account_policy_invariants()

• evaluate_invariants()

• InvariantResult

Core Contracts

The most important runtime contracts in this module are:

• metrics are gathered from real runtime outputs such as tracks tables, logs, and Patchworks config/model locations

• species-account policy can generate fatal invariants automatically rather than forcing each rule to be hand-authored in the spec

• invariant outcomes preserve both measured values and remediation text so rebuild reports remain actionable

Failure Seams To Watch

The common failure boundaries in this module are:

• missing runtime artifacts metric collection can degrade or fail if Patchworks outputs or logs are absent

• comparator mismatch a valid metric can still produce confusing output if the configured comparator/target pair does not match the metric’s real type

• policy drift species-account policy changes can alter the generated invariant set even when the hand-authored spec itself did not change

Cross-References

Guides and references that pair especially closely with this module:

• Rebuild Repro Contract

• How to Interpret Rebuild Reports and Regressions

• How to Author a New Instance Rebuild Spec

Related API pages:

• femic.rebuild_baseline Module

• femic.rebuild_spec Module

• femic.rebuild_runner Module

Invariant metric extraction and evaluation for instance rebuild runs.

class femic.rebuild_invariants.InvariantResult(invariant_id, severity, metric, comparator, target, measured, status, remediation, message)

Bases: object

Evaluation outcome for a single configured invariant.

Parameters:

• invariant_id (str)

• severity (str)

• metric (str)

• comparator (str)

• target (Any)

• measured (Any)

• status (str)

• remediation (str | None)

• message (str)

comparator: str

invariant_id: str

measured: Any

message: str

metric: str

remediation: str | None

severity: str

status: str

target: Any

femic.rebuild_invariants.append_invariant_payload_to_report(*, report_path, metrics, invariant_results)

Append metrics + invariant results to existing rebuild report JSON.

Parameters:

• report_path (Path)

• metrics (dict[str, Any])

• invariant_results (list[InvariantResult])

Return type:

None

femic.rebuild_invariants.build_species_account_policy_invariants(policy)

Build invariant entries from runtime species-account policy config.

Parameters:

policy (dict[str, Any] | None)

Return type:

list[dict[str, Any]]

femic.rebuild_invariants.collect_rebuild_metrics(*, instance_root, log_dir, run_id, patchworks_config_path)

Collect known metric values used by rebuild-spec invariants.

Parameters:

• instance_root (Path)

• log_dir (Path)

• run_id (str)

• patchworks_config_path (Path | None)

Return type:

dict[str, Any]

femic.rebuild_invariants.evaluate_invariants(*, invariants, metrics)

Evaluate configured invariants against measured metrics.

Parameters:

• invariants (list[dict[str, Any]])

• metrics (dict[str, Any])

Return type:

list[InvariantResult]

femic.rebuild_invariants.has_fatal_invariant_failures(results)

Return true when any invariant has fatal failure status.

Parameters:

results (list[InvariantResult])

Return type:

bool

femic.rebuild_invariants.serialize_invariant_results(results)

Convert dataclass results to JSON-serializable dictionaries.

Parameters:

results (list[InvariantResult])

Return type:

list[dict[str, Any]]