@turystack/modeling 1.0.1

package/00-overview.md

@@ -0,0 +1,96 @@
+# Overview
+
+**Rules defined here:** none — every id below is owned by another section.
+
+## The mental model
+
+A Turystack product is modelled in three layers, and confusing them is the
+origin of most of the damage.
+
+**The shape** is what this skill governs: tables, columns, keys, cardinalities,
+tenancy. It is the slowest thing in the system to change, because rows already
+exist in it. A wrong boundary in code is a refactor; a wrong column in a table
+with four million rows is a migration, a backfill, and a window where both
+shapes must be true at once.
+
+**The rules** are what the domain enforces on that shape: a second workspace is
+refused, a membership cannot outlive its organization, an OTP is consumed once.
+Rules live in use cases, not in the schema — but the schema decides which rules
+are *possible* to express and which are merely hoped for.
+
+**The presentation** is what an application shows about the shape: a workspace
+selector, a role picker. Presentation is never where a rule is enforced
+(`ARC-SEC-2`).
+
+The line between the shape and the rules is where the expensive mistakes are.
+Encoding a *policy* in the shape is the most common one: a customer who buys the
+single-workspace plan does not get a different schema, because next quarter they
+buy the other plan and the difference becomes a data migration instead of a
+setting. See `EVO-3`.
+
+## The five that cost the most
+
+1. **A policy modelled as a shape.** "This customer only has one workspace" is a
+   rule. Model the general case and constrain it. `EVO-3`
+2. **A row that cannot say which customer it belongs to.** Reachable in
+   principle, through four joins, is not the same as scoped. `SCP-2`
+3. **Uniqueness that forgot the tenant.** `unique(slug)` across all customers
+   means the second customer cannot use the obvious name — and worse, that a
+   lookup by slug can cross a tenant. `SCP-5`
+4. **A polymorphic foreign key.** `target_type` + `target_id` buys flexibility
+   by giving up every referential guarantee the database offers. `REL-6`
+5. **A null with no stated meaning.** `workspace_id IS NULL` is law when the
+   model says it means *the whole organization*, and a bug when nobody wrote
+   that down. `TAB-7`
+
+## Namespaces
+
+| Namespace | Owns |
+| --- | --- |
+| `TAB` | What becomes a table; identity, keys, columns, naming, types |
+| `REL` | Cardinality, join tables, optional relationships, ownership, cascade |
+| `SCP` | Tenancy: which column carries the customer, scoped uniqueness, cross-tenant reads |
+| `EVO` | How a model changes once rows exist |
+| `IAM` | The identity and access model |
+
+Model namespaces are allocated as models are written: `IAM` today,
+`BIL`, `NTF` and the rest as they land. A model file never redefines a
+generic rule; it cites it.
+
+## Cited from elsewhere
+
+These are law, and they are owned by another skill. They appear here because a
+modelling decision routinely depends on them.
+
+| Owner › Id | What it says |
+| --- | --- |
+| `turystack-architecture-pattern` › `ARC-SEC-1` | Scope comes from the authenticated context, never from a client field |
+| `turystack-architecture-pattern` › `ARC-SEC-3` | Authorization is operation **plus** resource |
+| `turystack-architecture-pattern` › `ARC-SEC-12` | A permission identifier comes from the product's single catalogue |
+| `turystack-architecture-pattern` › `ARC-DAT-3` | Erasure has a declared path reaching every place the data landed |
+| `turystack-architecture-pattern` › `ARC-DAT-4` | Soft delete is a state, not a synonym for erased |
+| `turystack-backend-pattern` › `REP-1` | A repository uses data verbs (`find`, `save`, `update`), never business operation names |
+| `turystack-backend-pattern` › `REP-L1` | Filters, sorting and pagination go through `@turystack/query-dsl` |
+| `turystack-backend-pattern` › `ENT-1` | The entity owns the invariants; the use case delegates to a `checkIf…` guard |
+| `turystack-backend-pattern` › `CTL-2` | One HTTP surface per consumer, each with its own prefix and OpenAPI document |
+| `turystack-backend-pattern` › `ENT-5` | Field order: PK → FKs → important → less important → booleans → status → timestamps and audit |
+| `turystack-backend-pattern` › `SCH-8` | The same order inside the schema |
+
+## How a canonical model is written
+
+Every `1x-model-*.md` has the same five parts, and the order matters because
+each part answers a question raised by the one before it.
+
+1. **What it is for** — the product question the model answers, in a paragraph.
+   A model whose purpose cannot be stated in a paragraph is two models.
+2. **The diagram** — an ASCII sketch of the entities and their cardinalities.
+   It is the thing people actually read, so it comes before the tables.
+3. **The tables** — column by column, with type, nullability and what a null
+   means — including the ones every table shares (`<table>_id`, `created_at`,
+   `updated_at`, `deleted_at`, the audit trio). A table you have to combine
+   with a legend to know its real shape is a table that gets read wrong.
+4. **Invariants** — `<MODEL>-n`, the rules that are true of this model and
+   that no generic rule can express.
+5. **What the CLI generates** — the exact tables, seeds and rules the scaffold
+   writes, so a diff between a generated repository and this file is a bug in
+   one of the two.

package/01-entities.md

@@ -0,0 +1,147 @@
+# Entities
+
+**Rules defined here:** `TAB-1` · `TAB-2` · `TAB-3` · `TAB-4` ·
+`TAB-5` · `TAB-6` · `TAB-7` · `TAB-8` · `TAB-9` — the law is the
+*Invariants* table.
+
+## Concept
+
+What deserves a table, what its rows are called, and what every row carries.
+This is the cheapest section to get right and the most expensive to revisit: a
+column name survives longer than the team that chose it.
+
+## Invariants
+
+| ID | Law (one line) | Class | Gate |
+| --- | --- | --- | --- |
+| TAB-1 | A table is a noun with its own identity and its own lifetime. A value that only exists as part of one parent row, and is always read with it, is a column — not a table. | constitutional | `manual` |
+| TAB-2 | The primary key carries the table's name — `user_id`, `invitation_id` — and is a UUIDv7 generated by the application. A foreign key carries the same name as the key it points at, so `membership.user_id` needs no explanation. A natural key is never the primary key; it is a scoped unique constraint. | constitutional | `manual` |
+| TAB-3 | Every table carries `created_at` and `updated_at`. A table whose rows can be withdrawn carries `deleted_at`, and withdrawal sets it (`ARC-DAT-4`). | constitutional | `manual` |
+| TAB-4 | A closed set of values the product owns is a `text` column plus a Zod enum in the schema. Never a database enum type. A set the customer can extend is a table. The question is "can a customer add one?", not "how many are there?". | constitutional | `manual` |
+| TAB-5 | Names: table singular `snake_case`; foreign key `<referenced_table>_id`; boolean `is_`/`has_`; instant `_at`; duration with its unit (`timeout_seconds`). | constitutional | `manual` |
+| TAB-6 | Money is an integer in minor units, always — the column is named for the thing (`price`), not for the unit. A currency column sits beside it. Never a float. | constitutional | `manual` |
+| TAB-7 | A nullable column has one stated meaning for its null, written in the model. Absence is never encoded as `''`, `0`, `-1` or the epoch. | constitutional | `manual` |
+| TAB-8 | A secret is stored as a hash, never as the value (`ARC-SEC-6`), and the column says so: `password_hash`, `code_hash`. | constitutional | `manual` |
+| TAB-9 | A table a person writes to carries `created_by`, `updated_by` and — where rows are withdrawn — `deleted_by` (`ARC-SEC-9`, `ENT-5`). They are `text` and not foreign keys, because the principal is not always a row in `user`: the seed and a scheduled job write too, and there the value is null. | constitutional | `manual` |
+
+## Why a table is a lifetime, not a shape
+
+The temptation is to make a table out of anything with more than one field. The
+question that actually decides it is: **can this thing be created, changed or
+removed on its own?**
+
+An address that belongs to one organization, is always shown with it, and dies
+with it, is columns on `organization` — or a JSON column if it is genuinely
+opaque. An address a customer maintains in a list, selects at checkout, and
+keeps after the order is delivered, is a table: it has its own lifetime.
+
+Getting this wrong in the cheap direction (a table that should have been
+columns) costs a join and some ceremony. Getting it wrong in the expensive
+direction (columns that should have been a table) costs a migration the day the
+customer wants a second one — and there is always a second one.
+
+## Why UUIDv7 and not a sequence
+
+Three reasons, in the order they bite:
+
+- An identifier that arrives from the client can be validated as an identifier
+  without a database round trip, and cannot be guessed by incrementing.
+- A row can be created by the application before the transaction commits, so a
+  parent and its children are built in one pass without `RETURNING` juggling.
+- UUIDv7 sorts by creation time, so the index behaves like a sequence's does —
+  which is the one thing UUIDv4 gets badly wrong.
+
+The natural key still matters; it is just not the primary key. An organization
+has a `slug` that people type and that must be unique **within its scope**
+(`SCP-5`) — and that can change without rewriting every row that points at
+the organization.
+
+The name carries the table because a join reads better than it selects. In
+`membership`, `user_id` and `organization_id` say what they point at without a
+lookup; with `id` as the primary key everywhere, half the columns in a
+four-table query are called `id` and the reader has to track which alias owns
+which. It also makes the foreign key and the key it references literally the
+same name, which is what lets a schema be checked by pattern rather than by
+memory.
+
+## Why the closed set is not a database enum
+
+A Postgres enum looks like the honest choice: the database refuses a value
+nobody declared. What it actually buys is a type that only DDL can change.
+
+Adding a value is `ALTER TYPE … ADD VALUE`, which means the deploy that
+introduces `SUSPENDED` in the code is now coupled to a migration — and the two
+land at different moments, so there is a window where one of them is wrong.
+Removing a value is not supported at all. Reordering is not supported.
+Renaming rewrites every dependent view.
+
+So the column is `text` and the closed set lives in the Zod schema, which is
+already the contract the edge validates against (`ARC-SEC-4`). One definition,
+versioned with the code that branches on it, and adding a value is a deploy.
+
+What the database gives up is a check it was doing for free. That is the trade,
+and it is worth it because the value only ever arrives through a validated
+schema — a write that bypasses validation is a bug the enum would have caught
+one layer too late anyway.
+
+The rule flips the moment a **customer** can add a value. Then it is not a
+closed set at all: it is a table, with an organization on it (`SCP-2`).
+
+## Why the null needs a meaning
+
+`membership.workspace_id IS NULL` means *this membership grants its role across
+the whole organization*. That sentence is law: queries branch on it, the admin
+UI renders differently for it, and a person reading the table without it would
+reasonably guess "workspace not chosen yet".
+
+A nullable column with no stated meaning eventually acquires two, from two
+different authors, and every read after that is a coin flip. If a column can be
+null for more than one reason, the reasons are a state column and the null is
+derived from it.
+
+## The order of the columns
+
+Columns are written in the order `ENT-5` and `SCH-8` require, and this file
+lists them that way for the same reason the entity and the schema do:
+
+```text
+PK → FKs → important → less important → booleans → status → timestamps + audit
+```
+
+The last group is `created_at`, `updated_at`, `deleted_at`, then `created_by`,
+`updated_by`, `deleted_by`.
+
+The order is not cosmetic. A model, a schema and an entity that agree top to
+bottom can be read against each other in one pass, and a column added in the
+wrong group is visible before anyone has to compare three files line by line.
+Biome sorts keys alphabetically everywhere except the entity, where
+`@turystack/backend-config` turns `useSortedKeys` off precisely so this
+semantic order can exist.
+
+## Never do
+
+```text
+❌  deleted BOOLEAN                      a state pretending to be a fact; when was it?
+✅  deleted_at TIMESTAMPTZ NULL          null means live (ARC-DAT-4)
+
+❌  price NUMERIC / price FLOAT          rounding, and no currency
+✅  price INTEGER + currency CHAR(3)     minor units, always (TAB-6)
+
+❌  CREATE TYPE organization_status AS ENUM (…)   only DDL can change it
+✅  status TEXT + z.enum([...]) in the schema     (TAB-4)
+
+❌  email VARCHAR PRIMARY KEY            the day someone changes it, every FK breaks
+✅  user_id UUID PRIMARY KEY + unique(email)
+
+❌  id UUID PRIMARY KEY                  which id, in a query that joins four tables?
+✅  user_id UUID PRIMARY KEY             the FK pointing at it has the same name (TAB-2)
+
+❌  expires_at DEFAULT '1970-01-01'      a sentinel meaning "never"
+✅  expires_at TIMESTAMPTZ NULL          null means "does not expire" — stated in the model
+
+❌  otp.code VARCHAR                     a stolen backup is a stolen set of codes
+✅  otp.code_hash VARCHAR                (TAB-8, ARC-SEC-6)
+
+❌  created_by UUID REFERENCES user(id)  the seed and the cron have no user row
+✅  created_by TEXT NULL                 null means no authenticated principal (TAB-9)
+```

package/02-relationships.md

@@ -0,0 +1,86 @@
+# Relationships
+
+**Rules defined here:** `REL-1` · `REL-2` · `REL-3` · `REL-4` ·
+`REL-5` · `REL-6` · `REL-7` — the law is the *Invariants* table.
+
+## Concept
+
+Which side holds the key, when a relationship becomes a table of its own, what
+an optional relationship means, and who owns whose lifetime.
+
+## Invariants
+
+| ID | Law (one line) | Class | Gate |
+| --- | --- | --- | --- |
+| REL-1 | Cardinality is declared in the model, in words, before it is written in a migration. "One organization has many workspaces; a workspace has exactly one organization" is the artefact — the foreign key is its consequence. | constitutional | `manual` |
+| REL-2 | One-to-many puts the foreign key on the many side. An array column, a comma-separated string and a JSON list of ids are not relationships. | constitutional | `manual` |
+| REL-3 | Many-to-many is an explicit table with its own key (`<table>_id`), its own timestamps, and a unique constraint on the pair. It is named for what it is (`membership`, `role_permission`), never `a_b`. | constitutional | `manual` |
+| REL-4 | An optional relationship is a nullable foreign key whose null carries the meaning the model states (`TAB-7`). It is never a second table that exists only to represent absence. | constitutional | `manual` |
+| REL-5 | Exactly one parent owns a row's lifetime, and the model names it. Deleting the owner reaches the row; deleting a non-owner never silently takes it. | constitutional | `manual` |
+| REL-6 | No polymorphic foreign key. If a row can point at two kinds of parent, it holds two nullable foreign keys and a check constraint that exactly one is set. | constitutional | `manual` |
+| REL-7 | A foreign key may cross domain packages only in the direction the packages already depend (`ARC-LAY-1`, `ARC-LAY-4`). Two domains that need to point at each other are one domain, or one of them holds an id without a constraint and reads through the other's API. | constitutional | `manual` |
+
+## Why the join table has its own id
+
+A composite primary key on `(role_id, permission_id)` is smaller and, for a
+week, simpler. Then one of these happens, and all of them happen eventually:
+
+- someone needs to know *when* the permission was granted, and to whom;
+- an audit trail needs to reference the grant itself;
+- the ORM needs a stable handle for the row to update it;
+- the pair has to become a triple, and every foreign key pointing at the pair
+  has to change shape.
+
+The key costs 16 bytes and buys all four. The unique constraint on the pair is
+what preserves the guarantee the composite key was there for — so nothing is
+lost, and it is the constraint, not the key, that should have been carrying that
+meaning from the start.
+
+## Why polymorphic keys are refused
+
+`comment(target_type, target_id)` looks like it saves four tables. What it
+actually does is move referential integrity out of the database and into the
+hope that every writer remembers. There is no foreign key, so a deleted parent
+leaves orphans; there is no index the planner can use across types; and every
+read needs a branch before it can join.
+
+Two nullable foreign keys with `CHECK (num_nonnulls(order_id, invoice_id) = 1)`
+keeps the guarantee and reads honestly. When the count of possible parents grows
+past three or four, that is the model telling you the child is really its own
+concept with its own table per parent, or that the parents share a supertype
+that deserves a table.
+
+## Ownership and cascade
+
+Ownership is a modelling statement, not a database setting: *this row cannot
+outlive that one*. A `workspace` cannot outlive its `organization`. A
+`membership` cannot outlive either its `user` or its `organization` — but it is
+**owned** by the organization, because that is the lifetime the product manages.
+
+Cascade follows ownership and nothing else. A foreign key that is not ownership
+— `membership.role_id` — restricts instead: a role in use cannot be deleted, and
+the product has to say what happens to the memberships first. That refusal is
+the point. A cascade there would silently strip people's access.
+
+Erasure of a person is not a cascade from `user`; it is the declared path in
+`ARC-DAT-3`, because the data landed in places no foreign key reaches.
+
+## Never do
+
+```text
+❌  workspace.member_ids UUID[]          no constraint, no index, no join
+✅  membership(user_id, organization_id, workspace_id?)   (REL-2, REL-3)
+
+❌  user_role(user_id, role_id) PK(user_id, role_id)
+✅  membership(membership_id, user_id, organization_id, workspace_id?, role_id,
+       unique(user_id, organization_id, workspace_id))    (REL-3)
+
+❌  attachment(owner_type, owner_id)     no foreign key, no integrity
+✅  attachment(order_id?, invoice_id?) + CHECK exactly one   (REL-6)
+
+❌  ON DELETE CASCADE on membership.role_id     deleting a role strips access
+✅  ON DELETE RESTRICT — the product decides what happens first   (REL-5)
+
+❌  user_without_workspace + user_with_workspace   two tables to model a null
+✅  workspace_id NULL, meaning stated in the model   (REL-4)
+```

package/03-scoping.md

@@ -0,0 +1,141 @@
+# Scoping
+
+**Rules defined here:** `SCP-1` · `SCP-2` · `SCP-3` · `SCP-4` ·
+`SCP-5` · `SCP-6` · `SCP-7` — the law is the *Invariants* table.
+
+## Concept
+
+Every Turystack product is multi-tenant from the first migration. This section
+is about the column that carries the tenant, and about the two questions that
+decide whether a leak between customers is possible at all: *can this row say
+who owns it?* and *can this query be written without saying it?*
+
+## Invariants
+
+| ID | Law (one line) | Class | Gate |
+| --- | --- | --- | --- |
+| SCP-1 | Every product row belongs to exactly one organization, and the model states the path. A table with no path to an organization is either platform-wide (a catalogue) or a modelling error, and the model says which. | constitutional | `manual` |
+| SCP-2 | A row read by scope carries `organization_id` directly, even when the value is reachable through a parent. Scoping through joins is how a filter gets forgotten. | constitutional | `manual` |
+| SCP-3 | The scope value comes from the authenticated context (`ARC-SEC-1`). A scope column is never populated from, or filtered by, a value the client sent. | constitutional | `manual` |
+| SCP-4 | A workspace-scoped row carries both `organization_id` and `workspace_id`. The organization stays because it is the tenant; the workspace narrows within it. | constitutional | `manual` |
+| SCP-5 | Every uniqueness rule includes its scope: `unique(organization_id, slug)`, never `unique(slug)`. A globally unique natural key is a deliberate, written exception. | constitutional | `manual` |
+| SCP-6 | A scoped read is **one** method, never two. `organizationId` is an optional field of its input schema, and the controller decides whether it is filled (`ARC-SEC-1`): forced from the authenticated profile on a client surface, absent on an internal one. There is no separate cross-organization method. | constitutional | `manual` |
+| SCP-7 | A read by id does not filter by scope. It fetches the row, and the entity's guard confirms the scope in the use case (`ENT-1`) — so a row belonging to another organization is refused by the domain rather than hidden by a `WHERE`. | constitutional | `manual` |
+
+## Why the column is denormalised
+
+`invoice_line` belongs to an `invoice`, which belongs to an `order`, which
+belongs to an `organization`. The tenant is reachable — three joins away. So the
+scoped read is:
+
+```sql
+SELECT il.* FROM invoice_line il
+JOIN invoice i ON i.id = il.invoice_id
+JOIN "order" o ON o.id = i.order_id
+WHERE o.organization_id = $1
+```
+
+Every one of those joins is a chance to omit the `WHERE`, and omitting it does
+not fail: it returns more rows, quietly, in an endpoint that looks like it
+works. The failure surfaces as a customer seeing another customer's data.
+
+With `organization_id` on `invoice_line`, the scoped read is one predicate, the
+index is one column, and — the part that matters — the shape makes the rule
+mechanically checkable: a query against a scoped table with no `organization_id`
+predicate is a finding a tool can raise, and that is impossible to check when
+the tenant lives three joins away.
+
+The cost is a denormalised column that must be written correctly on insert. That
+is a single place, in the repository, versus every read forever.
+
+## What is not scoped
+
+Three kinds of table legitimately have no `organization_id`, and the model must
+say which one applies:
+
+- **Catalogues owned by the code.** `permission` is seeded from the source and
+  is the same for every customer.
+- **The person.** `user` is not scoped: one person can belong to several
+  organizations, and that is exactly what `membership` expresses.
+- **Platform-wide records.** Rows the operator owns. They live under the
+  platform organization rather than under nothing, so `organization_id` is
+  present and points there — see `10-model-iam.md`.
+
+Anything else with no path to an organization is unfinished modelling.
+
+## Cross-tenant reads
+
+The backoffice exists to look across organizations, so the ability is real. What
+the model does **not** do is give it a method of its own.
+
+There is one read, and the scope is an optional field of its input. Who fills
+that field is the controller's decision, and `ARC-SEC-1` already states the
+three cases: a client surface forces it from the authenticated profile, an
+operator surface forces the operator organization's, and an internal surface
+leaves it out because querying across organizations is the point.
+
+```ts
+// the read — one method, data verbs only (REP-1), input built from the
+// canonical schemas through @turystack/query-dsl (REP-L1)
+findMany(input: { organizationId?: string; status?: OrderStatus })
+```
+
+```ts
+// client surface — the scope is forced, and never read from the request
+async list(
+  @AuthenticatedProfile() profile: IamProfile,
+  @Request(listOrdersRequest) req: RequestInput<typeof listOrdersRequest>,
+) {
+  return this.listOrders.execute({ ...req.query, organizationId: profile.organizationId })
+}
+
+// internal surface — no forced scope; organizationId is an optional query
+async list(@Request(listOrdersInternalRequest) req: RequestInput<typeof listOrdersInternalRequest>) {
+  return this.listOrders.execute(req.query)
+}
+```
+
+A second method named for crossing tenants would look safer and be worse: two
+implementations of the same query, drifting apart, and a filter that has to be
+remembered in one of them. One method with an optional scope keeps a single
+query, and moves the decision to the one layer that knows who is asking.
+
+What the model owes this arrangement is `SCP-2` — the column has to be on
+the row, or the optional filter has nothing to filter on.
+
+## Reading one row
+
+A read by id is not scoped, and that is deliberate:
+
+```ts
+const order = await this.orderRepository.findById(input.orderId)
+
+order.checkOrganization(input.organizationId) // ENT-1 — the entity refuses it
+```
+
+Filtering by scope in the query answers "not found" for a row that exists and
+belongs to someone else. Fetching it and letting the entity's guard refuse it
+answers with the denial the situation actually is, and puts the rule in the
+entity where every other invariant already lives. `find` returns one row,
+`findMany` returns rows, `findPaginated` returns a page — each taking the input
+its own read needs, and none of them growing a scoped variant.
+
+## Never do
+
+```text
+❌  findById(id) with no guard after it   returns any customer's row
+✅  findById(id) + entity.checkOrganization(scope)        (SCP-7, ENT-1)
+
+❌  unique(slug)                          customer B cannot use the obvious name
+✅  unique(organization_id, slug)         (SCP-5)
+
+❌  where: { organizationId: input.organizationId }    from the client
+✅  where: { organizationId: ctx.organizationId }      (ARC-SEC-1, SCP-3)
+
+❌  invoice_line with no organization_id, scoped through three joins
+✅  invoice_line.organization_id, written on insert       (SCP-2)
+
+❌  findMany() and findManyAcrossOrganizations()   two queries that will drift
+✅  findMany({ organizationId?: … }) — the controller fills it, or does not
+                                                         (SCP-6, ARC-SEC-1)
+```

package/04-evolution.md

@@ -0,0 +1,96 @@
+# Evolution
+
+**Rules defined here:** `EVO-1` · `EVO-2` · `EVO-3` · `EVO-4` ·
+`EVO-5` — the law is the *Invariants* table.
+
+## Concept
+
+A model with rows in it is a contract with everything already running against
+it. This section is how that contract changes without a window where the system
+is wrong.
+
+## Invariants
+
+| ID | Law (one line) | Class | Gate |
+| --- | --- | --- | --- |
+| EVO-1 | A change is additive first: add nullable, write both, backfill, then constrain. A migration that adds a `NOT NULL` column with no default to a populated table is refused. | constitutional | `manual` |
+| EVO-2 | A rename is add, copy, switch readers, drop — four deploys, not one `ALTER`. The old name stays until nothing reads it, and "nothing reads it" is verified, not assumed. | constitutional | `manual` |
+| EVO-3 | A choice a customer can flip is a policy, not a shape. Model the general case and constrain it with a domain rule; never generate a different schema per plan, per tier or per customer. | constitutional | `manual` |
+| EVO-4 | Dropping a column or table requires the erasure path (`ARC-DAT-3`) to be updated in the same change. Data that vanished from the schema did not vanish from the backups, the read models or the exports. | constitutional | `manual` |
+| EVO-5 | A catalogue seeded from code (`permission`) is owned by the code. The seed is idempotent, drift between code and table fails a gate, and nobody edits those rows by hand. | constitutional | `manual` |
+
+## Why the policy never becomes a shape
+
+This is the rule that pays for itself the most, so it is worth the example.
+
+A product offers two shapes of account: one organization with a single
+workspace, or one organization with many. The tempting move is to model them
+differently — no `workspace` table at all in the simple case, or
+`organization.workspace_id` instead of `workspace.organization_id`.
+
+What it costs the day a customer upgrades:
+
+- a data migration per customer, run live, on their data;
+- two code paths for every read that touches a workspace, forever, because both
+  shapes exist in production at once;
+- a scope column that means different things in different databases, which is
+  the exact condition under which `SCP-2` stops being checkable.
+
+Modelled as a policy instead: `workspace` always exists, always carries
+`organization_id`, and the single-workspace account simply has one — created
+with the organization. What the setting changes is a domain rule that refuses
+the second workspace, and whether the application renders a selector. Upgrading
+a customer is a settings change, and the schema never knew there were two
+products.
+
+The general form: **if a customer can change it, it is not allowed to be a
+shape.** Shapes change with migrations; policies change with a column value.
+
+## Additive, in four steps
+
+```text
+1. add          workspace.archived_at TIMESTAMPTZ NULL      deploy, nothing reads it
+2. write both   writers set it; readers still use the old signal
+3. backfill     one batch, restartable, with a count that proves it finished
+4. constrain    readers switch; the old signal is dropped in a later deploy
+```
+
+Steps 2 and 3 can share a deploy. Steps 1 and 4 cannot: between them there must
+be a moment where both the old and the new shape are true, because a rollback
+lands in that moment.
+
+The backfill produces a number, and the number is checked. "It ran" is not
+evidence; `0 rows remaining with archived_at IS NULL AND status = 'archived'`
+is.
+
+## Seeded catalogues
+
+`permission` exists in the database so foreign keys can point at it, but the
+list is in the source: it is the same for every customer, it is deployed with
+the code that enforces it, and a row nobody deployed is a permission nobody
+implements.
+
+So the seed is idempotent — insert what is missing, update what changed, and
+report what is in the table but not in the code. That last one is the important
+report: a permission that disappeared from the source while roles still grant it
+means people hold access to something that no longer exists, and that is a
+finding rather than a cleanup.
+
+## Never do
+
+```text
+❌  ALTER TABLE workspace ADD COLUMN kind TEXT NOT NULL     fails on any row
+✅  ADD COLUMN kind TEXT NULL → backfill → SET NOT NULL     (EVO-1)
+
+❌  ALTER TABLE user RENAME COLUMN name TO full_name        old readers 500
+✅  add full_name → write both → switch → drop name         (EVO-2)
+
+❌  if (plan === 'starter') { /* no workspace table */ }    two schemas
+✅  one schema; a rule refuses the second workspace         (EVO-3)
+
+❌  DROP TABLE otp                                           still in exports and backups
+✅  drop + update the erasure path in the same change        (EVO-4)
+
+❌  INSERT INTO permission ... run once, by hand
+✅  an idempotent seed the deploy runs, and a drift report   (EVO-5)
+```

package/10-model-iam.md

@@ -0,0 +1,579 @@
+# Model · IAM
+
+**Rules defined here:** `IAM-1` … `IAM-14` — the law is the *Invariants*
+table. Generic modelling rules are cited, never restated.
+
+## What it is for
+
+Who a person is, which customers they act for, and what they are allowed to do
+there. Every Turystack product is born with this model: the `auth` audience
+proves identity, and every other audience reads its scope and its permissions
+from here. It is the one model the CLI generates literally — a generated
+repository that differs from this file is a bug in one of the two.
+
+It answers three questions, and keeping them separate is the whole design.
+*Who are you* is `user`, and it is not scoped to anyone. *Where are you acting*
+is `membership`, which is the only place a person meets an organization. *What
+may you do there* is `role` → `permission`, resolved at sign-in into the session.
+
+## The model
+
+```text
+organization ──┬──< workspace
+  kind:        ├──< membership ─── user ──┬──< user_social_identity
+  CUSTOMER     │         │                └──< otp
+  PLATFORM     └──< invitation
+                          │
+                    role ─┘   both point at the same role
+                     │
+                     └──< role_permission >── permission
+                                              key: <audience>:<res>.<act>
+
+role.kind   ENVIRONMENT   every organization, shipped by the product
+            ORGANIZATION  one organization, written by the customer
+            BACKOFFICE    the platform only
+```
+
+Read the nullable foreign keys as sentences, because they are where the model
+does its work:
+
+- `membership.workspace_id IS NULL` — this role applies across the whole
+  organization.
+- `role.organization_id IS NULL` — the role is not one customer's; `kind` says
+  whether it is shipped to every organization or reserved for the platform.
+- `invitation.user_id IS NULL` — nobody has accepted it yet, and the person may
+  not exist in `user` at all.
+
+## How to read the tables
+
+Every column is listed, including the ones every table shares — a table you have
+to combine with a legend to know its real shape is a table that gets read wrong.
+
+The shared ones are: the key `<table>_id` (`TAB-2`), the timestamps
+`created_at` and `updated_at` (`TAB-3`), `deleted_at` where withdrawal is a
+state rather than an erasure (`ARC-DAT-4`), and the audit trio `created_by`,
+`updated_by`, `deleted_by` where a person writes the row (`TAB-9`).
+`@turystack/nestjs-database` stamps `created_by` and `updated_by` from the
+acting principal wherever the columns exist; the domain writes `deleted_by` when
+it withdraws the row. A table that deliberately omits a block says so under it,
+with the reason.
+
+Columns are in the order `ENT-5` and `SCH-8` require — **PK → FKs → important →
+less important → booleans → status → timestamps and audit** — so this file, the
+schema and the entity read the same way top to bottom.
+
+Every column whose values are listed is `text` with the set closed by a Zod enum
+in the schema, never a database enum type (`TAB-4`). The JSON under each
+table is the row as a repository returns it: camel case, same order, same
+columns.
+
+## The tables
+
+### `user`
+
+The person. Not scoped to an organization (`SCP-1`, third exception).
+
+| Column | Type | Null | Meaning |
+| --- | --- | --- | --- |
+| `user_id` | uuid | no | UUIDv7 (`TAB-2`) |
+| `name` | text | no | |
+| `email` | text | no | Lower-cased by the domain before every write; unique globally (`IAM-10`) |
+| `email_verified_at` | timestamptz | yes | Null means unverified |
+| `phone` | text | yes | E.164, `+` and digits. Null means the person gave none |
+| `phone_verified_at` | timestamptz | yes | Null means unverified — independent of the e-mail (`IAM-11`) |
+| `password_hash` | text | yes | Null means no password: this person signs in socially or by code (`IAM-8`) |
+| `password_changed_at` | timestamptz | yes | A session issued before this instant is refused. Null means a password was never set |
+| `locale` | text | no | BCP 47. The language an OTP, an invitation and a notification are written in |
+| `last_signed_in_at` | timestamptz | yes | Null means never signed in |
+| `created_at` | timestamptz | no | |
+| `updated_at` | timestamptz | no | |
+| `deleted_at` | timestamptz | yes | |
+| `created_by` | text | yes | Null when the person signed themselves up |
+| `updated_by` | text | yes | |
+| `deleted_by` | text | yes | |
+
+`unique(email)` · `unique(phone) where phone is not null`
+
+```json
+{
+  "userId": "01930f4e-6b21-7c3a-9f10-2c1a5b7d4e00",
+  "name": "Ana Ribeiro",
+  "email": "ana@acme.com",
+  "emailVerifiedAt": "2026-09-01T14:22:10.000Z",
+  "phone": "+5511998877665",
+  "phoneVerifiedAt": null,
+  "passwordHash": "$argon2id$v=19$m=65536,t=3,p=4$c29tZXNhbHQ$...",
+  "passwordChangedAt": "2026-09-01T14:20:02.000Z",
+  "locale": "pt-BR",
+  "lastSignedInAt": "2026-09-07T09:41:33.000Z",
+  "createdAt": "2026-09-01T14:20:02.000Z",
+  "updatedAt": "2026-09-07T09:41:33.000Z",
+  "deletedAt": null,
+  "createdBy": null,
+  "updatedBy": null,
+  "deletedBy": null
+}
+```
+
+`createdBy` is null because nobody was authenticated: the person signed
+themselves up. An operator creating a user from the backoffice leaves their id.
+
+### `user_social_identity`
+
+How a person proves themselves through a provider.
+
+| Column | Type | Null | Meaning |
+| --- | --- | --- | --- |
+| `user_social_identity_id` | uuid | no | UUIDv7 |
+| `user_id` | uuid → `user` | no | Owner (`REL-5`) |
+| `provider` | text | no | `APPLE` · `FACEBOOK` · `GOOGLE` · `MICROSOFT` |
+| `provider_id` | text | no | The subject the provider asserts. Stable across the person changing their e-mail there |
+| `provider_email` | text | yes | As asserted when the link was made. May differ from `user.email`, and is never treated as a verified address |
+| `last_used_at` | timestamptz | yes | Last sign-in through this provider. Null means linked but never used |
+| `created_at` | timestamptz | no | |
+| `updated_at` | timestamptz | no | |
+| `created_by` | text | yes | |
+| `updated_by` | text | yes | |
+
+`unique(provider, provider_id)` — one provider account maps to one
+person.
+
+**No soft delete.** Unlinking a provider removes the row, because a kept row
+would still hold `unique(provider, provider_id)` and refuse the re-link.
+A deliberate hard delete (`ARC-DAT-4`).
+
+```json
+{
+  "userSocialIdentityId": "01930f4e-7a02-7b55-8e31-9d4c0f2a6b11",
+  "userId": "01930f4e-6b21-7c3a-9f10-2c1a5b7d4e00",
+  "provider": "GOOGLE",
+  "providerId": "104729183746501928374",
+  "providerEmail": "ana@acme.com",
+  "lastUsedAt": "2026-09-07T09:41:33.000Z",
+  "createdAt": "2026-09-03T11:02:47.000Z",
+  "updatedAt": "2026-09-07T09:41:33.000Z",
+  "createdBy": "01930f4e-6b21-7c3a-9f10-2c1a5b7d4e00",
+  "updatedBy": "01930f4e-6b21-7c3a-9f10-2c1a5b7d4e00"
+}
+```
+
+### `otp`
+
+A one-time code. Single-use, bounded, and purposeful.
+
+| Column | Type | Null | Meaning |
+| --- | --- | --- | --- |
+| `otp_id` | uuid | no | UUIDv7 |
+| `user_id` | uuid → `user` | no | Owner |
+| `purpose` | text | no | `EMAIL_VERIFICATION` · `PASSWORD_RESET` · `SIGN_IN` |
+| `channel` | text | no | `EMAIL` · `SMS` — which contact carried it |
+| `target` | text | no | The address or number it was sent to, frozen at issue (`IAM-12`) |
+| `code_hash` | text | no | Hashed (`TAB-8`) |
+| `expires_at` | timestamptz | no | |
+| `consumed_at` | timestamptz | yes | Null means still usable (`IAM-6`) |
+| `attempts` | integer | no | Failed verifications, default `0`, bounded by the domain |
+| `created_at` | timestamptz | no | |
+| `updated_at` | timestamptz | no | |
+
+Index on `(user_id, purpose)` where `consumed_at is null` — the lookup every
+verification performs.
+
+**No audit** — the actor is the `user_id` already on the row. **No soft delete**
+— a spent code is pruned by retention (`ARC-DAT-1`).
+
+```json
+{
+  "otpId": "01930f50-1c88-7d09-b2a7-5e6f7a8b9c00",
+  "userId": "01930f4e-6b21-7c3a-9f10-2c1a5b7d4e00",
+  "purpose": "SIGN_IN",
+  "channel": "EMAIL",
+  "target": "ana@acme.com",
+  "codeHash": "$argon2id$v=19$m=19456,t=2,p=1$b3Rwc2FsdA$...",
+  "expiresAt": "2026-09-07T09:51:00.000Z",
+  "consumedAt": null,
+  "attempts": 0,
+  "createdAt": "2026-09-07T09:41:00.000Z",
+  "updatedAt": "2026-09-07T09:41:00.000Z"
+}
+```
+
+### `organization`
+
+The tenant. The root of every scope in the product.
+
+| Column | Type | Null | Meaning |
+| --- | --- | --- | --- |
+| `organization_id` | uuid | no | UUIDv7 |
+| `kind` | text | no | `CUSTOMER` · `PLATFORM` (`IAM-2`) |
+| `name` | text | no | What a person sees |
+| `slug` | text | no | Unique globally — it is the top of the scope tree, so there is nothing to scope it by |
+| `workspace_mode` | text | no | `SINGLE` · `MULTI` (`IAM-9`) |
+| `status` | text | no | `ACTIVE` · `SUSPENDED`. A suspended organization still authenticates its people and resolves no scope for them |
+| `created_at` | timestamptz | no | |
+| `updated_at` | timestamptz | no | |
+| `deleted_at` | timestamptz | yes | |
+| `created_by` | text | yes | Null for the platform organization and for a self-service sign-up |
+| `updated_by` | text | yes | |
+| `deleted_by` | text | yes | |
+
+`unique(slug)`
+
+```json
+{
+  "organizationId": "01930f4a-3d10-7f42-a81b-6c2e9d5f4a00",
+  "kind": "CUSTOMER",
+  "name": "Acme Viagens",
+  "slug": "acme-viagens",
+  "workspaceMode": "MULTI",
+  "status": "ACTIVE",
+  "createdAt": "2026-08-12T10:00:00.000Z",
+  "updatedAt": "2026-09-01T14:20:02.000Z",
+  "deletedAt": null,
+  "createdBy": null,
+  "updatedBy": "01930f4e-6b21-7c3a-9f10-2c1a5b7d4e00",
+  "deletedBy": null
+}
+```
+
+### `workspace`
+
+A division inside an organization. Present in both workspace modes.
+
+| Column | Type | Null | Meaning |
+| --- | --- | --- | --- |
+| `workspace_id` | uuid | no | UUIDv7 |
+| `organization_id` | uuid → `organization` | no | Owner (`REL-5`) |
+| `name` | text | no | |
+| `slug` | text | no | Unique within the organization (`SCP-5`) |
+| `is_default` | boolean | no | Where a session lands when the person picked no workspace. Exactly one per organization |
+| `created_at` | timestamptz | no | |
+| `updated_at` | timestamptz | no | |
+| `deleted_at` | timestamptz | yes | |
+| `created_by` | text | yes | Null for the workspace created with the organization |
+| `updated_by` | text | yes | |
+| `deleted_by` | text | yes | |
+
+`unique(organization_id, slug)` · `unique(organization_id) where is_default`
+
+```json
+{
+  "workspaceId": "01930f4b-8e77-7a13-9c40-1f5b2d6e3a00",
+  "organizationId": "01930f4a-3d10-7f42-a81b-6c2e9d5f4a00",
+  "name": "Operações",
+  "slug": "operacoes",
+  "isDefault": true,
+  "createdAt": "2026-08-12T10:00:00.000Z",
+  "updatedAt": "2026-08-12T10:00:00.000Z",
+  "deletedAt": null,
+  "createdBy": null,
+  "updatedBy": null,
+  "deletedBy": null
+}
+```
+
+### `membership`
+
+A person, in an organization, holding a role. The only table that joins a person
+to a tenant, and it exists only for someone who has accepted (`IAM-13`).
+
+| Column | Type | Null | Meaning |
+| --- | --- | --- | --- |
+| `membership_id` | uuid | no | UUIDv7 |
+| `user_id` | uuid → `user` | no | |
+| `organization_id` | uuid → `organization` | **no** | `IAM-1` |
+| `workspace_id` | uuid → `workspace` | **yes** | Null means the whole organization |
+| `role_id` | uuid → `role` | no | `ON DELETE RESTRICT` (`REL-5`) |
+| `status` | text | no | `ACTIVE` · `SUSPENDED` |
+| `created_at` | timestamptz | no | The moment the invitation was accepted |
+| `updated_at` | timestamptz | no | |
+| `deleted_at` | timestamptz | yes | |
+| `created_by` | text | yes | The person who sent the invitation |
+| `updated_by` | text | yes | |
+| `deleted_by` | text | yes | |
+
+`unique(user_id, organization_id, workspace_id)` — one role per person per scope.
+
+```json
+{
+  "membershipId": "01930f4c-2b90-7c81-84d2-3a7e1c9f5b00",
+  "userId": "01930f4e-6b21-7c3a-9f10-2c1a5b7d4e00",
+  "organizationId": "01930f4a-3d10-7f42-a81b-6c2e9d5f4a00",
+  "workspaceId": null,
+  "roleId": "01930f49-1a55-7e20-b6f3-8d2c4e7a1b00",
+  "status": "ACTIVE",
+  "createdAt": "2026-09-01T14:25:40.000Z",
+  "updatedAt": "2026-09-01T14:25:40.000Z",
+  "deletedAt": null,
+  "createdBy": "01930f4d-5511-7e02-9b83-4c7a2f1e6d00",
+  "updatedBy": null,
+  "deletedBy": null
+}
+```
+
+`workspaceId` is null, so this role applies across the whole organization.
+
+### `invitation`
+
+An offer of access, addressed to an e-mail that may not have a `user` row yet
+(`IAM-13`).
+
+| Column | Type | Null | Meaning |
+| --- | --- | --- | --- |
+| `invitation_id` | uuid | no | UUIDv7 |
+| `organization_id` | uuid → `organization` | no | The organization being joined |
+| `workspace_id` | uuid → `workspace` | yes | Null means the membership will cover the whole organization |
+| `role_id` | uuid → `role` | no | The role the membership will carry. `ON DELETE RESTRICT` |
+| `user_id` | uuid → `user` | yes | Null until accepted; then the person who accepted (`IAM-14`) |
+| `email` | text | no | Where the offer was sent, lower-cased. Not a foreign key — the person may not exist yet |
+| `token_hash` | text | no | Hashed (`TAB-8`). The plaintext exists only in the link |
+| `expires_at` | timestamptz | no | |
+| `accepted_at` | timestamptz | yes | Null until accepted |
+| `revoked_at` | timestamptz | yes | Null unless withdrawn before acceptance |
+| `status` | text | no | `PENDING` · `ACCEPTED` · `REVOKED` · `EXPIRED` |
+| `created_at` | timestamptz | no | |
+| `updated_at` | timestamptz | no | |
+| `deleted_at` | timestamptz | yes | |
+| `created_by` | text | yes | The person who sent the offer |
+| `updated_by` | text | yes | The person who accepted or revoked it |
+| `deleted_by` | text | yes | |
+
+`unique(organization_id, email) where status = 'PENDING'` — one open offer per
+address per organization.
+
+```json
+{
+  "invitationId": "01930f4d-c3a1-7f88-9210-6b4e8d1c2f00",
+  "organizationId": "01930f4a-3d10-7f42-a81b-6c2e9d5f4a00",
+  "workspaceId": null,
+  "roleId": "01930f49-1a55-7e20-b6f3-8d2c4e7a1b00",
+  "userId": "01930f4e-6b21-7c3a-9f10-2c1a5b7d4e00",
+  "email": "ana@acme.com",
+  "tokenHash": "$argon2id$v=19$m=19456,t=2,p=1$aW52aXRlc2FsdA$...",
+  "expiresAt": "2026-09-08T14:20:02.000Z",
+  "acceptedAt": "2026-09-01T14:25:40.000Z",
+  "revokedAt": null,
+  "status": "ACCEPTED",
+  "createdAt": "2026-09-01T14:20:02.000Z",
+  "updatedAt": "2026-09-01T14:25:40.000Z",
+  "deletedAt": null,
+  "createdBy": "01930f4d-5511-7e02-9b83-4c7a2f1e6d00",
+  "updatedBy": "01930f4e-6b21-7c3a-9f10-2c1a5b7d4e00",
+  "deletedBy": null
+}
+```
+
+### `role`
+
+A named bundle of permissions. `kind` says who may hold it.
+
+| Column | Type | Null | Meaning |
+| --- | --- | --- | --- |
+| `role_id` | uuid | no | UUIDv7 |
+| `organization_id` | uuid → `organization` | **yes** | Set only when `kind = 'ORGANIZATION'` (`IAM-4`) |
+| `kind` | text | no | `ENVIRONMENT` · `ORGANIZATION` · `BACKOFFICE` |
+| `key` | text | no | `OWNER`, `ADMIN`, `MEMBER`, `OPERATOR`, or whatever a customer names theirs |
+| `name` | text | no | What a person sees |
+| `description` | text | yes | Shown in the role editor |
+| `created_at` | timestamptz | no | |
+| `updated_at` | timestamptz | no | |
+| `deleted_at` | timestamptz | yes | |
+| `created_by` | text | yes | Null for a seeded role |
+| `updated_by` | text | yes | |
+| `deleted_by` | text | yes | |
+
+`unique(organization_id, key)`
+
+```json
+{
+  "roleId": "01930f49-1a55-7e20-b6f3-8d2c4e7a1b00",
+  "organizationId": null,
+  "kind": "ENVIRONMENT",
+  "key": "OWNER",
+  "name": "Owner",
+  "description": "Full access to the organization, including billing and members.",
+  "createdAt": "2026-08-01T00:00:00.000Z",
+  "updatedAt": "2026-08-01T00:00:00.000Z",
+  "deletedAt": null,
+  "createdBy": null,
+  "updatedBy": null,
+  "deletedBy": null
+}
+```
+
+`kind` is `ENVIRONMENT`, so `organizationId` is null and every organization can
+hand this role out. `createdBy` is null: the row came from the seed.
+
+### `permission`
+
+The catalogue. Seeded from code, never edited by hand (`EVO-5`,
+`ARC-SEC-12`).
+
+| Column | Type | Null | Meaning |
+| --- | --- | --- | --- |
+| `permission_id` | uuid | no | UUIDv7 |
+| `key` | text | no | `<audience>:<resource>.<action>` — unique globally (`IAM-5`) |
+| `audience` | text | no | `AUTH` · `ADMIN` · `BACKOFFICE` |
+| `description` | text | no | Shown in the role editor. Grouping parses the key rather than storing the resource a second time |
+| `created_at` | timestamptz | no | |
+| `updated_at` | timestamptz | no | |
+
+`unique(key)`
+
+**No audit** and **no soft delete.** Nobody writes these rows; a permission that
+disappears from the source is a drift report, not a withdrawal (`EVO-5`).
+
+```json
+{
+  "permissionId": "01930f48-0c31-7b10-9a22-4b6d8e1f2a00",
+  "key": "admin:workspace.create",
+  "audience": "ADMIN",
+  "description": "Create a workspace inside the organization.",
+  "createdAt": "2026-08-01T00:00:00.000Z",
+  "updatedAt": "2026-08-01T00:00:00.000Z"
+}
+```
+
+### `role_permission`
+
+| Column | Type | Null | Meaning |
+| --- | --- | --- | --- |
+| `role_permission_id` | uuid | no | UUIDv7 |
+| `role_id` | uuid → `role` | no | |
+| `permission_id` | uuid → `permission` | no | |
+| `created_at` | timestamptz | no | |
+| `updated_at` | timestamptz | no | |
+| `created_by` | text | yes | Who granted it |
+| `updated_by` | text | yes | |
+
+`unique(role_id, permission_id)` (`REL-3`)
+
+**No soft delete.** Revoking removes the row, and `created_by` is the record of
+who granted it.
+
+```json
+{
+  "rolePermissionId": "01930f48-9f04-7d66-b013-7c2a5e8d4f00",
+  "roleId": "01930f49-1a55-7e20-b6f3-8d2c4e7a1b00",
+  "permissionId": "01930f48-0c31-7b10-9a22-4b6d8e1f2a00",
+  "createdAt": "2026-08-01T00:00:00.000Z",
+  "updatedAt": "2026-08-01T00:00:00.000Z",
+  "createdBy": null,
+  "updatedBy": null
+}
+```
+
+## Invariants
+
+| ID | Law (one line) | Class | Gate |
+| --- | --- | --- | --- |
+| IAM-1 | `membership.organization_id` is NOT NULL. There is no membership outside an organization; the nullable column is `workspace_id`, and its null means the whole organization. | constitutional | `manual` |
+| IAM-2 | The platform operator is a member of the organization whose `kind` is `PLATFORM`. Exactly one such organization exists, it is created by the seed, and it is never created through the product. | constitutional | `manual` |
+| IAM-3 | A permission in the `backoffice:` namespace attaches only to a role whose `kind` is `BACKOFFICE`, and a `BACKOFFICE` role is granted only inside the platform organization. Enforced at seed time and by a domain rule on role editing. | constitutional | `manual` |
+| IAM-4 | `role.kind` decides who may hold the role, and `organization_id` follows from it: `ORGANIZATION` requires one, `ENVIRONMENT` and `BACKOFFICE` forbid one. A customer edits only its own `ORGANIZATION` roles. | constitutional | `manual` |
+| IAM-5 | A permission key is `<audience>:<resource>.<action>`. The prefix is what keeps an admin permission from ever satisfying a backoffice check, and it is part of the key rather than a separate column used for filtering. | constitutional | `manual` |
+| IAM-6 | An OTP is consumed once: `consumed_at` is set in the same transaction that accepts it, and a consumed or expired code is indistinguishable from a wrong one in the response. Attempts are bounded. | constitutional | `manual` |
+| IAM-7 | Sign-in identifies the person, not the tenant. Choosing the organization is a second step that produces the session scope; a person with memberships in three organizations signs in once and picks. | constitutional | `manual` |
+| IAM-8 | `password_hash` is null for a person who has no password. It is never a placeholder, a random value, or the hash of an empty string. | constitutional | `manual` |
+| IAM-9 | `workspace_mode` is configuration on the organization, never a difference in schema and never a difference in the build (`EVO-3`). Both modes have a `workspace` row; `SINGLE` refuses the second, and the selector is present in every build and hidden at runtime — one bundle serves both kinds of customer. | constitutional | `manual` |
+| IAM-10 | `user.email` is unique globally — a deliberate exception to `SCP-5`, because sign-in happens before any organization is known. | constitutional | `manual` |
+| IAM-11 | E-mail and phone are verified independently. Verifying one never sets the other's `*_verified_at`, and a code delivered to a channel proves that channel and nothing else. | constitutional | `manual` |
+| IAM-12 | `otp.channel` and `otp.target` are frozen at issue. Changing the person's e-mail or phone afterwards does not retarget a code already sent, and a code is accepted only for the target it went to. | constitutional | `manual` |
+| IAM-13 | An invitation is its own table, addressed to an e-mail rather than to a user. A `membership` row exists only for someone who accepted, so the member list never shows access that nobody claimed. | constitutional | `manual` |
+| IAM-14 | Accepting an invitation writes the `membership` and stamps `accepted_at`, `user_id` and `ACCEPTED` on the invitation, in one transaction. The invitation is never deleted on acceptance: it is the record of who offered the access and when. | constitutional | `manual` |
+
+## Why the operator is a member of an organization
+
+The alternative — `membership.organization_id` nullable, with null meaning
+"platform" — was considered and rejected. It buys a row and costs the invariant
+that makes scoping checkable: with a nullable tenant, *every* membership query
+has to handle a case where there is no tenant, and the compiler cannot tell the
+two apart.
+
+Making the platform an organization keeps one shape. Sign-in is one flow. Roles
+and permissions are one machine. The operator's own internal teams are
+workspaces, with no new code. And `SCP-1` stays literally true: every row
+belongs to exactly one organization.
+
+What that costs is a real risk, and `IAM-3` is the guard: if a customer
+organization could hold a role with `backoffice:organization.list`, a customer
+would read every other customer. `role.kind` is what makes that guard cheap to
+check — the question is one column, not a walk through the role's permissions.
+
+## Why the role has a kind
+
+Three kinds of role exist in any product with a backoffice, and encoding them as
+"organization_id is null or not" collapses two of them into one:
+
+- **`ENVIRONMENT`** — shipped by the product, available to every organization.
+  `OWNER`, `ADMIN`, `MEMBER`. A customer hands them out and cannot edit them.
+- **`ORGANIZATION`** — written by one customer, for that customer.
+- **`BACKOFFICE`** — the platform's own. `OPERATOR`. This is the only kind that
+  may hold a `backoffice:` permission.
+
+Both `ENVIRONMENT` and `BACKOFFICE` have a null `organization_id`, so the null
+alone cannot tell them apart — and the difference is exactly the one that
+matters, because one is offered to every customer and the other must never be.
+`kind` states it, and `IAM-4` binds the null to it.
+
+## Why the invitation is its own table
+
+An invitation is addressed to an **e-mail**, not to a person. The address may
+belong to nobody yet, so modelling the offer as a `membership` in a pending
+state would require inventing a `user` row for someone who has not agreed to
+exist — a half-person that sign-in, the member list and erasure all have to know
+about.
+
+Separating them also separates two lifetimes that genuinely differ. An
+invitation expires, is revoked, is re-sent. A membership does none of those: it
+is active or suspended. Putting both in one row means a status enum that mixes
+"has not answered" with "no longer allowed", and every read has to know which
+half it is looking at.
+
+What the two share is the destination — organization, workspace, role — and that
+is why `invitation` carries the same three foreign keys the membership will get.
+Acceptance copies them, and `IAM-14` makes that one transaction.
+
+## Sign-in produces a scope
+
+```text
+1. prove identity        password · social · code        → the person
+2. list memberships      organizations they belong to    → one, or a choice
+3. resolve permissions   role → role_permission → keys   → for that scope
+4. issue the session     user_id, organization_id, workspace_id, permissions[]
+```
+
+Step 4 is what every other audience reads (`ARC-SEC-1`): the scope on the
+session is the only scope the product trusts, and no endpoint accepts an
+organization from the client.
+
+A person with one membership never sees step 2 — but the model does not know
+that, and the API is the same either way. That is why step 2 is a step and not a
+special case.
+
+## The three audiences
+
+| Audience | App | Scope | Permission namespace |
+| --- | --- | --- | --- |
+| `auth` | `apps/auth` | none — identity only | `auth:` |
+| `admin` | `apps/admin` | one organization, from the session | `admin:` |
+| `backoffice` | `apps/backoffice` | across organizations | `backoffice:` |
+
+`apps/admin` holds no authentication code: it mounts `<AuthProvider>` and reads
+the session. `apps/backoffice` is a separate application rather than a route
+inside admin, because a cross-tenant read must not share a bundle, a route tree
+or a session shape with a tenant-scoped one.
+
+## What the CLI generates
+
+- `domains/iam` — the ten tables above, their repositories and the use cases for
+  sign-up, sign-in (password, social, code), OTP issue and consume, organization
+  and workspace creation, invitation send, revoke and accept, and role
+  management.
+- The seed: the platform organization, the `ENVIRONMENT` roles `OWNER`, `ADMIN`
+  and `MEMBER`, the `BACKOFFICE` role `OPERATOR`, and the permission catalogue
+  derived from the code (`EVO-5`).
+- `apps/auth`, `apps/admin`, `apps/backoffice`, and the three audiences on the
+  API.
+- The workspace selector in the admin sidebar, always generated and rendered
+  only when the signed-in organization's `workspace_mode` is `MULTI` — and the
+  domain rule that refuses a second workspace when it is `SINGLE`.

package/README.md

@@ -0,0 +1,20 @@
+# @turystack/modeling
+
+The modelling skill: what becomes a table, how tables relate, how every row is
+scoped to a customer, and how a model changes once it has rows in it — plus the
+library of canonical models the CLI generates literally.
+
+| File | Owns |
+| --- | --- |
+| [`SKILL.md`](SKILL.md) | Entry point and routing |
+| [`00-overview.md`](00-overview.md) | Mental model, the five costly mistakes, how a model file is written |
+| [`01-entities.md`](01-entities.md) | `TAB` — tables, identity, keys, naming, types |
+| [`02-relationships.md`](02-relationships.md) | `REL` — cardinality, join tables, optional keys, ownership |
+| [`03-scoping.md`](03-scoping.md) | `SCP` — tenancy columns, scoped uniqueness, cross-tenant reads |
+| [`04-evolution.md`](04-evolution.md) | `EVO` — additive change, renames, policy vs shape, seeds |
+| [`10-model-iam.md`](10-model-iam.md) | `IAM` — identity and access: organization, workspace, user, membership, role, permission |
+
+Models are numbered from `10`. A new canonical model takes the next number and
+its own `<NAME>` namespace.
+
+Installed into `.claude/skills` and/or `.codex/skills` by the Turystack CLI.

