feat(rules): a rule keeps what it used to say — rule_versions (#3240, milestone 323 step 1)

The sibling notes already had. `note_versions` snapshots a note's every
meaningful edit; a RULE, which binds behaviour on every session that loads
it, had nothing — an edit destroyed the previous wording with no record
anywhere. Rescoping rule 79 meant hand-copying the superseded statement into
a task log to keep it (#3237). The more consequential record had the weaker
protection.

Schema and transport only. Nothing writes a version yet — that is step 2.

Three guards are deliberately NOT copied from note_versions, each defending
against autosave, which rules do not have: no pruning or MAX_VERSIONS, no
pin columns, no minimum interval. A rule is edited a handful of times in its
life, and capping invites losing the one edit somebody needed.

`user_id` is the ACTOR rather than the owner, and SET NULL rather than
CASCADE: deleting a user must not erase the history of the rules they
edited. The restore diverges from its NoteVersion sibling accordingly — an
unmappable user leaves the row with a null actor instead of dropping it,
which is the whole point of choosing SET NULL. The integration round trip
pins that, because nothing in the code says which of the two shapes is
intended and "make it match the sibling" would silently delete the record.

Backup goes to v13. Both export paths carry the table; the per-user one
scopes through the rule rather than the version's user_id, or it would carry
the versions this user wrote on someone else's rule and drop the ones
someone else wrote on theirs. The restore remaps rule_id through
rule_id_map — #3182's arose_from_id trap on a new table.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

src/scribe/models/__init__.py

@@ -33,6 +33,7 @@ from scribe.models.milestone import Milestone  # noqa: E402, F401
 from scribe.models.task_log import TaskLog  # noqa: E402, F401
 from scribe.models.note_draft import NoteDraft  # noqa: E402, F401
 from scribe.models.note_version import NoteVersion  # noqa: E402, F401
+from scribe.models.rule_version import RuleVersion  # noqa: E402, F401
 from scribe.models.note_supersession import NoteSupersession  # noqa: E402, F401
 from scribe.models.group import Group, GroupMembership  # noqa: E402, F401
 from scribe.models.share import NoteShare, ProjectShare  # noqa: E402, F401

src/scribe/models/rule_version.py

@@ -0,0 +1,91 @@
+from datetime import datetime
+
+from sqlalchemy import BigInteger, ForeignKey, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from scribe.models import Base
+from scribe.models.base import CreatedAtMixin, iso
+
+
+class RuleVersion(Base, CreatedAtMixin):
+    """One snapshot of a rule's text, taken before an edit overwrote it.
+
+    THE SIBLING NOTES ALREADY HAD. `note_versions` has existed for a long
+    time, and the design-system note calls its history "the changelog". Rules
+    — which BIND BEHAVIOUR on every session that loads them — had nothing, so
+    an edit destroyed what the rule used to say. Rescoping rule 79 on
+    2026-08-29 meant hand-copying the superseded statement into a task log to
+    keep it (#3237). The more consequential record had the weaker protection.
+
+    `CreatedAtMixin`, not `TimestampMixin`: a version is an EVENT. It is
+    written once and never updated, so an `updated_at` on it would be a column
+    that can only ever lie.
+
+    WHAT IS DELIBERATELY DIFFERENT FROM NoteVersion (milestone 323):
+
+    - `user_id` is the ACTOR — who made the edit — where NoteVersion's is the
+      owner, because `update_note` passes an owner-scoped id. For an audit
+      trail over a binding instruction, "who changed this" is the question
+      being asked, and a rule is editable by anyone with rulebook access.
+    - No `pin_kind` / `pin_label`. Those exist so a note's version can survive
+      autosave pruning. Nothing prunes here, so a pin would protect a row that
+      was never at risk.
+    - TEXT ONLY. A rule's Systems and its typed relations are edges with their
+      own lifecycle; folding them in would make one word, "version", mean two
+      different things — the rule's wording, and the rule's place in the
+      graph. `verified_at` is likewise absent: it is a stamp about a check,
+      not a property of the text, and step 2's snapshot is taken before
+      update_rule clears it precisely so the history shows the check that was
+      in force when this wording was written.
+    """
+
+    __tablename__ = "rule_versions"
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True)
+    rule_id: Mapped[int] = mapped_column(
+        BigInteger, ForeignKey("rules.id", ondelete="CASCADE"), index=True
+    )
+    # The actor. SET NULL rather than CASCADE: deleting a user must not erase
+    # the history of the rules they edited — the edit still happened, and the
+    # rule is still binding because of it. NoteVersion cascades because a
+    # note's versions belong to its owner; a rule's belong to the rule.
+    user_id: Mapped[int | None] = mapped_column(
+        BigInteger, ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+    )
+
+    title: Mapped[str] = mapped_column(Text, default="")
+    statement: Mapped[str] = mapped_column(Text, default="")
+    why: Mapped[str | None] = mapped_column(Text, nullable=True)
+    how_to_apply: Mapped[str | None] = mapped_column(Text, nullable=True)
+    when_to_apply: Mapped[str | None] = mapped_column(Text, nullable=True)
+    tier: Mapped[str | None] = mapped_column(Text, nullable=True)
+    verify_with: Mapped[str | None] = mapped_column(Text, nullable=True)
+    expires_when: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    def to_dict(self, include_text: bool = True) -> dict:
+        """The row. `include_text=False` gives the listing form.
+
+        A rule's `statement` and `why` run to thousands of characters — rule
+        149's `why` alone is longer than most notes — so a history LIST that
+        carried every field would be unreadable and expensive. The listing
+        answers "when, and by whom"; opening one answers "and what did it
+        say". Same split NoteVersion makes with `include_body`.
+        """
+        out: dict = {
+            "id": self.id,
+            "rule_id": self.rule_id,
+            "user_id": self.user_id,
+            "title": self.title,
+            "created_at": iso(self.created_at),
+        }
+        if include_text:
+            out.update({
+                "statement": self.statement,
+                "why": self.why or "",
+                "how_to_apply": self.how_to_apply or "",
+                "when_to_apply": self.when_to_apply or "",
+                "tier": self.tier or "",
+                "verify_with": self.verify_with or "",
+                "expires_when": self.expires_when or "",
+            })
+        return out

src/scribe/services/backup.py

@@ -9,6 +9,7 @@ from scribe.models.note import Note
 from scribe.models.note_draft import NoteDraft
 from scribe.models.note_supersession import NoteSupersession
 from scribe.models.note_version import NoteVersion
+from scribe.models.rule_version import RuleVersion
 from scribe.models.design_system import DesignSystem, DesignToken
 from scribe.models.note_usage import NoteUsageEvent
 from scribe.models.canonical_system import CanonicalSystem
@@ -60,8 +61,9 @@ logger = logging.getLogger(__name__)
 # note, every issue and spike into `work`, and every plan reduced to a title.
 # _COLUMN_EXCLUSIONS and its guard landed with it, so the next such column
 # fails the build instead.
+# v13 (2026-08) added rule_versions — a rule's edit history (milestone 323).
 # Bump when the serialized schema changes.
-BACKUP_VERSION = 12
+BACKUP_VERSION = 13
 
 # Every table this backup carries, by its REAL name. Paired with _NOT_INCLUDED
 # below, these two lists must together account for the entire schema — which is
@@ -87,6 +89,9 @@ _BACKED_UP = [
     "canonical_systems",
     # v10 (2026-08): a rule's area tag and its typed edges (milestone 307).
     "rule_systems", "rule_relations",
+    # v13 (2026-08): a rule's edit history (milestone 323). note_versions has
+    # always travelled; its sibling has no excuse not to.
+    "rule_versions",
 ]
 
 # Tables intentionally NOT in the backup, surfaced in the payload so the gap is
@@ -176,6 +181,10 @@ _COLUMN_EXCLUSIONS: dict[str, set[str]] = {
     "design_systems": {"deleted_at", "deleted_batch_id", "created_at", "updated_at"},
     "design_tokens": {"deleted_at", "deleted_batch_id", "created_at", "updated_at"},
     "repo_bindings": {"id", "created_at", "updated_at"},
+    # Everything travels. A version row IS the audit trail, so a column left
+    # behind is a fact about a binding instruction that no longer exists
+    # anywhere.
+    "rule_versions": set(),
     # Serialised via the model's own to_dict(), so a column reaches the backup
     # the moment it reaches that method — and the guard still catches one that
     # reaches neither.
@@ -472,6 +481,23 @@ def _note_version_rows(rows) -> list[dict]:
     ]
 
 
+def _rule_version_rows(rows) -> list[dict]:
+    """A rule's edit history. Sibling of _note_version_rows, and it travels for
+    the same reason: a version is the only record of what a binding
+    instruction used to say, and nothing can recompute it."""
+    return [
+        {
+            "id": rv.id, "rule_id": rv.rule_id, "user_id": rv.user_id,
+            "title": rv.title, "statement": rv.statement, "why": rv.why,
+            "how_to_apply": rv.how_to_apply, "when_to_apply": rv.when_to_apply,
+            "tier": rv.tier, "verify_with": rv.verify_with,
+            "expires_when": rv.expires_when,
+            "created_at": rv.created_at.isoformat(),
+        }
+        for rv in rows
+    ]
+
+
 def _setting_rows(rows) -> list[dict]:
     return [{"user_id": s.user_id, "key": s.key, "value": s.value} for s in rows]
 
@@ -553,6 +579,9 @@ async def export_full_backup() -> dict:
         note_versions = (await session.execute(
             select(NoteVersion).order_by(NoteVersion.note_id, NoteVersion.id)
         )).scalars().all()
+        rule_versions = (await session.execute(
+            select(RuleVersion).order_by(RuleVersion.rule_id, RuleVersion.id)
+        )).scalars().all()
         settings = (await session.execute(select(Setting))).scalars().all()
         systems = (await session.execute(select(System))).scalars().all()
         canonical_systems = (await session.execute(
@@ -617,6 +646,7 @@ async def export_full_backup() -> dict:
         "task_logs": _task_log_rows(task_logs),
         "note_drafts": _note_draft_rows(note_drafts),
         "note_versions": _note_version_rows(note_versions),
+        "rule_versions": _rule_version_rows(rule_versions),
         "settings": _setting_rows(settings),
         "rulebooks": _rulebook_rows(rulebooks),
         "rulebook_topics": _topic_rows(topics),
@@ -753,6 +783,14 @@ async def export_user_backup(user_id: int) -> dict:
             .join(CanonicalSystem, CanonicalSystem.id == rule_systems_t.c.canonical_id)
             .where(rule_systems_t.c.rule_id.in_(_rule_ids))
         )).all() if _rule_ids else []
+        # Scoped through the RULE, not the version's user_id. That column is
+        # the ACTOR (milestone 323), so filtering on it would carry the
+        # versions this user wrote on someone ELSE's rule and drop the ones
+        # someone else wrote on theirs — the opposite of a per-user export.
+        rule_versions = (await session.execute(
+            select(RuleVersion).where(RuleVersion.rule_id.in_(_rule_ids))
+            .order_by(RuleVersion.rule_id, RuleVersion.id)
+        )).scalars().all() if _rule_ids else []
         rule_relations = (await session.execute(
             select(RuleRelation).where(
                 RuleRelation.from_rule_id.in_(_rule_ids),
@@ -801,6 +839,7 @@ async def export_user_backup(user_id: int) -> dict:
         "task_logs": _task_log_rows(task_logs),
         "note_drafts": _note_draft_rows(note_drafts),
         "note_versions": _note_version_rows(note_versions),
+        "rule_versions": _rule_version_rows(rule_versions),
         "settings": _setting_rows(settings),
         "rulebooks": _rulebook_rows(rulebooks),
         "rulebook_topics": _topic_rows(topics),
@@ -958,7 +997,7 @@ async def _restore_v2(data: dict) -> dict:
         "design_tokens": 0, "note_usage_events": 0, "repo_bindings": 0,
         "note_supersessions": 0, "code_shapes": 0, "code_shape_events": 0,
         "code_shape_uses": 0, "canonical_systems": 0,
-        "rule_systems": 0, "rule_relations": 0,
+        "rule_systems": 0, "rule_relations": 0, "rule_versions": 0,
     }
 
     async with async_session() as session:
@@ -1327,6 +1366,32 @@ async def _restore_v2(data: dict) -> dict:
             ))
             stats["rule_relations"] += 1
 
+        # A rule's edit history (milestone 323). Must come after the rules
+        # themselves — rule_id_map is only populated above — and both ids are
+        # ids in the SOURCE database, which is #3182's arose_from_id trap.
+        for rv in data.get("rule_versions", []):
+            mapped_rid = rule_id_map.get(rv.get("rule_id", 0))
+            if mapped_rid is None:
+                continue
+            # Unlike NoteVersion, an unmappable user does NOT drop the row.
+            # user_id is the ACTOR and is nullable by design: the column is
+            # SET NULL precisely so history outlives the account that wrote
+            # it. Skipping here would delete the record the FK preserves.
+            session.add(RuleVersion(
+                rule_id=mapped_rid,
+                user_id=user_id_map.get(rv.get("user_id") or 0),
+                title=rv.get("title", ""),
+                statement=rv.get("statement", ""),
+                why=rv.get("why"),
+                how_to_apply=rv.get("how_to_apply"),
+                when_to_apply=rv.get("when_to_apply"),
+                tier=rv.get("tier"),
+                verify_with=rv.get("verify_with"),
+                expires_when=rv.get("expires_when"),
+                created_at=_dt(rv.get("created_at")),
+            ))
+            stats["rule_versions"] += 1
+
         # 15. Systems
         for sy_data in data.get("systems", []):
             mapped_uid = user_id_map.get(sy_data.get("user_id", 0))