femic.rebuild_baseline Module

The femic.rebuild_baseline module owns FEMIC’s structural baseline snapshot and diff contract for instance rebuild runs. It resolves where the baseline snapshot should live, captures the current normalized Patchworks/XML and tracks-table state, loads and saves baseline JSON payloads, and computes the structural diff summary later used by regression gating.

If you are debugging why a rebuild baseline did or did not match, what FEMIC actually snapshots for comparison, or how baseline/allowlist drift is turned into machine-readable evidence, this is the first module to read. In practice it owns:

  • baseline snapshot path resolution

  • normalized current-state snapshot building

  • JSON load/save for baseline payloads

  • structural diff summaries between baseline and current state

Start Here If…

Use this page first if you are trying to:

  • understand what config/rebuild.baseline.json is meant to contain

  • inspect why a rebuild report shows baseline drift

  • trace which Patchworks/XML and track-table structures are compared

Typical maintenance path:

  1. Start with resolve_baseline_path() for path/instance-root questions.

  2. Read build_current_snapshot() for snapshot content questions.

  3. Move to diff_snapshots() when debugging baseline mismatch output.

Typical Usage

The common baseline workflow is:

from pathlib import Path
from femic.rebuild_baseline import build_current_snapshot, diff_snapshots, load_snapshot

baseline = load_snapshot(Path("config/rebuild.baseline.json"))
current = build_current_snapshot(
    patchworks_config_path=Path("config/patchworks.runtime.windows.yaml"),
)
diff = diff_snapshots(baseline=baseline, current=current)

How This Fits Into The Pipeline

This module sits beside rebuild execution and invariant evaluation:

  1. rebuild workflows resolve the baseline path for the active instance

  2. this module builds the current normalized snapshot

  3. baseline and current snapshots are compared and folded into the rebuild evidence/report flow

That makes this module the source-of-truth for baseline structural comparison, not the broader rebuild-step orchestration.

Key Entry Surfaces

The highest-value entrypoints in this module are:

  • resolve_baseline_path()

  • build_current_snapshot()

  • load_snapshot()

  • save_snapshot()

  • diff_snapshots()

  • load_diff_allowlist()

Core Contracts

The most important runtime contracts in this module are:

  • the default baseline path is config/rebuild.baseline.json relative to the active instance root

  • snapshots normalize the key Patchworks XML summary and track-table hash/row count surfaces rather than storing arbitrary raw files

  • diffs are structural summaries intended for regression gating, not full file patches

  • allowlists can be layered on top of diff results to accept intentional drift

Failure Seams To Watch

The common failure boundaries in this module are:

  • wrong baseline path assumptions relative baseline paths are resolved against the instance root, not the repo root by default

  • incomplete runtime outputs snapshot building depends on Patchworks config/model outputs being present

  • false-positive drift baseline mismatch can come from stale baselines or allowlists rather than true regressions in the current run

Cross-References

Guides and references that pair especially closely with this module:

Related API pages:

Baseline snapshot + diff helpers for instance rebuild regression checks.

femic.rebuild_baseline.apply_diff_allowlist(*, diff_payload, allowlist_payload)[source]

Filter diffs through explicit allowlist and report unexpected deltas.

Parameters:

  • diff_payload (dict[str, Any])

  • allowlist_payload (dict[str, Any])

Return type:

dict[str, Any]

femic.rebuild_baseline.build_current_snapshot(*, patchworks_config_path)[source]

Build normalized snapshot payload for key track/XML structures.

Parameters:

patchworks_config_path (Path)

Return type:

dict[str, Any]

femic.rebuild_baseline.diff_snapshots(*, baseline, current)[source]

Return structural diff summary between baseline and current snapshots.

Parameters:

  • baseline (dict[str, Any])

  • current (dict[str, Any])

Return type:

dict[str, Any]

femic.rebuild_baseline.load_diff_allowlist(path)[source]

Load optional YAML/JSON allowlist rules for intentional diffs.

Parameters:

path (Path)

Return type:

dict[str, Any]

femic.rebuild_baseline.load_snapshot(path)[source]

Load a baseline snapshot JSON payload.

Parameters:

path (Path)

Return type:

dict[str, Any]

femic.rebuild_baseline.resolve_baseline_path(*, baseline_path, instance_root)[source]

Resolve baseline path against instance root when relative.

Parameters:

  • baseline_path (Path | None)

  • instance_root (Path)

Return type:

Path

femic.rebuild_baseline.save_snapshot(*, path, snapshot)[source]

Persist snapshot JSON payload (creating parent directories if needed).

Parameters:

  • path (Path)

  • snapshot (dict[str, Any])

Return type:

None