gcubed.data.fiscal_contract

Validate in-memory generation contracts and safely bind legacy migration proof.

Source qualification stays in the data package. This module preserves its primitive receipt and checks immutable anchors, selected equations and exact legacy changes. Ordinary runtime CSV loading and conditioning do not read this source evidence or persist fiscal audits. Legacy decoding exists only for safe metadata retirement.

COMPANION_STATE_NAME = '__annual_fiscal_companion__'

STATE_COLUMNS = ('variable_name', 'year', 'original_value_text', 'last_applied_value_text')

def frame_digest(value: pandas.DataFrame) -> str:

Hash labelled values using the generation receipt's stable CSV representation.

def validate_fiscal_targets_receipt(receipt: dict) -> None:

Check the immutable P07 source-target schema and input identity, without refitting.

def validate_fiscal_receipt( receipt: dict, data: pandas.DataFrame, model_configuration: object, *, managed_records: list[dict] | None = None) -> None:

Validate source proof and final equations, allowing only recorded INTR changes.

Inputs are stored unlogged coordinates. Generation anchors remain immutable; conditioned anchors are derived from the exact persisted managed-cell records. Invalid or stale evidence raises ValueError without mutating the inputs.

def decode_fiscal_contract(contents: bytes) -> dict:

Decode the bounded primitive receipt; malformed evidence raises ValueError.

def current_database_digest(contents: bytes) -> str:

Bind CSV cells and metadata, masking only independently managed INTX year values.

Row presence, order, names, region, units and every column/year remain bound. Fiscal equations do not use INTX. The original whole-file hash remains separate.

def read_managed_records(path: pathlib.Path) -> list[dict]:

Read the existing four-column INTR state, including its reserved companion row.

Restore the process CSV limit after reading realistic source-evidence fields. Legacy states have no reserved row and remain valid four-column cell records.

def managed_cells_digest(records: list[dict]) -> str:

Bind ordinary cell changes separately from the companion row to avoid a hash cycle.

def companion_backup(records: list[dict]) -> tuple[bytes, str | None, str] | None:

Decode one reserved state row before ordinary coordinate restoration/counting.

def conditioning_records(receipt: dict, records: list[dict] | None = None) -> list[dict]:

Derive current anchors only from exact state records bound to original evidence.

def validate_legacy_fiscal_binding( database_path: pathlib.Path, model_configuration: object, managed_records: list[dict]) -> dict:

Validate historical CSV/managed proof before migration, without renewing sources.

Version-one and version-two proof can be retired even when its data sources have changed. Exact CSV, original-backup, marker and managed-cell bindings must still agree. This check establishes safe retirement, not economic acceptance.

def restore_legacy_intx( rows: list[list[str]], cells: list[dict], *, require_restored: bool = False) -> None:

Reconstruct an old exact-only CSV from bounded original INTX observation texts.

For cleanup, independent INTX numeric values must already equal the original; only representation is restored. Current masked companions need no such cells.