feat(design-systems): resolve the chain, and keep the argument not the verdict

Milestone #254 step 2 (#2287). `resolve_tokens` flattens a system's inheritance
chain into its effective token set — walk to the root, deepest wins by token
name. Pure and duck-typed, so a test states a whole hierarchy in literals and
the service hands the same function ORM rows.

**Provenance is stored as the contest, not the winner.** A ResolvedToken carries
every system that offered a value, per mode, deepest first — `[0]` won and
`[1:]` are what it shadowed. "Which system supplied this?" and "what did it
override?" are then two reads of one list and cannot disagree, where a winner
plus a separate provenance field would be two things to keep in step.

**Merging is per (name, MODE), and that is the storage decision paying off.** A
system that deepens one accent for light backgrounds while leaving dark alone
owns `base` and still inherits `dark`. A token-level "overridden here" flag
would have to lie about one of them, and the two-column shape could not have
represented it at all.

Metadata cascades separately by the same deepest-wins rule, with one exception:
`order_index` treats 0 as UNSTATED rather than "first", because 0 is the column
default. Reading it as a real value would let a colour-only override drag its
token to the top of its group — a visible reshuffle in return for a change that
touched nothing structural.

One fix to step 1 while wiring this up: `_parent_map` is now scoped to the
SYSTEM'S OWNER rather than the caller. A caller reading through a shared project
owns no link in the chain, so the caller-scoped version would have handed them
an empty forest and truncated the cascade to a single system — a page rendering
with plausible wrong values and no error anywhere. The ACL already grants read
along the whole chain; this is the loading side keeping that promise, and it now
has a test naming the shared-project case.

`BASE_MODE` moves from the model to the cascade module, where it belongs: it is
a resolution rule, not a storage fact, and design_cascade.py deliberately
imports nothing so both access.py and the service can depend on it.

src/scribe/services/design_systems.py

@@ -21,7 +21,12 @@ from scribe.models import async_session
 from scribe.models.design_system import DesignSystem, DesignToken
 from scribe.models.project import Project
 from scribe.services import access
-from scribe.services.design_cascade import would_cycle
+from scribe.services.design_cascade import (
+    ResolvedToken,
+    ancestry,
+    resolve_tokens,
+    would_cycle,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -36,17 +41,23 @@ class DesignSystemCycle(ValueError):
     """
 
 
-async def _parent_map(session, user_id: int) -> dict[int, int | None]:
-    """`{id: parent_id}` for the caller's live systems — the hierarchy's shape.
+async def _parent_map(session, owner_user_id: int) -> dict[int, int | None]:
+    """`{id: parent_id}` for one owner's live systems — the hierarchy's shape.
 
-    Owner-scoped, which is also the constraint on parenting: you can only build
-    a chain out of systems you own. A borrowed link would let someone else's
-    delete or re-parent silently restyle your app.
+    Scoped to the OWNER of the systems, not the caller, and the distinction is
+    load-bearing on the read path: a caller reading through a shared project
+    does not own any link in the chain, and a caller-scoped map would hand them
+    an empty forest and a cascade truncated to one system. They would get a page
+    that renders with plausible wrong values and no error anywhere.
+
+    Owner-scoping is also the constraint on parenting: a chain may only be built
+    from systems its owner controls, or someone else's delete or re-parent would
+    silently restyle your app.
     """
     rows = (
         await session.execute(
             select(DesignSystem.id, DesignSystem.parent_id).where(
-                DesignSystem.owner_user_id == user_id,
+                DesignSystem.owner_user_id == owner_user_id,
                 DesignSystem.deleted_at.is_(None),
             )
         )
@@ -131,7 +142,9 @@ async def update_design_system(
                 if not await access.can_write_design_system(user_id, parent_id):
                     return None
             if would_cycle(
-                design_system_id, parent_id, await _parent_map(session, user_id)
+                design_system_id,
+                parent_id,
+                await _parent_map(session, system.owner_user_id),
             ):
                 raise DesignSystemCycle(
                     f"Design system {design_system_id} cannot inherit from "
@@ -213,6 +226,47 @@ async def list_tokens(user_id: int, design_system_id: int) -> list[DesignToken]:
         return list(rows.scalars().all())
 
 
+async def resolve_design_system(
+    user_id: int, design_system_id: int
+) -> list[ResolvedToken] | None:
+    """A system's EFFECTIVE token set — everything it inherits, with its own on top.
+
+    None when the caller may not read the system; an empty list when the chain
+    genuinely holds no tokens, which is an ordinary state for a system that has
+    just been created.
+
+    Two queries regardless of how deep the chain runs: one for the hierarchy's
+    shape, one for every token in it. The flattening itself is
+    `design_cascade.resolve_tokens` — pure, so the cascade rule is tested
+    without a database and this function is only the loading.
+    """
+    if not await access.can_read_design_system(user_id, design_system_id):
+        return None
+    async with async_session() as session:
+        system = await session.get(DesignSystem, design_system_id)
+        if system is None or system.deleted_at is not None:
+            return None
+
+        parents = await _parent_map(session, system.owner_user_id)
+        chain = ancestry(design_system_id, parents)
+
+        rows = (
+            await session.execute(
+                select(DesignToken)
+                .where(
+                    DesignToken.design_system_id.in_(chain),
+                    DesignToken.deleted_at.is_(None),
+                )
+                .order_by(DesignToken.order_index.asc(), DesignToken.name.asc())
+            )
+        ).scalars().all()
+
+    tokens_by_system: dict[int, list[DesignToken]] = {}
+    for token in rows:
+        tokens_by_system.setdefault(token.design_system_id, []).append(token)
+    return resolve_tokens(design_system_id, parents, tokens_by_system)
+
+
 async def update_token(
     user_id: int, token_id: int, **fields: object
 ) -> DesignToken | None: