cadrumo.domain.calculations.registry.revision_contracts module

Shared temporal-delta and predecessor contracts for registry authorities.

Modelo editions and governed-fact revisions are two authored projections of the same mechanism: a revision has a scoped validity window and may name one sibling predecessor, explicitly declare a grounded root, or omit the key to remain a full copy. This module owns that mechanism once. Domain schemas add their payloads by subclassing RegistryRevisionDeclaration.

class DeclaredPredecessor(**data)[source]

Bases: RegistryModel

An explicit claim that a revision is authored relative to a sibling.

Parameters:

data (Any)

revision_id: RegistryRevisionNodeId
class NoPredecessorCause(*values)[source]

Bases: StrEnum

The closed set of grounded reasons a revision has no earlier sibling edition.

The reason prose of a NoPredecessor states the grounding in full and stays required; this token is the machine-readable classification of that same fact, so a census can answer which cause a root stands on without parsing prose. The set is closed: a root whose grounding is none of these is refused at the typed boundary rather than carried as a free-text token a later consumer would have to interpret.

predecessor_row_without_lineage

The earlier edition carries rows with no grounded continuity, so nothing can be inherited from it.

parallel_scheme_variants

The edition is one of several concurrent scheme variants, not a step in a sequence.

overlapping_predecessor

The candidate earlier edition’s validity scope overlaps this one, so neither strictly precedes the other.

forbidden_by_norm

The governing norm approves this edition independently, so no earlier edition is its authored basis.

lower_grade

Existing authored root pending source-data replanning; never inferred by migration or loading.

unretired_withdrawal

The earlier edition withdraws content without retiring it, so inheritance would carry withdrawn rows.

official_structure_differs

The official record structure is reordered or shifted, so supersede-in-place would not reproduce it.

class NoPredecessor(**data)[source]

Bases: RegistryModel

A grounded claim that a revision has no earlier sibling revision.

Parameters:

data (Any)

reason: str
legal_refs: LegalRefs
source_refs: SourceRefs
cause: Annotated[NoPredecessorCause | None, BeforeValidator(coerce_enum_member(NoPredecessorCause))]
class RegistryRevisionNode(**data)[source]

Bases: RegistryModel, ABC

Common predecessor-bearing node independent of identity/window spelling.

Concrete registries implement revision_identity(); this keeps the self-edge invariant in the base even when one schema spells the identity id and another spells it variant_id.

Parameters:

data (Any)

predecessor: Annotated[DeclaredPredecessorField | None, MANIFEST_ONLY]
abstractmethod revision_identity()[source]

Return the schema-specific identity of this revision node.

Return type:

str

class RegistryRevisionDeclaration(**data)[source]

Bases: RegistryRevisionNode, PeriodScopedValidityWindow

Common envelope for a period-scoped full-copy or delta revision.

Parameters:

predecessor (Annotated[Annotated[Annotated[DeclaredPredecessor, BeforeValidator(func=~cadrumo.domain.calculations.registry.revision_contracts._hydrate_declared_predecessor, json_schema_input_type=PydanticUndefined), Tag(tag=revision)] | Annotated[NoPredecessor, BeforeValidator(func=~cadrumo.domain.calculations.registry.revision_contracts._hydrate_no_predecessor, json_schema_input_type=PydanticUndefined), Tag(tag=none)], Discriminator(discriminator=~cadrumo.domain.calculations.registry.revision_contracts._predecessor_declaration_kind, custom_error_type=predecessor_kind, custom_error_message=predecessor must be the revision id of a sibling edition, or a single 'none' table grounding why no earlier sibling edition exists, custom_error_context=None)] | None, ManifestOnlyMarker()])

id: RevisionId
valid_to: Annotated[date | None, MANIFEST_ONLY]
revision_identity()[source]

Return the stable Modelo revision identity.

Return type:

str

class RegistryTemporalDeltaDeclaration(**data)[source]

Bases: RegistryRevisionNode, RegistryTemporalBounds

A predecessor-bearing delta with optional bounds and optional period scope.

Parameters:

predecessor (Annotated[Annotated[Annotated[DeclaredPredecessor, BeforeValidator(func=~cadrumo.domain.calculations.registry.revision_contracts._hydrate_declared_predecessor, json_schema_input_type=PydanticUndefined), Tag(tag=revision)] | Annotated[NoPredecessor, BeforeValidator(func=~cadrumo.domain.calculations.registry.revision_contracts._hydrate_no_predecessor, json_schema_input_type=PydanticUndefined), Tag(tag=none)], Discriminator(discriminator=~cadrumo.domain.calculations.registry.revision_contracts._predecessor_declaration_kind, custom_error_type=predecessor_kind, custom_error_message=predecessor must be the revision id of a sibling edition, or a single 'none' table grounding why no earlier sibling edition exists, custom_error_context=None)] | None, ManifestOnlyMarker()])

period_selector: PeriodSelector | None
class RevisionWindow(valid_from, valid_to, period_selector)[source]

Bases: object

The validity dates and period coordinate of one revision.

Parameters:
valid_from: date
valid_to: date | None
period_selector: PeriodSelector | None
class RevisionPredecessorProjection(named, declared_roots, keyless)[source]

Bases: object

The three declaration states projected from typed revisions.

Parameters:
named: Mapping[str, str]
declared_roots: frozenset[str]
keyless: frozenset[str]
project_predecessor_declarations(revisions)[source]

Project typed declarations once for forest validation and delta loading.

Return type:

RevisionPredecessorProjection

Parameters:

revisions (Mapping[str, RegistryRevisionNode])

validate_revision_predecessors(subject_id, revisions, *, windows=None, subject_kind='modelo', overlap_allows_parallel=True)[source]

Validate one revision map’s forest and materialized date direction.

Period-scoped concrete revisions need not pass windows. Delta schemas pass the windows produced by their shared materializer, keeping forest and date checks independent of how their optional bounds were authored.

Return type:

RevisionPredecessorProjection

Parameters:
validate_predecessor_forest(subject_id, *, named, declared_roots, keyless, subject_kind='modelo')[source]

Refuse predecessor declarations that do not form a rooted forest.

Return type:

None

Parameters:
validate_predecessor_date_agreement(subject_id, *, named, windows, subject_kind='modelo', overlap_allows_parallel=True)[source]

Refuse a predecessor that is not earlier when revision scopes do not overlap.

Return type:

None

Parameters: