dev_agent
52895199be
Co-authored-by: dev_agent <dev_agent@cubecraftlabs.com> Co-committed-by: dev_agent <dev_agent@cubecraftlabs.com>
536 lines
22 KiB
Python
536 lines
22 KiB
Python
"""The materialization walk (Feature 07 core).
|
|
|
|
:func:`materialize` turns the schedule rules + custody presence of the
|
|
active quest definitions into concrete ``quest_instances`` rows over a
|
|
date range. It is the pure walk over definitions x dates x assignees x
|
|
windows; HA scheduling (day-rollover triggers) is a separate later
|
|
task and lives elsewhere.
|
|
|
|
The walk is deterministic and idempotent:
|
|
|
|
- All inputs — the active definitions with their rules, assignees and
|
|
windows, AND the assignee children's presence patterns and scoped
|
|
overrides — are read inside ONE locked transaction (see
|
|
:func:`~.dao_rules.load_materialization_input`), so the walk sees a
|
|
single coherent snapshot rather than a definition state from one
|
|
instant and a presence state from another.
|
|
- Presence is snapshotted into an immutable
|
|
:class:`~.presence.PresenceEngine` from that same coherent read.
|
|
- For each date in the range, each definition whose decoded rule
|
|
:func:`~.recurrence.occurs_on` on that date, each assignee who is
|
|
``is_present`` on that date (or every assignee, when the definition's
|
|
``skip_on_away`` is off) and each declared window, one instance is
|
|
written through :class:`~.dao_instances.QuestInstancesDao.upsert_if_valid`
|
|
with a ``generated_at`` stamp shared by the whole batch (one coherent
|
|
time per run).
|
|
|
|
A config change that lands AFTER the snapshot is read but BEFORE a
|
|
tuple's write (an assignment removed, a definition or child deactivated,
|
|
a window removed) makes that tuple SKIP rather than abort the batch:
|
|
:meth:`~.dao_instances.QuestInstancesDao.upsert_if_valid` re-validates
|
|
every materialization precondition (active definition, active child,
|
|
live assignment, declared window, and its CURRENT ``due_time``) inside
|
|
the SAME transaction as the INSERT, so the check and the write cannot be
|
|
split by a racing config edit.
|
|
|
|
The upsert is idempotent on (definition_id, child_id, due_date,
|
|
window), so re-running the materialization over the same range never
|
|
duplicates a row; a tuple whose instance is already completed is SKIPPED
|
|
(never rewritten, never raised) by
|
|
:meth:`~.dao_instances.QuestInstancesDao.upsert_if_valid`.
|
|
|
|
Regeneration: a config or presence change must rebuild future instances
|
|
so they track the new state. :func:`regenerate_for_definition` covers
|
|
definition edits / reassignment (Features 06/07); :func:`regenerate_for_child`
|
|
covers a single child's presence change (Feature 09). Both delete the
|
|
affected open instances at or after today — never a completed instance,
|
|
never the past — and re-run the walk over the rolling horizon
|
|
``[today, today + horizon_days]`` (``horizon_days`` defaults to
|
|
``DEFAULT_HORIZON_DAYS``).
|
|
|
|
HOOK (Feature 09 presence services): the presence business layer that
|
|
lands in Feature 09 MUST call :func:`regenerate_for_child` after EVERY
|
|
presence-state write so a child's future instances track its presence:
|
|
creating, updating and deleting a presence pattern
|
|
(:mod:`.presence_management`'s ``create_presence_pattern`` /
|
|
``update_presence_pattern`` / ``delete_presence_pattern``),
|
|
``create_presence_override``, and ``delete_presence_override``. A
|
|
pattern delete changes presence state too, so it must regenerate just
|
|
like the others. This hook
|
|
is documented, not yet wired: no presence business layer exists yet, and
|
|
the presence DAO (``dao_presence.py``) must stay free of business rules
|
|
— never call :func:`regenerate_for_child` from inside the DAO layer.
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
import datetime
|
|
from typing import NamedTuple
|
|
|
|
from .const import DEFAULT_HORIZON_DAYS
|
|
from .dao_instances import (
|
|
CompletionEventsDao,
|
|
QuestInstancesDao,
|
|
_resolve_today,
|
|
)
|
|
from .dao_rules import (
|
|
_validate_date,
|
|
load_materialization_input,
|
|
schedule_rule_from_storage,
|
|
schedule_rule_storage_from_record,
|
|
)
|
|
from .db import NestQuestDatabase
|
|
from .presence import PresenceEngine, PresenceOverride, PresencePattern
|
|
from .recurrence import ScheduleRule, occurs_on
|
|
|
|
|
|
def _now_stamp() -> str:
|
|
"""Return the batch's shared UTC second-precision generation stamp."""
|
|
return datetime.datetime.now(datetime.timezone.utc).isoformat(
|
|
timespec="seconds"
|
|
)
|
|
|
|
|
|
def _resolve_horizon_days(horizon_days: int | None) -> int:
|
|
"""Validate a regeneration horizon and return the resolved day count.
|
|
|
|
``None`` resolves to :data:`~.const.DEFAULT_HORIZON_DAYS`. A bool
|
|
(SQLite would happily bind ``True``/``False`` onto an int), a non-int,
|
|
or a value below 1 raises ValueError naming the field — the validation
|
|
runs BEFORE any future-instance delete so a malformed horizon can never
|
|
delete rows it then fails to rebuild. A negative horizon would
|
|
otherwise delete first and only then be rejected by
|
|
:func:`materialize`'s inverted-range check; ``0``/``False`` would
|
|
silently shrink the window to a single day.
|
|
"""
|
|
if horizon_days is None:
|
|
return DEFAULT_HORIZON_DAYS
|
|
if (
|
|
isinstance(horizon_days, bool)
|
|
or not isinstance(horizon_days, int)
|
|
or horizon_days < 1
|
|
):
|
|
raise ValueError(
|
|
f"horizon_days must be a positive integer, got {horizon_days!r}"
|
|
)
|
|
return horizon_days
|
|
|
|
|
|
def _decode_rule(snapshot) -> ScheduleRule:
|
|
"""Decode a snapshot's rule record back into a ScheduleRule.
|
|
|
|
The record carried by the snapshot is the one the definition
|
|
referenced at read time, so decoding it here (rather than re-reading
|
|
through ``ScheduleRulesDao``) preserves the coherence the snapshot
|
|
guarantees.
|
|
"""
|
|
return schedule_rule_from_storage(
|
|
schedule_rule_storage_from_record(snapshot.rule)
|
|
)
|
|
|
|
|
|
def _build_engine(
|
|
patterns_records,
|
|
overrides_records,
|
|
*,
|
|
extra_overrides: tuple[PresenceOverride, ...] = (),
|
|
) -> PresenceEngine:
|
|
"""Convert raw presence records into an immutable PresenceEngine.
|
|
|
|
``extra_overrides`` layers already-validated, NOT-yet-stored
|
|
overrides on top of the stored ones — the consequence preview's
|
|
proposed override (:func:`count_removed_by_override`).
|
|
"""
|
|
patterns: dict[int, list[PresencePattern]] = {}
|
|
for child_id, records in patterns_records.items():
|
|
patterns[child_id] = [
|
|
PresencePattern.decode(
|
|
record.child_id,
|
|
record.name,
|
|
record.kind,
|
|
record.anchor_date,
|
|
record.pattern,
|
|
)
|
|
for record in records
|
|
]
|
|
overrides: dict[int, list[PresenceOverride]] = {}
|
|
for child_id, records in overrides_records.items():
|
|
overrides[child_id] = [
|
|
PresenceOverride(
|
|
record.child_id,
|
|
record.start_date,
|
|
record.end_date,
|
|
record.is_present,
|
|
record.note,
|
|
)
|
|
for record in records
|
|
]
|
|
for override in extra_overrides:
|
|
overrides.setdefault(override.child_id, []).append(override)
|
|
return PresenceEngine(patterns, overrides)
|
|
|
|
|
|
class GeneratedTuple(NamedTuple):
|
|
"""One instance the walk WOULD write: its upsert key plus due time."""
|
|
|
|
definition_id: int
|
|
child_id: int
|
|
due_date: str
|
|
window: str
|
|
due_time: str | None
|
|
|
|
|
|
def _generation_preview(
|
|
snapshots,
|
|
engine: PresenceEngine,
|
|
start: datetime.date,
|
|
end: datetime.date,
|
|
*,
|
|
child_filter: set[int] | None = None,
|
|
) -> list[GeneratedTuple]:
|
|
"""Return the tuples the walk would write over ``[start, end]``.
|
|
|
|
The pure, read-only half of :func:`materialize`: for each date, each
|
|
definition whose decoded rule :func:`~.recurrence.occurs_on` it,
|
|
each assignee in ``child_filter`` (every assignee when None) who is
|
|
``is_present`` on it — or every assignee when the definition's
|
|
``skip_on_away`` is off — and each declared window, one tuple, in
|
|
the walk's write order. :func:`materialize` writes exactly these
|
|
tuples and :func:`count_removed_by_override` compares two of these
|
|
previews, so the write and the consequence preview can never
|
|
diverge. No database access.
|
|
"""
|
|
definitions = [
|
|
(snapshot.definition.id, _decode_rule(snapshot),
|
|
snapshot.assignees, snapshot.windows,
|
|
snapshot.definition.skip_on_away)
|
|
for snapshot in snapshots
|
|
]
|
|
generated: list[GeneratedTuple] = []
|
|
cursor = start
|
|
while cursor <= end:
|
|
iso = cursor.isoformat()
|
|
for (
|
|
definition_id, rule, assignees, windows, skip_on_away
|
|
) in definitions:
|
|
if not occurs_on(rule, cursor):
|
|
continue
|
|
for child in assignees:
|
|
if child_filter is not None and child.id not in child_filter:
|
|
continue
|
|
if skip_on_away and not engine.is_present(child.id, cursor):
|
|
continue
|
|
for window in windows:
|
|
generated.append(
|
|
GeneratedTuple(
|
|
definition_id,
|
|
child.id,
|
|
iso,
|
|
window.window,
|
|
window.due_time,
|
|
)
|
|
)
|
|
cursor += datetime.timedelta(days=1)
|
|
return generated
|
|
|
|
|
|
async def materialize(
|
|
database: NestQuestDatabase,
|
|
start_date: str,
|
|
end_date: str,
|
|
*,
|
|
child_ids: list[int] | None = None,
|
|
today: datetime.date | None = None,
|
|
) -> int:
|
|
"""Generate quest instances for the closed range [start_date, end_date].
|
|
|
|
``start_date`` and ``end_date`` must be strict ISO calendar dates
|
|
(YYYY-MM-DD) with ``end_date`` on or after ``start_date``; anything
|
|
else raises ValueError naming the offending field. Returns the number
|
|
of instances upserted for the range (idempotent — a re-run refreshes
|
|
the same rows, never duplicates them).
|
|
|
|
``child_ids`` optionally scopes the walk to exactly those children:
|
|
assignees outside the list are never written, so a caller that only
|
|
wants one child's instances rebuilt (e.g. :func:`regenerate_for_child`
|
|
after a presence change) cannot touch any unrelated child's rows.
|
|
When omitted (or None) the walk covers every assignee as before.
|
|
|
|
``today`` optionally pins the resolved household-local date the walk's
|
|
no-past guard compares against; it is threaded into every
|
|
:meth:`~.dao_instances.QuestInstancesDao.upsert_if_valid` write. When
|
|
omitted the host clock (``datetime.date.today``) is used, which is the
|
|
historical default. A caller that computed the horizon in the
|
|
household's application time zone MUST pass that same date here so a
|
|
time zone behind the host around midnight is not rejected as "past".
|
|
|
|
``start_date`` is clamped up to the resolved "today" (the same
|
|
``today`` anchor threaded into the no-past guard), so a caller that
|
|
passes a ``start_date`` already in the past never yields a
|
|
past-dated instance: the walk simply begins on today and skips every
|
|
earlier date. A range entirely in the past therefore produces zero
|
|
instances rather than an error, and the DAO's no-past guard remains
|
|
the authoritative backstop under the lock.
|
|
|
|
All inputs are read in ONE locked transaction; each tuple's write then
|
|
goes through the atomic :meth:`~.dao_instances.QuestInstancesDao.upsert_if_valid`,
|
|
which re-validates the tuple and its current ``due_time`` in the same
|
|
transaction as the INSERT, so a config change that arrives mid-batch
|
|
skips the affected tuples rather than aborting the batch or leaving a
|
|
partial result.
|
|
"""
|
|
_validate_date(start_date, "start_date")
|
|
_validate_date(end_date, "end_date")
|
|
if end_date < start_date:
|
|
raise ValueError(
|
|
f"end_date must be on or after start_date, got "
|
|
f"{end_date!r} < {start_date!r}"
|
|
)
|
|
|
|
snapshots, patterns_records, overrides_records = await (
|
|
load_materialization_input(database, start_date, end_date)
|
|
)
|
|
engine = _build_engine(patterns_records, overrides_records)
|
|
child_filter = None if child_ids is None else set(child_ids)
|
|
|
|
generated_at = _now_stamp()
|
|
instances = QuestInstancesDao(database)
|
|
|
|
start = datetime.datetime.strptime(start_date, "%Y-%m-%d").date()
|
|
end = datetime.datetime.strptime(end_date, "%Y-%m-%d").date()
|
|
|
|
# Clamp a past start up to today (the household-local anchor when the
|
|
# caller pinned one, else the host clock) so the walk can never emit a
|
|
# past-dated instance; the DAO's no-past guard remains the backstop.
|
|
# A range entirely in the past therefore yields zero instances.
|
|
today_date = _resolve_today(today)
|
|
start = max(start, today_date)
|
|
|
|
count = 0
|
|
for generated in _generation_preview(
|
|
snapshots, engine, start, end, child_filter=child_filter
|
|
):
|
|
written = await instances.upsert_if_valid(
|
|
generated.definition_id,
|
|
generated.child_id,
|
|
generated.due_date,
|
|
generated_at,
|
|
window=generated.window,
|
|
due_time=generated.due_time,
|
|
today=today,
|
|
)
|
|
if written is not None:
|
|
count += 1
|
|
return count
|
|
|
|
|
|
async def regenerate_for_definition(
|
|
database: NestQuestDatabase,
|
|
definition_id: int,
|
|
*,
|
|
today: datetime.date | None = None,
|
|
horizon_days: int | None = None,
|
|
) -> int:
|
|
"""Regenerate a definition's future instances after a config change.
|
|
|
|
The Feature 06 edit/assignment/activation paths call this after a
|
|
successful write so future instances track the new state: the
|
|
definition's open instances at or after today are deleted (never a
|
|
completed instance, never the past) via
|
|
:meth:`~.dao_instances.QuestInstancesDao.delete_future_uncompleted`,
|
|
then the materialization walk re-runs over the rolling horizon
|
|
``[today, today + horizon_days]`` so the (changed) rule,
|
|
assignee set and windows re-materialize against today's state.
|
|
|
|
"today" is computed the same way the walk computes it —
|
|
:func:`~.dao_instances._today` — so the delete cutoff and the
|
|
re-materialization range share one anchor, and the walk's
|
|
``upsert_if_valid`` no-past guard never rejects the regenerated
|
|
range. ``today`` optionally pins a caller-resolved household-local date
|
|
(threaded into both the delete cutoff and the re-materialization)
|
|
so a household time zone behind the host around midnight stays
|
|
consistent. ``horizon_days`` sizes the re-materialization window;
|
|
when omitted it falls back to :data:`~.const.DEFAULT_HORIZON_DAYS`.
|
|
A bool, non-int, or sub-1 value raises ValueError BEFORE any delete.
|
|
Returns the number of instances the re-materialization
|
|
upserted across the whole snapshot (idempotent — other active
|
|
definitions' tuples refresh in place, never duplicate).
|
|
"""
|
|
horizon = _resolve_horizon_days(horizon_days)
|
|
today_date = _resolve_today(today)
|
|
start_date = today_date.isoformat()
|
|
end_date = (
|
|
today_date + datetime.timedelta(days=horizon)
|
|
).isoformat()
|
|
|
|
instances = QuestInstancesDao(database)
|
|
await instances.delete_future_uncompleted(
|
|
definition_id, start_date, today=today
|
|
)
|
|
return await materialize(database, start_date, end_date, today=today)
|
|
|
|
|
|
# HOOK (Feature 09 presence services): ``regenerate_for_child`` is the
|
|
# child-presence counterpart to ``regenerate_for_definition``. The
|
|
# presence business layer that lands in Feature 09 MUST call
|
|
# ``regenerate_for_child`` after EVERY presence-state write, so future
|
|
# instances track a child's changed presence: create_presence_pattern,
|
|
# update_presence_pattern, delete_presence_pattern,
|
|
# create_presence_override, and delete_presence_override. A pattern
|
|
# delete changes presence state too, so it must regenerate just like
|
|
# the others. It is deliberately NOT
|
|
# wired into ``dao_presence.py``: the DAO layer stays pure storage (no
|
|
# business rules), and no presence business layer exists yet to host the
|
|
# call — see the module docstring note above.
|
|
async def regenerate_for_child(
|
|
database: NestQuestDatabase,
|
|
child_id: int,
|
|
*,
|
|
today: datetime.date | None = None,
|
|
horizon_days: int | None = None,
|
|
) -> int:
|
|
"""Regenerate a child's future instances after a presence change.
|
|
|
|
The Feature 09 presence services call this after every
|
|
presence-state write — create_presence_pattern,
|
|
update_presence_pattern, delete_presence_pattern,
|
|
create_presence_override, and delete_presence_override — so a
|
|
child's future instances track its new presence: the child's open
|
|
instances at or after today are deleted across ALL its definitions
|
|
(never a completed instance, never the past) via
|
|
:meth:`~.dao_instances.QuestInstancesDao.delete_future_uncompleted_for_child`,
|
|
then the materialization walk re-runs over the rolling horizon
|
|
``[today, today + horizon_days]`` scoped to that child only,
|
|
so the child's now-absent/present dates re-materialize against
|
|
today's presence WITHOUT touching any other child's rows.
|
|
|
|
``child_id`` must be a plain int — bool and float are rejected
|
|
(SQLite binds a bool as 0/1 and a float would round, so a malformed
|
|
id must never mutate the wrong profile).
|
|
|
|
"today" is computed the same way the walk computes it —
|
|
:func:`~.dao_instances._today` — and the re-materialization range uses the
|
|
delete's returned effective cutoff (see
|
|
:meth:`~.dao_instances.QuestInstancesDao.delete_future_uncompleted_for_child`),
|
|
so the delete cutoff and the re-materialization window share ONE
|
|
execution-day anchor even when the call is queued across midnight.
|
|
``today`` optionally pins a caller-resolved household-local date, threaded
|
|
into the delete cutoff and the re-materialization for the same
|
|
host-vs-household time-zone consistency. ``horizon_days`` sizes the
|
|
re-materialization window; when omitted it falls back to
|
|
:data:`~.const.DEFAULT_HORIZON_DAYS`. A bool, non-int, or sub-1 value
|
|
raises ValueError BEFORE any delete. Returns the number of instances
|
|
the re-materialization upserted for the child across the whole
|
|
snapshot.
|
|
"""
|
|
if isinstance(child_id, bool) or not isinstance(child_id, int):
|
|
raise ValueError(f"child_id must be an integer, got {child_id!r}")
|
|
|
|
horizon = _resolve_horizon_days(horizon_days)
|
|
today_date = _resolve_today(today)
|
|
|
|
instances = QuestInstancesDao(database)
|
|
# Use the delete's returned effective cutoff as the materialize anchor,
|
|
# NOT the independently-computed "today" above. If the call is queued
|
|
# across midnight the delete clamps its cutoff to the execution-day;
|
|
# materializing from the stale "today" (now yesterday) would trip the
|
|
# walk's no-past guard and leave the child's future instances deleted
|
|
# but not rebuilt. One anchor for both keeps them consistent.
|
|
_, effective_cutoff = await instances.delete_future_uncompleted_for_child(
|
|
child_id, today_date.isoformat(), today=today
|
|
)
|
|
start = datetime.date.fromisoformat(effective_cutoff)
|
|
end_date = (start + datetime.timedelta(days=horizon)).isoformat()
|
|
return await materialize(
|
|
database, start.isoformat(), end_date, child_ids=[child_id], today=today
|
|
)
|
|
|
|
|
|
async def count_removed_by_override(
|
|
database: NestQuestDatabase,
|
|
override: PresenceOverride,
|
|
*,
|
|
today: datetime.date | None = None,
|
|
horizon_days: int | None = None,
|
|
) -> int:
|
|
"""Count the upcoming instances saving ``override`` would remove.
|
|
|
|
Read-only: nothing is written. The window is the part of the
|
|
override's range inside the rolling horizon ``[today, today +
|
|
horizon_days]`` that :func:`regenerate_for_child` rebuilds after the
|
|
override is saved (outside the range the two presence answers agree,
|
|
so nothing there can change). The materialization input is read
|
|
ONCE (:func:`~.dao_rules.load_materialization_input`) and
|
|
:func:`_generation_preview` runs twice over it for the override's
|
|
child — with the stored presence, and with ``override`` layered on
|
|
top (:func:`_build_engine`'s ``extra_overrides``). The count is the
|
|
tuples the first preview generates and the second does not, MINUS
|
|
every (definition, date, window) whose stored instance already has a
|
|
completion event (D-005: regeneration never deletes those). A
|
|
definition with ``skip_on_away`` off generates regardless of
|
|
presence, so it contributes nothing; a present override only ever
|
|
ADDS tuples, so it counts 0.
|
|
|
|
An override overlapping a stored one (which the create path refuses)
|
|
resolves through the engine's latest-start-wins rule. ``today`` and
|
|
``horizon_days`` resolve exactly as :func:`regenerate_for_child`
|
|
resolves them; a malformed horizon raises ValueError.
|
|
"""
|
|
horizon = _resolve_horizon_days(horizon_days)
|
|
today_date = _resolve_today(today)
|
|
start = max(today_date, override.start_date)
|
|
end = min(
|
|
today_date + datetime.timedelta(days=horizon), override.end_date
|
|
)
|
|
if end < start:
|
|
return 0
|
|
start_date, end_date = start.isoformat(), end.isoformat()
|
|
child_id = override.child_id
|
|
|
|
snapshots, patterns_records, overrides_records = await (
|
|
load_materialization_input(database, start_date, end_date)
|
|
)
|
|
current = _generation_preview(
|
|
snapshots,
|
|
_build_engine(patterns_records, overrides_records),
|
|
start,
|
|
end,
|
|
child_filter={child_id},
|
|
)
|
|
proposed = set(
|
|
_generation_preview(
|
|
snapshots,
|
|
_build_engine(
|
|
patterns_records,
|
|
overrides_records,
|
|
extra_overrides=(override,),
|
|
),
|
|
start,
|
|
end,
|
|
child_filter={child_id},
|
|
)
|
|
)
|
|
removed = [generated for generated in current if generated not in proposed]
|
|
if not removed:
|
|
return 0
|
|
|
|
stored = await QuestInstancesDao(database).list_by_date_range(
|
|
child_id, start_date, end_date
|
|
)
|
|
touched = {
|
|
event.instance_id
|
|
for event in await CompletionEventsDao(
|
|
database
|
|
).list_by_child_and_date_range(child_id, start_date, end_date)
|
|
}
|
|
completed = {
|
|
(instance.definition_id, instance.due_date, instance.window)
|
|
for instance in stored
|
|
if instance.id in touched
|
|
}
|
|
return sum(
|
|
1
|
|
for generated in removed
|
|
if (generated.definition_id, generated.due_date, generated.window)
|
|
not in completed
|
|
)
|