stack/docs/requirements/hierarchy-schema.md

Hierarchy Schema Contract (D2)

Status: DRAFT — awaiting ratification (webui-audit S2, contract 1 of 9). Authority: PRD D2/D9/D13 (Part I §4) and the native-kanban SOT Amendment A1 (docs/requirements/native-kanban-sot.md §8, ratified 2026-08-25). This document turns the ratified hierarchy into a concrete schema contract: tables, cardinalities, constraints, and ownership/transfer semantics. It is the prerequisite for the D8 rank-1 tool (hierarchy command family) and for the RBAC grant model (contract 2).

Scope: the tenancy/authorization structure record class — companies, estates, platform-projects, workspaces, their parentage, and the grant attachment points. Out of scope: the RBAC grant vocabulary and evaluation semantics (contract 2), roll-up projection semantics (contract 8), kanban planning entities inside workspaces (SOT §5), migration of legacy flat data (SOT REQ-MIG-001).

1. Record class and placement

1. The four tables below form the tenancy/authorization structure record class defined by Amendment A1 §8.1.2. They carry parentage, naming, and grant data only — never task, plan, or any business/orchestration payload. No business/orchestration row may reference a hierarchy record as a dependency, claim target, or work subject.
2. Hierarchy records are NOT workspace-scoped rows: REQ-TEN-001's workspace_id obligation binds business/orchestration rows and does not apply to this class (A1 §8.1.2). The workspaces table itself is the anchor the obligation points at.
3. The legacy flat tables (teams, projects in packages/db/src/schema.ts — the Brain planning table, not the hierarchy level) are not part of this class and are not repurposed. The SOT forbids reusing the flat model for the hierarchy; their eventual migration or retirement is REQ-MIG-001 work, out of scope here.

2. Tables and cardinalities

Naming: the level above workspaces is platform_projects, per A1 §8.1.4 — the existing projects table already means workspace-internal planning entities, and the schema MUST NOT merge the two. (A rename of either remains an implementation-PR decision under A1; this contract pins only that they stay distinct tables.)

1. companies — id (uuid pk), name, slug (unique per deployment), created_at, updated_at. N per deployment (D2).
2. estates — id, name, slug, company_id NOT NULL → companies.id ON DELETE RESTRICT. Exactly one company per estate.
3. platform_projects — id, name, slug, estate_id NOT NULL → estates.id ON DELETE RESTRICT. Exactly one estate per platform-project.
4. workspaces — id, name, slug, platform_project_id NOT NULL → platform_projects.id ON DELETE RESTRICT. Exactly one platform-project per workspace. This table is the referent of every workspace_id column the SOT requires on canonical rows.
5. Chain resolution is by construction. Because every parent FK is NOT NULL and single-valued, each workspace resolves to exactly one platform-project → estate → company chain (A1 §8.3 acceptance 1). There are no parentage edge tables, no multi-parent forms, and no nullable "detached" states.
6. Slug scoping. estates.slug is unique within its company, platform_projects.slug within its estate, workspaces.slug within its platform-project (composite unique constraints). Display names are unconstrained.
7. No hierarchy table carries a metadata jsonb column or any free-form payload field. Parentage, naming, timestamps, and the audit linkage of §5 — nothing else (A1 §8.1.2).

3. Grant attachment points

The grant vocabulary (which roles exist, what each permits, how inheritance and revocation evaluate) is contract 2. This contract pins only the schema shape contract 2 attaches to:

1. hierarchy_grants — id, subject (exactly one of user_id → users.id, team_id → teams.id; CHECK-enforced exactly-one-of), target (exactly one of company_id, estate_id, platform_project_id; CHECK-enforced exactly-one-of), role (text; vocabulary owned by contract 2), granted_by → users.id, created_at.
2. Uniqueness: at most one grant row per (subject, target, role).
3. Deleting a hierarchy record deletes its grants (the one permitted cascade in this class — a grant on a deleted node is meaningless and fail-open if retained). Deleting a user or team follows the platform rule for principal deletion (identity contract §7; deletion is currently gated).
4. Workspace-level access is evaluated, not stored here: a grant at any of the three levels evaluates down the chain to workspace-scoped authorization (A1 §8.1.3). No workspace_id column exists on hierarchy_grants — workspace membership (REQ-ID-001) remains its own mechanism inside the SOT schema, and the chain adds where grants can be declared, never a bypass.

4. Ownership and transfer

"Assets are transferable subject to the structure" (PRD Part I §4):

1. A transfer is an audited UPDATE of exactly one parent FK on exactly one hierarchy row: workspace → new platform-project, platform-project → new estate, estate → new company. Nothing else changes: business and orchestration rows inside affected workspaces are untouched, keep their workspace_id, and never cross a workspace boundary (A1 §8.1.3 "chain maintenance").
2. Transfer authorization requires authority over BOTH the source and the destination parent (the vocabulary for "authority" is contract 2; the both-sides requirement is structural and binds here).
3. A transfer is a single-row, single-statement mutation; there are no multi-row transfer batches at the schema level. Bulk moves are N audited transfers.
4. Hierarchy records have no owner_id. Ownership in the hierarchy IS the grant structure (§3) — a "company owner" is a subject with the top role on that company, not a column. This avoids the dual-write failure mode of the legacy teams.owner_id/teams.manager_id columns, which encode authority outside any evaluable grant model.

5. Mutation path, audit, and deletion

1. All hierarchy mutations flow through the same sole-writable-SOT, fail-closed, audited Gateway command path as everything else (A1 §8.2.3, REQ-API-001). No direct-DB writers, no raw CRUD endpoints.
2. Every create, rename, transfer, grant change, and delete emits a semantic audit event carrying actor, verb, target record, and (for transfers) source and destination parents. Hierarchy audit events reference hierarchy records; they are not workspace-scoped rows and do not ride the workspace outbox (REQ-AUD-001 binds business rows; the implementing PR defines the hierarchy audit store under the same append-only rules).
3. Deletion is fail-closed bottom-up: a hierarchy record with children cannot be deleted (RESTRICT FKs, §2). Deleting a workspace is a SOT-side operation subject to the kanban SOT's own rules and is not granted any new semantics by this contract.
4. Roll-up reads (A1 §8.1.3) touch none of these tables' write paths and are specified by contract 8; this contract only guarantees the chain they aggregate over is unique and non-null.

6. Verification requirements

Binding on the implementing PRs (extends A1 §8.3):

1. Schema tests: chain uniqueness by construction (insert attempts with null/duplicate parents fail); composite slug uniqueness per parent; CHECK-enforced exactly-one-of on grant subject and target; grant uniqueness per (subject, target, role).
2. Transfer tests: parent-FK update moves the subtree resolution and modifies zero business/orchestration rows (row-count and content assertions on workspace contents before/after); transfer without authority on either side is refused.
3. Deletion tests: delete with children refused at the database level; delete of a leaf cascades its grants and nothing else.
4. Authorization tests (with contract 2): a grant at each level yields exactly the workspace permissions the chain implies; revocation up the chain propagates (A1 §8.3 acceptance 2).
5. Negative tests: no business/orchestration table accepts a hierarchy record id in any dependency/reference position; roll-up endpoints cannot mutate hierarchy state; readers see aggregates only over workspaces they are authorized on, with no cross-tenant existence oracles (A1 §8.3 acceptance 3).
6. Real-PostgreSQL coverage for the constraint-witness tests (unique/CHECK/ RESTRICT behavior), using the ci-postgres service in the test CI step; mocked specs cannot witness database constraints.

Ruling request

Ratify sections 1–6 as written, with one decision embedded: hierarchy records carry no owner column — ownership is expressed solely through grants (§4.4) — say "agreed" or name the ownership model you want.