cadrumo.domain.calculations.registry.binding_provider_registration module

The single enrollment authority joining a provider kind to everything it needs.

A provider kind used to be real only by agreement between three tables that could each be edited alone: a selector-model lookup, a validator lookup, and the application route table. Seven authored kinds proved the arrangement does not hold – they carried a model and a validator, reached calculation, and had no owner at all, visible only as an advisory diagnostic.

BINDING_PROVIDER_REGISTRATIONS replaces the agreement with one row per union member. The row carries the member’s model, its build-time validator, the value channels and aggregation operations the family can honour, the terminal origin classes it can produce, its output shape, its filing disposition, its route owner, and its authoring support. A kind is real when it has a row, and a row is complete or the module refuses to import.

Two ownership shapes exist because two honest answers exist. RouteOwnership names a resolver on the production calculation route – including the two pseudo-owners, which run no resolver class but are enrolled so that operator input and a diseño constant are not mistaken for unrouted sources. NonRuntimeOwnership names the absence of a route as a declaration: disposition = "deferred" with the reason written down, so a kind nobody routed is a stated gap rather than a silent zero.

The registration table lives in the domain because the declaration is domain authority; the route table lives in the application beside its resolvers. The join between them is therefore asserted where the dependency direction allows it – in the application module, which imports this one.

BindingRouteStage

A production calculation-route stage, spelled as the route table spells it.

alias of Literal[‘pre_mesh’, ‘mesh’, ‘conditional’, ‘post_mesh’, ‘manual’]

ProviderOutputShape

What a resolver for this kind can emit.

alias of Literal[‘scalar’, ‘rows’, ‘scalar_and_rows’]

ProviderDisposition

How much weight a value from this kind may carry in a filing.

alias of Literal[‘filing_grade’, ‘advisory’, ‘deferred’, ‘non_runtime’]

ProviderAuthoringSupport

How much help an author gets writing a row of this kind.

alias of Literal[‘scaffold’, ‘generator’, ‘none’]

class RouteOwnership(resolver_id, stage)[source]

Bases: object

The production calculation-route owner of one provider kind.

resolver_id and stage restate the route table’s own values so the domain can carry them without importing application code; the application asserts the restatement is true at its own import time, which is the only place both tables are visible at once.

Parameters:

  • resolver_id (str)

  • stage (Literal['pre_mesh', 'mesh', 'conditional', 'post_mesh', 'manual'])

resolver_id: str
stage: Literal['pre_mesh', 'mesh', 'conditional', 'post_mesh', 'manual']
class NonRuntimeOwnership(owner)[source]

Bases: object

The declared absence of a runtime owner for one provider kind.

owner states who or what stands in for a resolver: a pseudo-owner name for a kind that needs no aggregation, or the reason a route is deferred. Spelling the absence out is what keeps it out of the silent-gap category.

Parameters:

owner (str)

owner: str
class BindingProviderRegistration(kind, provider_model, validator, permitted_value_channels, permitted_aggregation_ops, permitted_terminal_origins, output, disposition, route, authoring)[source]

Bases: object

Everything that makes one provider kind real, in one row.

Parameters:
kind: BindingSourceKind
provider_model: type[BaseModel]
validator: TypeAliasType | None

The family’s build-time gate, or None when the union member is the whole gate.

A family whose only build-time invariant is its own provider shape needs no validator: the discriminated union has already constructed that member from the authored row, so re-validating the typed member against its own class can produce no diagnostic. None states that the member carries the gate, rather than dressing a no-op call up as one.

permitted_value_channels: frozenset[BindingValueChannel]
permitted_aggregation_ops: frozenset[BindingAggregationOp]
permitted_terminal_origins: frozenset[TerminalOriginClass]
output: Literal['scalar', 'rows', 'scalar_and_rows']
disposition: Literal['filing_grade', 'advisory', 'deferred', 'non_runtime']
route: TypeAliasType
authoring: Literal['scaffold', 'generator', 'none']
property names_source_casilla: bool

Return whether this kind’s provider member declares a source casilla coordinate.

Derived from the member’s own fields rather than restated as data, so a family cannot claim a coordinate its model does not carry. The typed source accessors read this to tell “this family has no source casilla” apart from “this family has one and the accessor forgot to narrow it”.

property names_source_modelo: bool

Return whether this kind’s provider member declares a source modelo coordinate.

property row_grouping: RowSetGroupingKind | None

Return the grouping axis this kind’s rows are assembled by, if any.

validate_binding_provider_registrations(registrations)[source]

Refuse an incomplete, duplicated, or self-contradicting registration table.

