cadrumo.domain.calculations.registry.keyed_families module

The canonical policy for revision declaration-family inheritance.

SCHEMA_FAMILY answers a coverage question: which revision fields are collections of typed declarations. It deliberately does not answer the different question of whether a successor may omit one of those declarations and inherit it from its predecessor. Keeping that second decision here gives the compiler, the migration authoring tool, and the delta signal one vocabulary for the union rule.

The table is intentionally dependency-light. It does not import ModeloRevision (which imports the restated-family schema), so the domain schema can import this module without a cycle. Consumers validate the table against their local schema-family census where they have that schema available.

ROW_SOURCE_FIELD: Final[str]

The member field carrying a row’s own source grounding.

ROW_SOURCE_ADDITIONS_FIELD: Final[str]

The member field extending, rather than replacing, its family’s edition default.

class FamilyInheritanceMode(*values)[source]

Bases: StrEnum

How a revision family participates in predecessor materialisation.

CASILLA

Casillas use continuity lineage rather than a member-owned id and need their own merge for locale and row-attestation handling.

KEYED

A collection whose members are joined by the declared identity.

PER_EDITION

A declaration about the edition’s own generated/evidence surface.

NONE

A typed family that is intentionally full-copy for now.

class KeyedFamilySpec(section, identity, storage_identity='id', identity_fields=(), casilla_identity_fields=(), period_scoped=False, inheritance=FamilyInheritanceMode.KEYED, restatable=True, drop_eligible=False, source_default_key=None, holdback_reason=None, schema_family=True, scoped=False, singleton=False)[source]

Bases: object

Immutable policy for one declaration family.

identity is retained even for a NONE/PER_EDITION family when the schema has one. That lets diagnostics report the family accurately without accidentally enrolling it in the predecessor union. The inheritance mode, not the presence of an id, is the enrolment decision.

Parameters:
section: str
identity: str | None
storage_identity: str

Edition-local key used only to address a member in the immediately declared predecessor for lossless storage patches. This is deliberately separate from semantic continuity: for casillas it is id, not continuidad_id.

identity_fields: tuple[str, ...]
casilla_identity_fields: tuple[str, ...]

Identity fields that name edition-local casillas; compare their declared continuity rather than mistaking a printed-number change for repurposing.

period_scoped: bool
inheritance: FamilyInheritanceMode
restatable: bool

Whether a typed restated_families declaration is meaningful. The casilla merge is inherited but does not yet honour that manifest list.

drop_eligible: bool

Whether the migration drop operation may remove an identical member. Conditional period-scoped inheritance is deliberately not droppable.

source_default_key: str | None

Manifest field paired with a family’s shared source_refs run, when that family has one. This does not itself enroll a family.

holdback_reason: str | None

Reason shown when a family is intentionally not droppable/inheritable.

schema_family: bool

Whether the family is a ModeloRevision SCHEMA_FAMILY field.

scoped: bool

Whether each edition must explicitly assert that an edition-local claim applies.

singleton: bool

Whether the raw family is one table rather than an array of tables.

property inherited: bool

Whether the loader carries members from a predecessor.

property keyed: bool

Whether the generic identity union, rather than casilla merge, applies.

family_identity_value(member, path)[source]

Read one identity-bearing field, including a dotted nested path.

Authoring and compiler boundaries carry raw TOML mappings, while focused callers may hold typed registry models. Resolve both shapes without coercing the value: identity comparisons must distinguish missing values, enums, and scalar values exactly as their source declared them.

Return type:

object

Parameters:
family_spec(section)[source]

Return the canonical policy for section, if it is known.

Return type:

KeyedFamilySpec | None

Parameters:

section (str)

family_source_default_fields(*, include_casillas=False)[source]

Return each family paired with the manifest field carrying its source_refs default.

The pairing lives on CANONICAL_FAMILY_SPECS so a family can never be defaulted from another family’s grounding, and so enrolling one is adding its source_default_key rather than extending a second table that has to be kept in step. Casillas are excluded by default because their default is applied by the casilla rule, which also fills legal_refs from the edition’s approving ordenes and defaults a row’s constraints table.

Return type:

tuple[tuple[str, str], ...]

Parameters:

include_casillas (bool)

bound_family_source_refs(default, additions)[source]

Return the edition default followed by a member’s additions, each reference once.

The default comes first and duplicates are dropped, so a member extending its edition’s grounding reads as that grounding plus what it adds. Values are carried through uncoerced: a malformed default or addition reaches typed construction and is refused there with the field’s own error rather than being silently repaired here.

Return type:

tuple[object, ...]

Parameters:
inline_family_source_default(member, edition, default_key)[source]

Return member with its family’s edition-level source_refs default bound onto it.

One rule, shared by every consumer that has to reason about what a member’s grounding EFFECTIVELY is: the compiler, which pins an inherited member to the default effective where it was stated; the delta signal, which must not report a field difference that is only the two editions’ defaults; and the migration chain proof, whose equivalence claim is about meaning rather than physical representation. A second implementation of it would let those three disagree about what a registry says.

A member stating its own source_refs replaces the default whole and is returned unchanged, as is one whose family has no default key or whose edition declares no usable default. Otherwise the member takes the default, extended by any additional_source_refs it states, and the additions key is consumed. member itself is returned when nothing is bound, so a caller can test identity to learn whether the edition changed anything.

Return type:

Mapping[str, object]

Parameters: