cadrumo.core.validity_window module

Closed validity windows for registry records that carry their own grounding.

A registry corpus that lives outside a modelo revision has no revision window to inherit, so a record in one states the span it is asserted over itself. ValidityWindow is that statement, and it is deliberately narrow: two inclusive dates, both required.

Why both bounds are required, and why neither may be open. An omissible start sorts as datetime.date.min in every ordering helper that has ever been written for this shape, so the first undated row written after any dated one persists without error and never resolves as effective again – a partial adoption that does not announce itself. An omissible end is worse in a different way: it silently converts “grounded for the years I read” into “grounded until further notice”, which is exactly the claim a registry record must never make by default. Requiring both makes the span an assertion the author had to type, and therefore one a gate can hold them to.

A window is a grounding claim, not a convenience. The span says the cited evidence supports the record across it. Widening one is not a formatting change; it is a new claim about the law, and the gates that read these windows treat it that way.

The type carries no notion of “now” and no clock. Coverage is asked as a question about a filing year, because that is the axis the registry corpora are selected on.

class ValidityWindow(**data)

Bases: BaseModel

The closed, inclusive date span over which a grounded record is asserted.

Variables:

• valid_from – First date the record is asserted to hold. Required.

• valid_to – Last date the record is asserted to hold, inclusive. Required.

Parameters:

data (Any)

valid_from: date

valid_to: date

covers(moment)

Return whether moment falls inside the closed span.

Return type:

bool

Returns:

True when moment is on or after valid_from and on or before valid_to.

Parameters:

moment (date)

covers_year(year)

Return whether the span overlaps any part of the filing year.

Overlap rather than containment is the right question: a provision that takes effect in July is in force for that filing year, and a window clipped to its own effective date would otherwise report the year uncovered.

Return type:

bool

Returns:

True when the span intersects year.

Parameters:

year (int)

years()

Return every filing year the span touches, ascending.

Return type:

tuple[int, ...]

Returns:

The years from valid_from to valid_to inclusive.

years_covered_by_any(windows)

Return every filing year at least one window touches.

Return type:

frozenset[int]

Returns:

The union of each window’s ValidityWindow.years().

Parameters:

windows (Iterable[ValidityWindow])

years_covered_by_every_group(groups)

Return the years every group covers with at least one of its windows.

A corpus is resolvable for a year only when each of its grounded records has evidence for that year, so the corpus-level answer is an intersection of per-record unions rather than one flat union. A single record whose evidence stops earlier stops the whole corpus, which is the honest reading: the corpus cannot be assembled for that year.

An empty group contributes no years and therefore empties the result, which is correct – a record with no window at all is grounded nowhere. An empty sequence of groups yields the empty set rather than “everything”.

Return type:

frozenset[int]

Returns:

The intersection across groups of the years each group covers.

Parameters:

groups (Iterable[Iterable[ValidityWindow]])