feat(ledger): code_shapes — the shape ledger schema (#2787, milestone 294 step 1)

The accounting half of the pattern system (governing note 2786): the snippet
library records canon (small), this table accounts for EVERY extracted shape
(total). Identity is (project, repo_key, path, symbol, kind) — kind included
because one file can define '.foo' (css) and 'foo' (sym) as distinct shapes.
Status vocabulary: canonical / instance / variant / exempt / unclassified,
with unclassified as the default and THE todo state; classifications carry
who judged (agent|audit|hook|mechanical|import), when, and the why for
variants/exemptions. first/last-seen commits + vanished_at keep history
instead of deleting it; a rename reads as vanish+new (accepted for v1).

snippet_id is SET NULL on snippet deletion so accounting rows outlive their
target and rejoin the todo via the step-2 sync, never dangle silently.

Backups: v7 carries code_shapes (judgment data, worth moving) — full and
per-user export sections, and a restore that keeps a judgment only when its
snippet survives the id re-mapping, downgrading to unclassified otherwise.

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

tests/test_shape_ledger.py

@@ -0,0 +1,52 @@
+"""The shape ledger's schema contract (#2787, milestone 294, note 2786).
+
+Step 1 pins the model: identity, the classification vocabulary, and the
+token-free serialisation. The sync pass (step 2) and the classification
+surface (step 3) grow their tests here; DB-backed behavior lands in the
+integration lane once there is behavior to exercise.
+"""
+from scribe.models import Base
+from scribe.models.code_shape import SHAPE_CLASSIFIERS, SHAPE_STATUSES, CodeShape
+
+
+def test_identity_is_project_repo_path_symbol_kind():
+    """Kind is part of identity on purpose: one file can define `.foo` (css)
+    and `foo` (sym) as distinct shapes — the extractor emits both."""
+    table = Base.metadata.tables["code_shapes"]
+    unique = next(
+        c for c in table.constraints
+        if getattr(c, "name", "") == "uq_code_shapes_identity"
+    )
+    assert [c.name for c in unique.columns] == [
+        "project_id", "repo_key", "path", "symbol", "kind",
+    ]
+
+
+def test_the_todo_state_is_the_default():
+    """A shape nobody has judged yet must read `unclassified` — the ledger's
+    todo list — never silently look classified."""
+    assert CodeShape.__table__.c.status.default.arg == "unclassified"
+    assert "unclassified" in SHAPE_STATUSES
+    assert set(SHAPE_STATUSES) == {
+        "canonical", "instance", "variant", "exempt", "unclassified",
+    }
+    assert set(SHAPE_CLASSIFIERS) == {
+        "agent", "audit", "hook", "mechanical", "import",
+    }
+
+
+def test_snippet_reference_survives_snippet_deletion_as_null():
+    """SET NULL, not CASCADE: a deleted snippet must not silently erase the
+    accounting rows that pointed at it — the sync pass re-files them as
+    unclassified so they rejoin the todo."""
+    fk = next(iter(CodeShape.__table__.c.snippet_id.foreign_keys))
+    assert fk.ondelete == "SET NULL"
+    assert fk.column.table.name == "notes"
+
+
+def test_status_queries_have_an_index():
+    """list_shapes(status=unclassified) is THE todo query (step 3) — it must
+    not degrade into a project-wide scan as ledgers reach thousands of rows."""
+    names = {ix.name for ix in CodeShape.__table__.indexes}
+    assert "ix_code_shapes_project_status" in names
+    assert "ix_code_shapes_snippet" in names