feat(design-systems): the model, the parent chain, and the guard on it

Milestone #254 step 1 (#2286). A design system becomes a record Scribe holds
rather than prose in a rulebook: a named set of tokens with an OPTIONAL parent,
so a family system carries the house style and an app system carries only what
it changes. Answering "what does this app alter?" is then `list its tokens` —
nothing to compute.

`parent_id` is the whole model. It replaces both an `always_on` flag (a family
system is one with no parent) and a subscription join table (a project points at
ONE system; the chain supplies the rest) — less schema than the rulebook shape
it mirrors.

Two decisions the task left open, settled here:

- **Token values are JSONB keyed by mode**, not `value_light`/`value_dark`
  columns. The deciding argument was not flexibility, it was ambiguity: in a
  child system an unset mode means "inherit", in a root it means "not
  mode-dependent", and as columns both are NULL and the resolver cannot tell
  them apart. As a map, resolution is `{**parent, **child}` at every level with
  no special case for roots. Against it: queryability — but nothing filters
  tokens by value in SQL, so that buys a query no caller makes.
- **`group_name` is free text, no CHECK enum.** Groupings are each design
  system's own vocabulary; a whitelist would bake one install's kit into the
  schema. No CHECK is introduced anywhere, so rule #36 does not fire.

The cascade lives in `services/design_cascade.py` as pure functions over a
`{id: parent_id}` map, importing nothing — which is what lets both the service
and `access.py` use it without a cycle, and lets a test state a whole hierarchy
in one literal. Cycles are refused on WRITE by walking up from the proposed
parent (the cheap direction), and survived on READ by a visited-set, because a
loop from a direct DB edit must truncate rather than hang.

