femic.rebuild_spec Module

The femic.rebuild_spec module owns FEMIC’s rebuild-spec loading and schema-style validation contract. It turns config/rebuild.spec.yaml into a validated mapping, enforces the allowed root/step/invariant structure, and is the code-level gate that keeps instance rebuild flows deterministic and auditable rather than loosely scripted.

If you are debugging why femic instance validate-spec rejects a rebuild spec, which comparators or step kinds are allowed, or how FEMIC decides whether an instance spec is structurally valid before a rebuild run starts, this is the first module to read. In practice it owns:

  • YAML rebuild-spec loading

  • required root/step/invariant key validation

  • allowed enum-style values for step kinds, severities, and comparators

  • uniqueness and dependency-reference validation for step and invariant ids

Start Here If…

Use this page first if you are trying to:

  • author or debug config/rebuild.spec.yaml

  • understand the minimum schema FEMIC expects for deterministic instance rebuilds

  • inspect why a spec fails validation before any actual rebuild step runs

Typical maintenance path:

  1. Start with load_rebuild_spec() for raw file-loading behavior.

  2. Move to validate_rebuild_spec_payload() for schema and rule failures.

  3. Inspect the module-level constants when extending the allowed schema.

Typical Usage

The usual maintenance flow is to validate the YAML payload before trying to run any rebuild steps:

from pathlib import Path
from femic.rebuild_spec import load_rebuild_spec, validate_rebuild_spec_payload

payload = load_rebuild_spec(Path("config/rebuild.spec.yaml"))
errors = validate_rebuild_spec_payload(payload)
assert not errors, errors

How This Fits Into The Pipeline

This module sits at the front of the rebuild workflow:

  1. instance-maintenance docs and templates define a rebuild spec

  2. CLI validation/rebuild commands load that spec through this module

  3. downstream rebuild execution, invariant evaluation, and evidence reporting only proceed once the spec passes structure validation

That means this module owns the spec structure contract, not the actual step execution or metric evaluation behavior.

Key Entry Surfaces

The highest-value entrypoints in this module are:

  • load_rebuild_spec()

  • validate_rebuild_spec_payload()

The main schema constants are also useful because they make the accepted surface explicit:

  • REBUILD_SPEC_REQUIRED_ROOT_KEYS

  • REBUILD_SPEC_REQUIRED_STEP_KEYS

  • REBUILD_SPEC_REQUIRED_INVARIANT_KEYS

  • ALLOWED_STEP_KINDS

  • ALLOWED_INVARIANT_SEVERITIES

  • ALLOWED_INVARIANT_COMPARATORS

Core Contracts

The most important runtime contracts in this module are:

  • rebuild specs must be YAML mappings with schema version 1.0

  • required root sections are instance, runtime, steps, and invariants

  • step IDs and invariant IDs must be unique

  • step dependency references must resolve to declared step IDs

  • runtime species-account policy fields must use the expected list structure

Failure Seams To Watch

The common failure boundaries in this module are:

  • malformed YAML root shape non-mapping root payloads fail immediately

  • schema drift undocumented new keys or values in rebuild specs will fail until validation rules are updated here

  • dependency/reference mistakes typos in depends_on or duplicate ids can look like runner bugs later if spec validation is skipped

Cross-References

Guides and references that pair especially closely with this module:

Related API pages:

Rebuild-spec loading and schema-style validation helpers.

femic.rebuild_spec.load_rebuild_spec(spec_path)[source]

Load a rebuild spec YAML file into a dictionary payload.

Parameters:

spec_path (Path)

Return type:

dict[str, Any]

femic.rebuild_spec.validate_rebuild_spec_payload(payload)[source]

Validate a rebuild spec payload and return human-readable errors.

Parameters:

payload (dict[str, Any])

Return type:

list[str]