cadrumo.domain.calculations.registry.facts.resolution module

Typed query and provenance-bearing result contracts for governed facts.

class ScalarFactQuery(**data)[source]

Bases: _FactQuery

Select one scalar fact variant at an exact temporal coordinate.

Parameters:

data (Any)

family: Literal[GovernedFactFamily.SCALAR]
class BracketFactQuery(**data)[source]

Bases: _FactQuery

Select one bracket fact variant at an exact temporal coordinate.

Parameters:

data (Any)

family: Literal[GovernedFactFamily.BRACKET]
class MappingFactQuery(**data)[source]

Bases: _FactQuery

Select one mapping fact variant at an exact temporal coordinate.

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]$')])])

  • date_axis (Annotated[DateAxis, BeforeValidator(func=~cadrumo.domain.calculations.registry.schema_base.coerce_enum_member.<locals>._coerce, json_schema_input_type=PydanticUndefined)])

  • effective_date (date)

  • selectors (tuple[FactSelector, ...])

  • filing_year (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=2000), Le(le=2099)])] | None)

  • period (Annotated[str, BeforeValidator(func=~cadrumo.core.period._validate_registry_selector_period, json_schema_input_type=PydanticUndefined)] | None)

  • family (Literal[GovernedFactFamily.MAPPING])

family: Literal[GovernedFactFamily.MAPPING]
class EntitySetFactQuery(**data)[source]

Bases: _FactQuery

Select one entity-set fact variant at an exact temporal coordinate.

Parameters:

data (Any)

family: Literal[GovernedFactFamily.ENTITY_SET]
class OverrideFactQuery(**data)[source]

Bases: _FactQuery

Select one explicit override variant at an exact temporal coordinate.

Parameters:

data (Any)

family: Literal[GovernedFactFamily.OVERRIDE]
class EventFactQuery(**data)[source]

Bases: _FactQuery

Select one governed event variant at an exact temporal coordinate.

Parameters:

data (Any)

family: Literal[GovernedFactFamily.EVENT]
class MultiOutputFactQuery(**data)[source]

Bases: _FactQuery

Select one multi-output fact variant at an exact temporal coordinate.

Parameters:

data (Any)

family: Literal[GovernedFactFamily.MULTI_OUTPUT]
class ResolvedScalarFact(**data)[source]

Bases: _ResolvedFact

A resolved scalar payload with its complete authority context.

Parameters:

data (Any)

family: Literal[GovernedFactFamily.SCALAR]
payload: ScalarFactPayload
class ResolvedBracketFact(**data)[source]

Bases: _ResolvedFact

A resolved bracket payload with its complete authority context.

Parameters:

data (Any)

family: Literal[GovernedFactFamily.BRACKET]
payload: BracketFactPayload
class ResolvedMappingFact(**data)[source]

Bases: _ResolvedFact

A resolved mapping payload with its complete authority context.

Parameters:

data (Any)

family: Literal[GovernedFactFamily.MAPPING]
payload: MappingFactPayload
class ResolvedEntitySetFact(**data)[source]

Bases: _ResolvedFact

A resolved entity-set payload with its complete authority context.

Parameters:

data (Any)

family: Literal[GovernedFactFamily.ENTITY_SET]
payload: EntitySetFactPayload
class ResolvedOverrideFact(**data)[source]

Bases: _ResolvedFact

A resolved override payload with its complete authority context.

Parameters:

data (Any)

family: Literal[GovernedFactFamily.OVERRIDE]
payload: OverrideFactPayload
class ResolvedEventFact(**data)[source]

Bases: _ResolvedFact

A resolved event payload with its complete authority context.

Parameters:

data (Any)

family: Literal[GovernedFactFamily.EVENT]
payload: EventFactPayload
class ResolvedMultiOutputFact(**data)[source]

Bases: _ResolvedFact

A resolved multi-output payload with its complete authority context.

Parameters:

data (Any)

family: Literal[GovernedFactFamily.MULTI_OUTPUT]
payload: MultiOutputFactPayload
required_mapping_entry(entries, key, *, subject)[source]

Return the stripped value of one required mapping-fact entry.

subject names the mapping in the refusal, so each consumer keeps its own diagnostic wording.

Raises:

RegistryValidationError – When key is absent or blank.

Return type:

str

Parameters:
unique_mapping_tokens(entries, key, *, subject, requirement='must contain unique tokens')[source]

Return the stripped, non-empty comma-separated tokens of one required entry.

subject and requirement word the refusal, so each consumer keeps its own diagnostic.

Raises:

RegistryValidationError – When the entry is absent or blank, yields no token, or repeats a token.

Return type:

tuple[str, ...]

Parameters:
resolve_governed_fact(catalogue, query, *, authority_digest, support)[source]

Resolve one query through the variant window containing it.

Return type:

ResolvedScalarFact | ResolvedBracketFact | ResolvedMappingFact | ResolvedEntitySetFact | ResolvedOverrideFact | ResolvedEventFact | ResolvedMultiOutputFact

Parameters:
resolve_validated_governed_fact(fact, query, *, authority_digest, support)[source]

Resolve one query from an already validated immutable fact.

Published component readers validate a governed fact while decoding its content-addressed component. Runtime point reads must not wrap that model in a new GovernedFactCatalogue and validate the same static graph again for every temporal query.

support is the registry’s single filing-year envelope, the same one that gates modelo revisions: a coordinate outside it is refused, a first variant omitting valid_from reaches its floor, and an open final variant carries past its horizon. An explicit endpoint is a legal boundary, so a coordinate in a gap between explicit windows resolves to nothing rather than to the nearest variant.

Return type:

ResolvedScalarFact | ResolvedBracketFact | ResolvedMappingFact | ResolvedEntitySetFact | ResolvedOverrideFact | ResolvedEventFact | ResolvedMultiOutputFact

Parameters: