cadrumo.domain.calculations.registry.facts.schema module¶

Closed schema contracts for registry-governed facts.

TAGGED_FACT_ATOM_CONTEXT: Final¶: Validation-context key a reader sets when every non-string fact atom arrives in its tagged JSON form. JSON carries a decimal or a date only as a string, which the FactAtom union would read back as text; the tag keeps the type.

tagged_fact_atom_json(value)[source]¶

Return the lossless JSON form of one fact atom.

A string stays a bare JSON string. Every other atom becomes a single-key object naming its type: {"$decimal": "0.40"}, {"$date": "2025-01-01"}, {"$int": 5} and {"$bool": true}. None stays null.

Return type:: object
Parameters:: value (str | int | Decimal | bool | date | None)

class GovernedFactFamily(*values)[source]¶

Bases: StrEnum

The complete set of payload semantics admitted by the facts registry.

SCALAR¶

BRACKET¶

MAPPING¶

ENTITY_SET¶

OVERRIDE¶

EVENT¶

MULTI_OUTPUT¶

class FactOwnership(*values)[source]¶

Bases: StrEnum

Whether a variant is reviewed source data or a reproducible projection.

AUTHORED¶

GENERATED¶

class FactSelector(**data)[source]¶

Bases: RegistryModel

One typed, exact-match coordinate of a governed variant.

Parameters:

name (str)
value_type (Literal['decimal'] | None)
value (Annotated[str | int | Decimal | bool | date, BeforeValidator(func=~cadrumo.domain.calculations.registry.facts.schema._hydrate_tagged_fact_atom, json_schema_input_type=PydanticUndefined)])

name: str¶

value_type: Literal['decimal'] | None¶

value: FactAtomField¶

class NamedFactValue(**data)[source]¶

Bases: RegistryModel

A named typed result used by mapping and multi-output payloads.

Parameters:: data (Any)

name: str¶

value: FactAtomField¶

unit: str | None¶

class ScalarFactPayload(**data)[source]¶

Bases: RegistryModel

One typed scalar value.

Parameters:

kind (Literal[GovernedFactFamily.SCALAR])
value_type (Literal['decimal'] | None)
value (Annotated[str | int | Decimal | bool | date, BeforeValidator(func=~cadrumo.domain.calculations.registry.facts.schema._hydrate_tagged_fact_atom, json_schema_input_type=PydanticUndefined)])
unit (str)

kind: Literal[GovernedFactFamily.SCALAR]¶

value_type: Literal['decimal'] | None¶

value: FactAtomField¶

unit: str¶

class BracketFactRow(**data)[source]¶

Bases: RegistryModel

One half-open numeric band and its scalar result.

Parameters:: data (Any)

lower_bound: DecimalValue¶

upper_bound: DecimalValue | None¶

value: DecimalValue¶

class BracketFactPayload(**data)[source]¶

Bases: RegistryModel

An ordered, non-overlapping numeric bracket schedule.

Parameters:: data (Any)

kind: Literal[GovernedFactFamily.BRACKET]¶

unit: str¶

brackets: tuple[BracketFactRow, ...]¶

class MappingFactEntry(**data)[source]¶

Bases: RegistryModel

One exact key-to-value mapping entry.

Parameters:: data (Any)

key: FactAtomField¶

value_type: Literal['decimal'] | None¶

value: FactAtomField¶

class MappingFactPayload(**data)[source]¶

Bases: RegistryModel

A typed finite mapping whose keys remain explicit schema data.

Parameters:: data (Any)

kind: Literal[GovernedFactFamily.MAPPING]¶

entries: tuple[MappingFactEntry, ...]¶

class EntitySetFactPayload(**data)[source]¶

Bases: RegistryModel

A closed set of stable entity tokens.

Parameters:: data (Any)

kind: Literal[GovernedFactFamily.ENTITY_SET]¶

entities: EntitySetField¶

class OverrideFactPayload(**data)[source]¶

Bases: RegistryModel

A result that supersedes named variants under explicit selectors.

Parameters:: data (Any)

kind: Literal[GovernedFactFamily.OVERRIDE]¶

override_code: str¶

value: OptionalFactAtomField¶

unit: str | None¶

class EventFactPayload(**data)[source]¶

Bases: RegistryModel

A legally meaningful event with optional structured outputs.

Parameters:: data (Any)

kind: Literal[GovernedFactFamily.EVENT]¶

event_date: date¶

event_code: str¶

outputs: tuple[NamedFactValue, ...]¶

class MultiOutputFactRow(**data)[source]¶

Bases: RegistryModel

One numeric band producing several named values together.

Parameters:: data (Any)

lower_bound: DecimalValue¶

upper_bound: DecimalValue | None¶

outputs: tuple[NamedFactValue, ...]¶

class MultiOutputFactPayload(**data)[source]¶

Bases: RegistryModel

A band schedule whose match returns more than one named result.