package/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: turystack-modeling
+description: "How a Turystack product is modelled — what becomes a table, how tables relate, how every row is scoped to a customer, and how a model changes without breaking the repositories already running on it. Open it before writing a migration, adding an entity, changing a cardinality, or designing a new domain; and open the canonical model file when the domain is one Turystack already ships, because those models are law rather than suggestion. It owns entity identity and naming, cardinality and join tables, optional relationships and what a null means, ownership and cascade, tenancy columns and scoped uniqueness, additive evolution, and the model library — IAM first: organization, workspace, user, membership, role, permission. Code mechanics live in turystack-backend-pattern; boundaries, consistency and data lifetime live in turystack-architecture-pattern."
+---
+
+# turystack-modeling
+
+What exists, and how it relates. Read it before a migration or a new domain.
+
+## What lives here, and what does not
+
+A law belongs here when it is about **shape**: whether something is a table or a
+column, which side holds the foreign key, what a null means, which column
+carries the tenant, how uniqueness is scoped, and how that shape is allowed to
+change.
+
+A law about **boundaries, consistency, failure or lifetime** belongs to
+`turystack-architecture-pattern`. A rule about **how the code is written** —
+Drizzle syntax, repository methods, decorators — belongs to
+`turystack-backend-pattern`.
+
+```text
+turystack-architecture-pattern     boundaries, transactions, lifetime, security
+└── turystack-modeling             ← this: the shape of the data
+    └── turystack-backend-pattern  how that shape is written in this stack
+```
+
+**One law, one owner.** Data retention and erasure are `ARC-DAT-*`. Scope coming
+from the authenticated context is `ARC-SEC-1`. The permission catalogue is
+`ARC-SEC-12`. This skill cites those ids and never restates them; what it adds
+is the shape they imply.
+
+## How to use
+
+1. Read `00-overview.md`. It carries the mental model and the five mistakes that
+   cost the most, and it is short enough to keep in context.
+2. Open the law section your change touches. Read the whole section rather than
+   a remembered summary — these rules are dense.
+3. If the domain is one Turystack already models, open its model file (`1x-`)
+   and follow it exactly. Those models are not examples; the CLI generates them
+   literally, and a project that diverges from one has to say why in writing.
+4. Then read `turystack-backend-pattern` for how to write it here.
+
+## Routing
+
+| Your change | Read |
+| --- | --- |
+| A new table, or deciding whether something *is* a table | `01-entities.md` |
+| A foreign key, a join table, an optional relationship, a cascade | `02-relationships.md` |
+| Anything a customer owns, any uniqueness rule, any cross-customer read | `03-scoping.md` |
+| A migration on a model that already has rows, or flipping a cardinality | `04-evolution.md` |
+| Sign-in, organizations, workspaces, roles, permissions, OTP | `10-model-iam.md` |
+
+## How a section is written
+
+- **Concept** — what the section governs.
+- **Invariants** — the law, one row per rule, each with a stable id
+  `<NAMESPACE>-n`. **This table is what a review binds to.**
+- Prose explaining why the non-obvious rules exist, because a rule you
+  understand survives a refactor and a rule you memorised does not.
+- **Never do** — the same law as violations, so the shape is recognisable in a
+  diff.
+
+A model file (`1x-`) adds two things: the **tables**, column by column, and the
+**invariants that are true of this model specifically** — the ones a generic
+modelling rule cannot express, like "a role carrying a `backoffice:` permission
+attaches only to the platform organization".
+
+Ids are stable across versions. Every section opens with a **Rules defined
+here** line naming the ids it owns.

package/package.json

@@ -0,0 +1,21 @@
+{
+	"name": "@turystack/modeling",
+	"description": "Data modelling skill — what becomes a table, how tables relate, how every row is scoped to a customer, how a model evolves once it has rows, and the library of canonical models the CLI generates: IAM first. Installed into .claude/skills and/or .codex/skills via the turystack CLI.",
+	"private": false,
+	"version": "1.0.1",
+	"packageManager": "pnpm@10.12.3",
+	"sideEffects": false,
+	"publishConfig": {
+		"access": "public"
+	},
+	"engines": {
+		"node": ">=20"
+	},
+	"files": [
+		"*.md"
+	],
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/turystack/modeling-skill.git"
+	}
+}