feat(rules): a preference is a rule that does not bind (#3849 step 1)
CI & Build / Plugin hooks (push) Successful in 11s
CI & Build / Python lint (push) Successful in 2s
CI & Build / TypeScript typecheck (push) Successful in 54s
CI & Build / integration (push) Successful in 1m4s
CI & Build / Python tests (push) Failing after 1m11s
CI & Build / Build & push image (push) Skipped

Adds `kind` to rules — `rule` binds, `preference` is how the operator wants
work done. One column, because the two differ in exactly one dimension and
everything else a preference needs already lives on `rules`: a trigger
column, a trigger-dominated embedding document, ownership-scoped search,
three retrieval arms with telemetry, typed relations, and versioning.

Defaults to `rule`, so nothing changes force on upgrade — 0088's argument
for `tier`, unchanged.

`rule_versions` gets the column too, and that half is not bookkeeping.
`record_if_changed` decides whether an edit deserves a snapshot by comparing
the fields a version carries, so a field absent from SNAPSHOT_FIELDS is a
field whose change records no history at all. Without it, turning a rule
into a preference — the moment something stops binding, and the single most
consequential edit either kind can undergo — would leave the history silent.

Backup carries it through all four seams. A missed one would have restored
every preference as a rule, quietly.

Guarded on real Postgres in three halves: a preference writes, a typo is
refused (without which every other assertion would pass against a table
whose CHECK had been dropped), and a row written with no kind reads back as
`rule` — the migration's whole safety claim, asserted rather than assumed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011cPyzNnegXHr5iRMzzy5KJ
This commit is contained in:
2026-09-10 21:14:29 -04:00
co-authored by Claude Opus 5
parent c1aa1d8e92
commit c63172272d
7 changed files with 332 additions and 6 deletions
+33 -3
View File
@@ -295,6 +295,9 @@ async def _assert_rulebook_rule_owned(session, rule_id: int, user_id: int) -> No
# two in step; this keeps the error readable).
TIERS = ("always_on", "conditional")
RELATION_KINDS = ("co_surfaces", "overrides", "elaborates")
# Migration 0098's CHECK. `rule` binds; `preference` is how the operator
# wants work done — see the model comment for why both live on one table.
KINDS = ("rule", "preference")
# The rule columns that are nullable, and therefore the ones where EMPTY has
@@ -319,6 +322,22 @@ def _valid_tier(tier: str) -> str:
return tier if tier in TIERS else "always_on"
def _valid_kind(kind: str) -> str:
"""An unrecognised kind falls back to `rule` — the SAFE direction.
Same shape as _valid_tier and the same argument, pointed at force instead
of delivery. A preference wrongly treated as binding costs a little
friction: the reader is told something is required that was only
preferred. A rule wrongly treated as a preference costs the thing the rule
was written to prevent, and costs it silently, because nothing downstream
can tell a softened rule from a preference that was always one.
Between a reader who is too careful and a reader who is not careful
enough, the typo should produce the first.
"""
return kind if kind in KINDS else "rule"
# Re-exported, not redefined. Notes gained the same trio in milestone 317 and
# this reading of it is genuinely common, so it moved to services/verification
# — the DRY win note 3163 names, as against sharing the QUERY, which the two
@@ -351,6 +370,13 @@ def rule_brief(rule: Rule, **extra) -> dict:
"statement": rule.statement,
"topic_id": rule.topic_id,
"tier": rule.tier,
# Unconditional, and the payload cost is accepted deliberately. Every
# other optional key below is attached only when present, because an
# absent key should never read as a capability the record lacks. Force
# is the opposite case: a reader seeing no `kind` would have to assume
# one, and the assumption it would reach for — "this binds" — is the
# expensive one to get wrong in the other direction. Say it outright.
"kind": rule.kind or "rule",
"updated_at": rule.updated_at.date().isoformat() if rule.updated_at else None,
}
# Attached only when present (#2483: never a null key that reads as a
@@ -478,7 +504,7 @@ async def create_rule(
topic_id: int, user_id: int, title: str, statement: str,
why: str = "", how_to_apply: str = "", order_index: int = 0,
when_to_apply: str = "", tier: str = "always_on", arose_from_id: int = 0,
verify_with: str = "", expires_when: str = "",
verify_with: str = "", expires_when: str = "", kind: str = "rule",
) -> Rule:
async with async_session() as session:
await _assert_topic_owned(session, topic_id, user_id)
@@ -488,6 +514,7 @@ async def create_rule(
statement=statement,
when_to_apply=when_to_apply or None,
tier=_valid_tier(tier),
kind=_valid_kind(kind),
why=why or None,
how_to_apply=how_to_apply or None,
verify_with=verify_with or None,
@@ -506,7 +533,7 @@ async def create_project_rule(
project_id: int, user_id: int, title: str, statement: str,
why: str = "", how_to_apply: str = "", order_index: int = 0,
when_to_apply: str = "", tier: str = "always_on", arose_from_id: int = 0,
verify_with: str = "", expires_when: str = "",
verify_with: str = "", expires_when: str = "", kind: str = "rule",
) -> Rule:
"""Create a rule scoped to a single project (no rulebook ceremony).
@@ -522,6 +549,7 @@ async def create_project_rule(
statement=statement,
when_to_apply=when_to_apply or None,
tier=_valid_tier(tier),
kind=_valid_kind(kind),
why=why or None,
how_to_apply=how_to_apply or None,
verify_with=verify_with or None,
@@ -752,7 +780,7 @@ async def update_rule(
return None
allowed = {
"title", "statement", "why", "how_to_apply", "order_index",
"when_to_apply", "tier", "arose_from_id",
"when_to_apply", "tier", "kind", "arose_from_id",
"verify_with", "expires_when",
}
check_before = rule.verify_with
@@ -770,6 +798,8 @@ async def update_rule(
continue
if key == "tier":
value = _valid_tier(value)
elif key == "kind":
value = _valid_kind(value)
elif key in NULLABLE_RULE_TEXT:
value = value or None
elif key == "arose_from_id":