cgalo5758
ac2760a0fe
Write the eight domain-model cards under `docs/models/`, mark M10 10i Done, and update the design docs to v16. Also records Doc 44, which ratifies Decisions 129-133 as amended, and the Doc-39 conformance check that satisfied its gate.
49 lines
4.5 KiB
Markdown
49 lines
4.5 KiB
Markdown
---
|
|
title: "Domain Model Cards"
|
|
audience: [developer]
|
|
summary: "One card per domain model: purpose, invariants, dimensions, drift traps, and open questions, each claim cited to the migration, file, or decision that enforces it."
|
|
---
|
|
|
|
# Domain Model Cards
|
|
|
|
Each card in this directory describes one domain model as it is actually built, so a maintainer can modify that model without re-deriving its rules from migrations, specs, and decision documents. The cards are the **descriptive** home for the as-built models; the **normative** record — the designed schema, the decision log, the numbered design documents, and the glossary — lives in the synced `design/` directory (Decision 141, `design/documents/doc-43-schema-topology-and-documentation-division.md`). Migrations are the ground truth for as-built claims.
|
|
|
|
The catalog was motivated by the survey in `status/model-inventory-2026-07-02.md`, which traced the majority of a 56-finding UX audit to model-attributable causes: rules that lived only in prose, invariants enforced nowhere, and dimensions that were easy to conflate because no single page named them side by side.
|
|
|
|
## The cards
|
|
|
|
- [Product / catalog](product-catalog.md) — how capabilities are packaged, priced, and sold; the dissolved kind taxonomy and the shape views that replaced it.
|
|
- [Payments and Billing](payments-billing.md) — billing accounts, subscriptions, invoices and payments projected from Stripe, scheduled changes as intent, and the reconciler.
|
|
- [Plan Ladders and Transitions](plan-ladders-transitions.md) — ranked tiers, who occupies which rung, the append-only audit, and the conferral functions as sole writers.
|
|
- [Entitlements](entitlements.md) — resource keys, sets and rules, grants as decrees, provisions as delivery, and the materializer.
|
|
- [Resource Pools](resource-pools.md) — the per-organization container: workspace assignments, the two resolution directions, and pool-grain usage.
|
|
- [Providers and Integrations](provider-integration.md) — the registry, boot-time manifests, resource-key ownership, and the shared substrate.
|
|
- [Domains Registry](domains-registry.md) — claims as subtree ownership, placements as the only thing that serves, and the anti-abuse ledger.
|
|
- [Identity, Organizations, and Workspaces](identity-organization-workspace.md) — users vs persons, the containment ladder, org types as policy, and first-login provisioning.
|
|
|
|
A new domain model is not considered documented until its card exists and is listed here.
|
|
|
|
## Card anatomy
|
|
|
|
Every card has four sections in this order:
|
|
|
|
- **Purpose** — what the model owns and why it exists, in plain present tense.
|
|
- **Where this lives** — a map of the model's pieces: each table, view, function, and code file, with one line saying what it is. Locations live here, not scattered through the body.
|
|
- **Invariants** — the rules the model guarantees, one per numbered entry so reviews can cite "invariant 3". Each entry carries an enforcement tag matching the actual mechanism: **[db]** means the database schema rejects violations outright; **[db-code]** means the database functions are written to uphold the rule, so reviews must protect it when they change; **[app]** means only application code upholds the rule, so new code paths must uphold it too.
|
|
- **Dimensions** — the orthogonal axes a maintainer must hold simultaneously, each defined where it is named.
|
|
|
|
Cards describe the model as it is today, for a reader who knows nothing yet. That means: no history, no decision numbers, no change narrative in the body — a card introduces every table, column, view, and concept before or where it first uses it. Drift between design and code, open questions, and other bookkeeping live in `status/issues.md` under "Model documentation", not in the cards.
|
|
|
|
## Style contract
|
|
|
|
Card prose follows these rules, and edits are reviewed against them:
|
|
|
|
- Write for someone with zero context: never assume the reader knows a term, a table, or an internal codename you haven't introduced.
|
|
- Name the agent: state what acted and what it acted on.
|
|
- Give each verb its own object; do not let one object serve two verbs.
|
|
- Connect clauses with explicit causal or temporal words (because, so, when, after) — never with a bare comma.
|
|
- Replace every metaphor or compressed phrase with the literal claim it stands for.
|
|
- Give every count or statistic its denominator.
|
|
|
|
A change that alters an invariant, dimension, or map entry recorded on a card must update that card in the same change (see `openspec/specs/model-catalog/spec.md` once this change archives).
|