Parameters:: data (Any)

kind: Literal[GovernedFactFamily.MULTI_OUTPUT]¶

bands: tuple[MultiOutputFactRow, ...]¶

class GovernedFactVariant(**data)[source]¶

Bases: RegistryTemporalDeltaDeclaration

One evidence-bearing fact revision on an exact semantic track.

variant_id is the stable revision identity. Bounds are delta-authored against the registry’s single filing-year support envelope: an explicit date is a legal endpoint and nothing projects past it, the first variant of a track may omit its lower endpoint to reach the envelope floor, and an omitted upper endpoint stays open up to the envelope ceiling.

Parameters:

valid_from (date | None)
valid_to (date | None)
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)
variant_id (RegistryRevisionNodeId)
selectors (tuple[FactSelector, ...])
date_axis (Annotated[DateAxis, BeforeValidator(func=~cadrumo.domain.calculations.registry.schema_base.coerce_enum_member.<locals>._coerce, json_schema_input_type=PydanticUndefined)])
payload (Annotated[ScalarFactPayload | BracketFactPayload | MappingFactPayload | EntitySetFactPayload | OverrideFactPayload | EventFactPayload | MultiOutputFactPayload, FieldInfo(annotation=NoneType, required=True, discriminator='kind')])
legal_refs (tuple[LegalRefId, ...])
source_refs (tuple[SourceRefId, ...])
source_citations (tuple[SourceCitation, ...])
review_status (Annotated[RevisionReviewStatus, BeforeValidator(func=~cadrumo.domain.calculations.registry.schema_base._coerce_revision_review_status, json_schema_input_type=PydanticUndefined)])
ownership (Annotated[FactOwnership, BeforeValidator(func=~cadrumo.domain.calculations.registry.schema_base.coerce_enum_member.<locals>._coerce, json_schema_input_type=PydanticUndefined)])
source_revision_ids (tuple[RevisionId, ...])
precedence_over (tuple[RegistryRevisionNodeId, ...])

variant_id: RegistryRevisionNodeId¶

selectors: tuple[FactSelector, ...]¶

date_axis: DateAxisField¶

payload: FactPayload¶

legal_refs: tuple[LegalRefId, ...]¶

source_refs: tuple[SourceRefId, ...]¶

source_citations: tuple[SourceCitation, ...]¶

review_status: RevisionReviewStatusField¶

ownership: FactOwnershipField¶

source_revision_ids: tuple[RevisionId, ...]¶

precedence_over: tuple[RegistryRevisionNodeId, ...]¶

revision_identity()[source]¶

Return the stable fact revision identity used by shared predecessor mechanics.

Return type:: str

class GovernedFact(**data)[source]¶

Bases: RegistryModel

A stable semantic fact and all legally distinct variants of that fact.

Parameters:

fact_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128), _PydanticGeneralMetadata(pattern='^[a-z0-9][a-z0-9._:-]*[a-z0-9]$|^[a-z0-9]$')])])
family (Annotated[GovernedFactFamily, BeforeValidator(func=~cadrumo.domain.calculations.registry.schema_base.coerce_enum_member.<locals>._coerce, json_schema_input_type=PydanticUndefined)])
provider_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128), _PydanticGeneralMetadata(pattern='^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$')])] | None)
variants (tuple[GovernedFactVariant, ...])

fact_id: FactId¶

family: GovernedFactFamilyField¶

provider_id: FactProviderId | None¶

variants: tuple[GovernedFactVariant, ...]¶

validity_window(variant, support=None)[source]¶

Materialise one variant’s authored or floor-propagated endpoints.

Return type:

RegistryValidityWindow

Parameters:

variant (GovernedFactVariant)
support (DateSupportEnvelope | None)

static track_key(variant)[source]¶

Return the exact axis, selector, and typed-period identity of a revision track.

Return type:: tuple[object, ...]
Parameters:: variant (GovernedFactVariant)

materialized_windows(support=None)[source]¶

Resolve delta-authored bounds against the registry support envelope.

Explicit endpoints are retained verbatim. The one variant per track that omits valid_from reaches the envelope floor; without an envelope (the structural validation of a single component) it reaches the earliest representable date, which orders it first without inventing a floor.

Return type:: Mapping[TypeAliasType, RegistryValidityWindow]
Parameters:: support (DateSupportEnvelope | None)

class GovernedFactCatalogue(**data)[source]¶

Bases: RegistryModel

Governed facts keyed by their stable semantic identity.

Parameters:: facts (Annotated[Mapping[Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128), _PydanticGeneralMetadata(pattern='^[a-z0-9][a-z0-9._:-]*[a-z0-9]$|^[a-z0-9]$')])], GovernedFact], <cadrumo.core.frozen_mapping.FrozenMappingMarker object at 0x7f8c00a93860>])

facts: Annotated[Mapping[FactId, GovernedFact], FROZEN_MAPPING]¶