cadrumo.domain.modelos.calculation_revision_identity module

Private canonicalization and hashing mechanics for calculation revisions.

The public construction and derivation functions remain canonical in cadrumo.domain.modelos.calculation_revision. This module owns only the private deterministic projections they use.

canonical_row_binding_values(row_binding_values, *, surface)

Return row-binding values with validated keys, canonically sorted, or raise.

Return type:

dict[TypeAliasType, dict[str, str]]

Parameters:

• row_binding_values (Mapping[object, object])

• surface (str)

canonical_row_source_identities(value)

Return row source identities as canonically sorted, JSON-shaped rows.

Return type:

list[dict[str, object]]

Parameters:

value (Mapping[RowBindingKey, RowSourceIdentity])

canonical_row_casilla_values(value)

Return row casilla values as canonically sorted, JSON-shaped rows.

Return type:

list[dict[str, object]]

Parameters:

value (Mapping[RowCasillaKey, Decimal])

canonical_row_casilla_provenance(value)

Return row casilla materialization provenance as canonically sorted, JSON-shaped rows.

Return type:

list[dict[str, object]]

Parameters:

value (Mapping[RowCasillaKey, DirectRowMaterializationProvenance])

derive_calculation_revision_id_from_identity_inputs(identity_inputs)

Hash a value returned only by calculation_revision_identity_inputs().

The id is content-addressed by the parent work unit plus the three payload mappings: input casilla values, scalar binding overrides, and computed casilla outputs. Row-indexed binding values are carried as their own nested map so repeating-record coordinates participate in identity without being flattened into synthetic binding ids. Two structurally identical re-runs produce the same id; the catalogue’s content-addressing invariant then makes a second calculate call idempotent (the existing revision is returned, no duplicate is persisted).

detail_rows carries typed row observations for informational modelos (M184, M232) that declare row-producer bindings. When rows are present they are serialised into the hash so structurally identical re-runs with the same rows produce the same id.

source_issues carries unresolved source conditions that block verification. It participates in identity so distinct resolution outcomes cannot collapse to one revision. Typed filing-instance evidence likewise participates, so changing Modelo 303 joint-return or insolvency facts creates a distinct immutable revision rather than mutating a draft.

Return type:

str

Parameters:

identity_inputs (CalculationRevisionIdentityInputs)

outputs_for_hash_from_mapping(casilla_values)

Canonical {casilla_id: canonical_decimal_str} projection from the flat mapping.

Pure function — same input → same output, no side effects, no dependence on observation order. Used by derive_calculation_revision_id() to produce the outputs payload key consumed by the SHA-256 hash, AND by outputs_for_hash_from_observations() to project the typed envelope into the same canonical form so the validator’s consistency check is byte-exact.

Validated casilla_id keys, _canonical_decimal values, sorted by casilla_id — matches the original inline projection in derive_calculation_revision_id() byte-for-byte. The A hash-stability contract guards this projection.

Return type:

dict[TypeAliasType, str]

Parameters:

casilla_values (Mapping[CasillaId, Decimal])

outputs_for_hash_from_observations(observations)

Same canonical projection as outputs_for_hash_from_mapping(), sourced from observations.

The typed observations envelope is the logical source of truth for derivation. This helper materialises the same {casilla_id: canonical_decimal_str} projection the flat-mapping helper produces, sourced from CasillaObservation.value. The validator uses this to assert the persisted casilla_values field is byte-identical to the projection of observations.

A future cycle drops the flat field and routes the hash directly through this helper; currently both fields are kept and this helper is used for the consistency check only.

Core types: CasillaObservation.

Return type:

dict[TypeAliasType, str]

Parameters:

observations (Sequence[CasillaObservation])