ACL (rule #78) is deliberately asymmetric: owning a system grants write,
reaching one through a project you can see grants READ ONLY. An editor on a
shared project must not be able to rewrite the family system every other project
in that family resolves through.

Also renames `services/design_system.py` -> `design_rulebook_import.py`. It is
the #251 prose extractor, whose role is already scheduled to become a one-shot
importer (#2288), and leaving it one character away from the new
`design_systems.py` was a trap for every later session.

Rule #115 throughout: nothing seeds a system or implies a default. An install
with zero design systems is ordinary, not degraded.

tests/test_services_design_systems.py

@@ -0,0 +1,194 @@
+"""ACL gating and field handling for services/design_systems.py (unit, mocked).
+
+Mirrors tests/test_services_systems.py — same mocked-session shape, because the
+question is the same one: does the service refuse before it touches a row?
+"""
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from scribe.services.design_systems import DesignSystemCycle
+
+
+def _make_mock_session():
+    s = AsyncMock()
+    s.__aenter__ = AsyncMock(return_value=s)
+    s.__aexit__ = AsyncMock(return_value=False)
+    s.add = MagicMock()
+    s.commit = AsyncMock()
+    s.refresh = AsyncMock()
+    return s
+
+
+# --- creating ---------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_create_with_a_parent_is_denied_without_write_on_that_parent():
+    """Parenting to someone else's system would let their delete or re-parent
+    silently restyle your app, so the chain may only be built from systems you
+    can write — which, per the ACL, means ones you own."""
+    with patch("scribe.services.design_systems.access") as acc:
+        acc.can_write_design_system = AsyncMock(return_value=False)
+        from scribe.services.design_systems import create_design_system
+        result = await create_design_system(user_id=1, title="Scribe", parent_id=7)
+    assert result is None
+
+
+@pytest.mark.asyncio
+async def test_create_without_a_parent_never_consults_the_parent_acl():
+    """A family system has no parent, and creating one must not be gated on a
+    permission check for a system that does not exist."""
+    mock_session = _make_mock_session()
+    captured = {}
+    mock_session.add = MagicMock(
+        side_effect=lambda obj: captured.update(
+            title=obj.title, parent_id=obj.parent_id
+        )
+    )
+    with patch("scribe.services.design_systems.async_session") as mock_cls, \
+         patch("scribe.services.design_systems.access") as acc:
+        acc.can_write_design_system = AsyncMock(return_value=False)
+        mock_cls.return_value = mock_session
+        from scribe.services.design_systems import create_design_system
+        await create_design_system(user_id=1, title="  FabledSword  ")
+    assert captured["title"] == "FabledSword"   # stripped
+    assert captured["parent_id"] is None
+    acc.can_write_design_system.assert_not_awaited()
+
+
+# --- the cycle guard, through the service -----------------------------------
+
+@pytest.mark.asyncio
+async def test_reparenting_into_a_loop_raises_rather_than_returning_none():
+    """None already means "not found, or not yours". A caller that conflated the
+    two would report "no such design system" for what is really "that parent is
+    one of its own descendants", so the cycle gets its own exception type."""
+    mock_session = _make_mock_session()
+    mock_session.get = AsyncMock(return_value=MagicMock(deleted_at=None, parent_id=None))
+
+    with patch("scribe.services.design_systems.async_session") as mock_cls, \
+         patch("scribe.services.design_systems.access") as acc, \
+         patch("scribe.services.design_systems._parent_map",
+               AsyncMock(return_value={1: None, 2: 1})):
+        acc.can_write_design_system = AsyncMock(return_value=True)
+        mock_cls.return_value = mock_session
+        from scribe.services.design_systems import update_design_system
+        with pytest.raises(DesignSystemCycle):
+            await update_design_system(user_id=1, design_system_id=1, parent_id=2)
+
+    mock_session.commit.assert_not_awaited()  # refused BEFORE the write
+
+
+@pytest.mark.asyncio
+async def test_clearing_the_parent_is_allowed_and_is_not_read_as_no_change():
+    """`parent_id=None` means "make this a root" — the one field where None is a
+    value rather than "leave alone", which is why it is handled apart from the
+    others."""
+    system = MagicMock(deleted_at=None, parent_id=5)
+    mock_session = _make_mock_session()
+    mock_session.get = AsyncMock(return_value=system)
+
+    with patch("scribe.services.design_systems.async_session") as mock_cls, \
+         patch("scribe.services.design_systems.access") as acc, \
+         patch("scribe.services.design_systems._parent_map",
+               AsyncMock(return_value={1: 5, 5: None})):
+        acc.can_write_design_system = AsyncMock(return_value=True)
+        mock_cls.return_value = mock_session
+        from scribe.services.design_systems import update_design_system
+        await update_design_system(user_id=1, design_system_id=1, parent_id=None)
+
+    assert system.parent_id is None
+
+
+# --- tokens -----------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_create_token_denied_without_write_on_the_system():
+    with patch("scribe.services.design_systems.access") as acc:
+        acc.can_write_design_system = AsyncMock(return_value=False)
+        from scribe.services.design_systems import create_token
+        result = await create_token(user_id=1, design_system_id=3, name="--fs-obsidian")
+    assert result is None
+
+
+@pytest.mark.asyncio
+async def test_token_values_default_to_an_empty_map_not_json_null():
+    """The column is NOT NULL so that absence has exactly ONE spelling. Passing
+    None straight through would store JSON null and hand every reader back the
+    second empty state the schema was shaped to remove."""
+    mock_session = _make_mock_session()
+    captured = {}
+    mock_session.add = MagicMock(
+        side_effect=lambda obj: captured.update(value_by_mode=obj.value_by_mode)
+    )
+
+    with patch("scribe.services.design_systems.async_session") as mock_cls, \
+         patch("scribe.services.design_systems.access") as acc:
+        acc.can_write_design_system = AsyncMock(return_value=True)
+        mock_cls.return_value = mock_session
+        from scribe.services.design_systems import create_token
+        await create_token(
+            user_id=1, design_system_id=3, name="--fs-radius-md", value_by_mode=None
+        )
+
+    assert captured["value_by_mode"] == {}
+
+
+@pytest.mark.asyncio
+async def test_list_tokens_denied_returns_empty():
+    with patch("scribe.services.design_systems.access") as acc:
+        acc.can_read_design_system = AsyncMock(return_value=False)
+        from scribe.services.design_systems import list_tokens
+        assert await list_tokens(user_id=1, design_system_id=3) == []
+
+
+# --- the project pointer ----------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_pointing_a_project_at_a_system_needs_write_on_the_project():
+    with patch("scribe.services.design_systems.access") as acc:
+        acc.can_write_project = AsyncMock(return_value=False)
+        acc.can_read_design_system = AsyncMock(return_value=True)
+        from scribe.services.design_systems import set_project_design_system
+        assert await set_project_design_system(1, project_id=5, design_system_id=3) is False
+
+
+@pytest.mark.asyncio
+async def test_pointing_a_project_needs_only_READ_on_the_system():
+    """Consuming a design system is not changing it, so a system reachable
+    through another project is a legitimate choice here. Requiring write would
+    make a shared family style unusable by the people it was shared with."""
+    project = MagicMock(deleted_at=None, design_system_id=None)
+    mock_session = _make_mock_session()
+    mock_session.get = AsyncMock(return_value=project)
+
+    with patch("scribe.services.design_systems.async_session") as mock_cls, \
+         patch("scribe.services.design_systems.access") as acc:
+        acc.can_write_project = AsyncMock(return_value=True)
+        acc.can_read_design_system = AsyncMock(return_value=True)
+        acc.can_write_design_system = AsyncMock(return_value=False)
+        mock_cls.return_value = mock_session
+        from scribe.services.design_systems import set_project_design_system
+        assert await set_project_design_system(1, project_id=5, design_system_id=3) is True
+
+    assert project.design_system_id == 3
+
+
+@pytest.mark.asyncio
+async def test_clearing_a_projects_design_system_skips_the_system_acl():
+    """Un-styling a project must not require permission on the system it is
+    letting go of — including one that has since been deleted."""
+    project = MagicMock(deleted_at=None, design_system_id=3)
+    mock_session = _make_mock_session()
+    mock_session.get = AsyncMock(return_value=project)
+
+    with patch("scribe.services.design_systems.async_session") as mock_cls, \
+         patch("scribe.services.design_systems.access") as acc:
+        acc.can_write_project = AsyncMock(return_value=True)
+        acc.can_read_design_system = AsyncMock(return_value=False)
+        mock_cls.return_value = mock_session
+        from scribe.services.design_systems import set_project_design_system
+        assert await set_project_design_system(1, project_id=5, design_system_id=None) is True
+
+    assert project.design_system_id is None
+    acc.can_read_design_system.assert_not_awaited()