83 lines
3.5 KiB
Python
83 lines
3.5 KiB
Python
"""A rule's edit history — the snapshot taken when an edit overwrites text.
|
|
|
|
Sibling of `note_versions`, and the differences are the whole design.
|
|
|
|
WHAT A VERSION IS FOR. It records what a rule USED TO SAY, because an update
|
|
overwrites that and nothing can recompute it. It is not a record of the rule's
|
|
lifecycle: a soft delete keeps the rule row whole and restorable, so there is
|
|
nothing to preserve at delete time, and anything that outlived a purge would be
|
|
data the operator explicitly asked to be gone.
|
|
|
|
WHAT IS DELIBERATELY NOT COPIED FROM note_versions (milestone 323). Both of its
|
|
guards defend against note autosave, which fires every 60 seconds and would
|
|
otherwise burn every slot. Rules have no autosave — every version here comes
|
|
from a deliberate `update_rule` — so both guards would only ever discard a real
|
|
edit:
|
|
|
|
- No `MIN_VERSION_INTERVAL_SECONDS`. Two deliberate edits four minutes apart
|
|
are two edits.
|
|
- No `MAX_VERSIONS` and no pruning. A rule is edited a handful of times in its
|
|
life; a cap invites losing the one edit somebody needed.
|
|
|
|
TEXT ONLY. A rule's topic, its Systems tags and its typed edges are not here.
|
|
They have their own lifecycle, and folding them in would make one word,
|
|
"version", mean two things — the rule's wording, and the rule's place in the
|
|
graph.
|
|
"""
|
|
from sqlalchemy import select
|
|
|
|
from scribe.models import async_session
|
|
from scribe.models.rule_version import RuleVersion
|
|
|
|
# The columns a version carries, and therefore the ones whose change is worth
|
|
# a snapshot. `order_index` and `arose_from_id` are editable through
|
|
# update_rule and are deliberately absent: reordering a rulebook is not an
|
|
# edit to what any rule says, and a run of "moved rule 4 above rule 3"
|
|
# snapshots would bury the edits somebody is actually looking for.
|
|
SNAPSHOT_FIELDS = (
|
|
"title", "statement", "why", "how_to_apply", "when_to_apply",
|
|
"kind", "verify_with", "expires_when",
|
|
)
|
|
|
|
|
|
def snapshot(rule) -> dict:
|
|
"""The rule's text right now, as a plain dict.
|
|
|
|
Plain values rather than the ORM object because the caller has to hold
|
|
this ACROSS the mutation — a live `rule` would show the new text by the
|
|
time it was read, which is the one thing the snapshot must not do.
|
|
"""
|
|
return {f: getattr(rule, f) for f in SNAPSHOT_FIELDS}
|
|
|
|
|
|
def record_if_changed(session, rule, actor_user_id: int | None, before: dict):
|
|
"""Add a version holding `before`, unless the edit changed no text.
|
|
|
|
Git semantics, and not a nicety: `update_rule` is reached by callers that
|
|
resend every field, so without this a form saved twice would file a second
|
|
identical snapshot and the history would stop reading as a list of edits.
|
|
|
|
Session-BOUND, unlike `note_versions.create_version` which opens its own.
|
|
The version and the edit that caused it commit together or not at all;
|
|
a separate session could leave a snapshot behind after the update it
|
|
describes had failed, which is a history entry for an edit that never
|
|
happened.
|
|
"""
|
|
if snapshot(rule) == before:
|
|
return None
|
|
version = RuleVersion(
|
|
rule_id=rule.id, user_id=actor_user_id, **before,
|
|
)
|
|
session.add(version)
|
|
return version
|
|
|
|
|
|
async def list_versions(rule_id: int) -> list[RuleVersion]:
|
|
"""Newest first — the reader's question is "what did this just say?"."""
|
|
async with async_session() as session:
|
|
return list((await session.execute(
|
|
select(RuleVersion)
|
|
.where(RuleVersion.rule_id == rule_id)
|
|
.order_by(RuleVersion.created_at.desc(), RuleVersion.id.desc())
|
|
)).scalars().all())
|