feat(design-systems): the model, the parent chain, and the guard on it
CI & Build / Python lint (push) Successful in 3s
CI & Build / Plugin hooks (push) Successful in 7s
CI & Build / integration (push) Successful in 18s
CI & Build / TypeScript typecheck (push) Successful in 20s
CI & Build / Python tests (push) Successful in 42s
CI & Build / Build & push image (push) Successful in 27s

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.
This commit is contained in:
2026-07-30 16:54:41 -04:00
parent 4ca3ab02c4
commit 03b3998585
13 changed files with 1022 additions and 3 deletions
+61
View File
@@ -0,0 +1,61 @@
"""The design-system cascade, as pure functions over already-loaded rows.
Deliberately free of every database and service import — including
`services/access.py`, which needs `ancestry` to answer "can this caller read
this system?" and would otherwise form an import cycle with the service that
needs `access` back. A module that imports nothing can be imported by both.
Being pure is also what makes the cascade rule testable without a database:
these take a plain `{id: parent_id}` map, so a test states the shape of a
hierarchy in one literal instead of building one.
"""
from collections.abc import Mapping
def ancestry(system_id: int, parents: Mapping[int, int | None]) -> list[int]:
"""The inheritance chain from `system_id` up to its root, nearest first.
Includes `system_id` itself at index 0, because resolution wants
deepest-to-shallowest and the system being resolved is the deepest link.
A system missing from `parents` terminates the chain rather than raising: a
parent whose row was soft-deleted or filtered out is a truncated chain, not
a failed request.
The visited-set is defensive, not the primary guard — writes already refuse
to create a cycle (`would_cycle`). It is here because a loop introduced by a
direct DB edit or a future bug must degrade to a truncated chain instead of
spinning forever. Truncation shows up in the result; a hang shows up as an
outage.
"""
chain: list[int] = []
seen: set[int] = set()
current: int | None = system_id
while current is not None and current not in seen:
seen.add(current)
chain.append(current)
current = parents.get(current)
return chain
def would_cycle(
system_id: int,
proposed_parent_id: int | None,
parents: Mapping[int, int | None],
) -> bool:
"""Would making `proposed_parent_id` the parent of `system_id` close a loop?
True when the proposed parent IS the system, or already inherits from it.
The walk goes UP from the proposed parent, which is the cheap direction —
each system has at most one parent, so the chain is a line. Asking the
equivalent downward question ("is the proposed parent among my
descendants?") would mean searching a whole forest for the same answer.
`proposed_parent_id=None` clears the parent and can never cycle.
"""
if proposed_parent_id is None:
return False
if proposed_parent_id == system_id:
return True
return system_id in ancestry(proposed_parent_id, parents)