Returns the frozen kind-keyed view the accessors read, so the only way to obtain a usable table is to pass these checks.

Return type:

Mapping[BindingSourceKind, BindingProviderRegistration]

Parameters:

registrations (tuple[BindingProviderRegistration, ...])

BINDING_PROVIDER_REGISTRATIONS: Final[Mapping[BindingSourceKind, BindingProviderRegistration]]

The canonical enrollment authority, one row per provider union member.

AUTHORED_LAYOUT_INTEGER_FIELD_NAMES: Final[frozenset[str]]

Provider field names whose integer is a record-layout fact, not a filing coordinate.

offset, length and decimals describe where a value sits in an official fixed-width record and how it is written, which is authored design data that does not change with the filing context. Every other integer on a provider member would pin the declaration to one concrete year, revision, or date, and is refused. The list is explicit so that adding a fourth is a deliberate decision with a stated reason rather than a field that slipped through.

TEMPORAL_PROVIDER_FIELD_NAME: Final[str]

The one provider field allowed to carry numbers that move with the context.

The temporal union is where a relative coordinate is supposed to live: its members carry offsets and spans that are resolved against the target filing context. The guard therefore skips this field rather than descending into it.

absolute_coordinate_offenders(label, model)[source]

Return one diagnostic per field of model that pins a filing coordinate.

The walk descends into nested models, reporting a dotted field path, because a coordinate reached through a structured field is still a coordinate: a provider declaring window: Window where Window carries a year would otherwise pass a check that only ever looked one level down. The temporal field is skipped at every depth for the reason its own constant states, and each model is visited once so a self-referential shape terminates.

Both exemptions – the record-layout integer names and the temporal field – are granted to the PROVIDER MODEL ITSELF and to nothing below it. Each is a statement about one specific declared surface: offset on a provider is an authored fixed-width address, and temporal on a provider is the union built to carry relative coordinates. A field of the same name on some nested model is a different field with a different contract, and an exemption that followed the name down would let any nested structure re-admit an absolute coordinate by calling it offset.

Pure and model-agnostic, so the guard can be exercised against a fabricated provider class without touching the enrolled table.

Return type:

tuple[str, ...]

Parameters:

  • label (str)

  • model (type[BaseModel])

require_relative_provider_coordinates(registrations=None)[source]

Refuse any registered provider member that pins a concrete filing coordinate.

A binding declares timeless intent and derives its source coordinate from the target filing context at resolve time. The check is structural and runs over the models at import: it does not enumerate forbidden field names, so a newly added year, revision or date field is refused on the shape of its type rather than on whether anyone remembered to name it.

Raises:

RegistryValidationError – A registered provider member declares such a field.

Return type:

None

Parameters:

registrations (Mapping[BindingSourceKind, BindingProviderRegistration] | None)

registration_for(kind)[source]

Return the registration for one provider kind.

Raises:

RegistryValidationError – The kind is not a member of the provider union, which the discriminated union has already refused at construction; reaching this means a caller invented a kind.

Return type:

BindingProviderRegistration

Parameters:

kind (BindingSourceKind)

validator_for(kind)[source]

Return the build-time validator enrolled for one provider kind, if it has one.

None is the enrolled answer for a family whose provider member is its own complete gate, not a missing registration: a kind with no row cannot reach here at all.

Return type:

TypeAliasType | None

Parameters:

kind (BindingSourceKind)

provider_model_for(kind)[source]

Return the provider union member model enrolled for one provider kind.

Return type:

type[BaseModel]

Parameters:

kind (BindingSourceKind)

validate_binding_against_registration(binding)[source]

Return the diagnostics a binding earns against its kind’s registration.

Checks only what the registration is the authority for – the value channel, the aggregation operation, the scalar/rows agreement between the two, and the terminal-origin classes the family can actually produce. Provider shape stays with the family validator, which owns it.

The scalar/rows agreement is read off the EFFECTIVE operation (binding_aggregation_op()) rather than off the authored one, because that is the operation every row consumer dispatches on: a binding declaring the row_set channel and no aggregation takes the family default, which is not rows, and the row assemblers then pass it over – the casilla resolves to no rows at all rather than to a refusal. Gating the agreement on an authored aggregation block made omitting the block the way to escape it.

The permitted-operation check stays on the authored operation. The family default is a rows/not-rows marker rather than an authored intent – it answers sum for families whose registration permits only copy – so holding an undeclared binding to it would report the default table rather than the declaration.

Return type:

tuple[str, ...]

Parameters:

binding (BindingDefinition)