[Orgs] Multi-tenant organizations with a project role ladder (admin/member/viewer)

From the PR description

Rewritten 2026-08-26. This description was replaced wholesale after @willchen96's review and its invitation addendum. The previous body described the model that review rejected - four project tiers (owner/manager/editor/viewer), hidden personal organizations, Teams, and nine migrations. None of that is on this branch any more, so its replication matrix no longer replicates. Everything below describes the branch at d6058c22.

Updated 2026-08-26 (evening). A post-review fix round landed on top of the revision, and the branch was rebased onto main at 1b58c7aa, which now carries #383 (model-selection policy). Two consequences run through this description: the migrations are renumbered 20260831_01..03 (see Migrations), and the org-visibility RPCs carry #383's model column. See Post-review fix round.

Followed by #268 (organization management UI) and #363 (chat permission parity). Backend-only: 39 files, +9768 / -416, 51 commits over main at 1b58c7aa. Zero changes under frontend/, e2e/ or word-addin/.

Summary

A firm is not one user. This PR adds multi-tenant organizations and one permission system the product can explain in a sentence: a project is personal or belongs to an organization; organization admins administer its projects, organization members collaborate on them, and anyone else can be invited to a single project as admin, member or viewer without joining the organization.

Concretely: two organization roles (admin, member), three project roles (admin, member, viewer), org-role inheritance onto org projects, per-recipient access grants that carry a role, membership that requires the recipient's consent, an organization that durably owns its projects even after the creator's account is deleted, and one capability matrix that every gated route declares against.

Live demo (recorded 2026-08-26, revised model)

Ten flows recorded with a real browser driving the running product on this stack's current tip, against an upgrade-path database - main's schema.sql with migrations 20260831_01..05 applied on top, i.e. the path an existing deployment actually takes rather than a fresh install. The three below are the ones this backend PR is responsible for.

The sole admin cannot strand the organization: their own row shows a role badge instead of a picker, the leave attempt comes back 409 with the refusal surfaced in the UI, and the role is still admin afterwards - the guard is the Postgres trigger, not the client.

A non-member finds the project in none of the tabs - Mine, Shared with me, All - and a direct URL is refused without leaking the project's name or contents.

An organization member with no explicit grant reaches the org project through inheritance alone, and the member tier is a real write tier: the upload is accepted and the folder is created.

The remaining seven flows from the same round:

• flow-01 - org creation and invitations
• flow-02 - invitation accepted, roster updated
• flow-04 - per-recipient project sharing roles
• flow-06 - viewer is read-only
• flow-08 - chat list/detail parity
• flow-09 - admin deletes a chat they did not author
• flow-10 - tabular review gating

Source mp4s and the labeled per-checkpoint stills are on the media branch: assets/orgs-live-2026-08-26.

What the review asked for, and what this branch does

The model

backend/src/lib/permissions.ts - one rank table, exhaustively unit-tested, fails closed on a null or unknown role (so the retired names owner/manager/editor are inert rather than ranking as something).

Roles rank viewer(0) < member(1) < admin(2). A capability names its minimum rank.

There is deliberately no tier between member and admin. The earlier draft split collaboration into editor (content) and manager (structure), borrowed from Drive's writer/fileOrganizer pair where it protects a shared drive's taxonomy. A collaborator who may delete every document in a folder one at a time is not meaningfully restrained by being unable to rename the folder; the split only produced a refusal popup on the operation people reach for when tidying up after themselves. The two capability names survive at the call sites even though they now share a rank, because they say different things about why a route is gated and a future tier can move one without hunting for which role === "member" checks meant which.

A caller's role for a project is the strongest of: the creator branch (admin), a direct grant's role, and the org-role inheritance (admin→admin, member→member). strongerRole is unchanged; only the rank table underneath it moved. The same merge exists in SQL as project_access_role() / review_access_role(), so list RPCs and detail routes cannot disagree about who sees what.

What changed

lib/permissions.ts - three roles, five capabilities, as above. Its unit test is now an explicit role × capability table, so a policy change must change a written-out verdict.

lib/access.ts + the new lib/projectAccess.ts - project_access_grants replaces the roleless array as the authorization input. Grants are keyed by normalized email (so a project can be shared with someone who has no account yet, and - the case the review called out - with someone who is not a member of the project's organization at all) and are additive, merged through strongerRole. resolveContentOrgId no longer needs to know who is asking: it inherits a project's org or returns null. isOwner → isCreator, and user_id is string | null throughout with comparisons guarded so a detached row never matches a caller by accident.

projects.shared_with survives as a derived mirror, rewritten from the grant table after every mutation (syncSharedWithMirror). No authorization decision consults it. replaceGrantsFromEmails handles the legacy roleless array by treating it as the set of direct grantees: emails already granted keep their role, only newcomers default to member - a client that cannot express roles must not be able to silently demote an admin collaborator by re-sending a list it did not change.

lib/orgs.ts + routes/orgs.ts + routes/user.ts - two org roles, peer admins, and the full invitation lifecycle:

POST   /orgs/:orgId/invitations               create (admin)
GET    /orgs/:orgId/invitations               roster (admin)
DELETE /orgs/:orgId/invitations/:id           cancel (admin)
POST   /orgs/:orgId/invitations/:id/resend    refresh expiry (admin)
GET    /user/invitations                      mine (recipient)
POST   /user/invitations/:id/accept           join
POST   /user/invitations/:id/decline          refuse

Three details worth naming. Invitations are addressed to a normalized email, not a user id, which is what makes claim-after-signup work. Expiry is evaluated lazily on read - a pending row past expires_at reports as expired and cannot be accepted, and the stored status stays pending until somebody acts on it; a sweeper job would have raced the accept path for no benefit. And an invitation addressed to somebody else answers 404, not 403, because a 403 would confirm that a given id exists for some other address. Expired invitations are re-openable in place (a re-invite refreshes the row and returns 201) rather than accumulating dead rows, and 410 Gone distinguishes "this existed and is past" from 404's "never heard of it". Every transition is audited (org.invite.created/cancelled/resent/accepted/declined).

routes/projects.ts - sharing becomes per-recipient:

GET    /projects/:projectId/access          list grants (anyone who can see the project)
POST   /projects/:projectId/access          grant / re-role one email (admin)
DELETE /projects/:projectId/access/:email   revoke one email (admin)

POST is an upsert on purpose: re-sharing with a different role is how a person changes someone's access, and making that a 409 would force the client to guess which verb to send. Reading the list is open to anyone who can see the project, because "who else is on this" is not privileged.

GET /projects/:projectId now returns access_role, org_role, owner_email, owner_display_name and admin_contacts ([{user_id, email, display_name, source: "creator"|"grant"|"organization"}], creator first, then admin grants, then the org's admins). The review found the symptom in the UI: the refusal popup renders an "ask ..." line guarded on an owner email, and the endpoint had never returned one, so the line could not appear under any circumstances. A refusal that cannot say who to ask is a dead end. /people gains each collaborator's role, and its owner may now be null - an organization project outlives the account that created it.

PATCH /projects/:projectId still accepts a roleless shared_with array for the un-revised web client, but no longer writes the column directly, and it now answers 403 rather than 404 when the caller can see the project but may not change its settings: those are different facts and the UI has to tell them apart to say anything useful.

A chat's creator can always continue their own chat. POST /projects/:projectId/chat gated purely on the project role, so a project viewer who had started a chat got a 404 on their next message. The client gates on canEditContent || chatOwnerId === user.id, so it rendered that message locally and then lost it - the server had persisted nothing and said nothing useful. POST /chat already had the creator branch; both ladders now agree, and the refusal is a 403 that says why.

The route sweep. Gates that said structure.manage now say docs.organize; ones that said members.manage say access.manage. Folder create/rename/move/delete all sit at member. Review columns, title, document set and clear-cells sit at content.edit; review sharing is access.manage. Project delete is admin-only and deletes by id rather than by owner - an org project may have no creator left to scope by. Error copy loses Owner/Manager/Editor throughout.

lib/userDataCleanup.ts - a firm's matters survive the account that opened them. partitionOwnedProjects splits the departing user's projects by org_id. Personal ones are destroyed exactly as before; organization ones are detached (user_id → NULL on the project and on the content inside it that the departing user created), and the detach runs before the by-user deletions so those deletions no longer match the rows being kept. On departure the membership goes; if they were the sole admin, the earliest remaining member is promoted first. Where there is no heir at all and the organization still owns projects, the membership row is deliberately not deleted here: neither of the trigger's escape hatches is open yet, so the delete would be refused. The auth.users cascade removes it a moment later, which is exactly the hatch the trigger reserves for account deletion. Pending invitations addressed to the departing account are cancelled, and their grants are deleted with each affected project's mirror rebuilt.

8. Post-review verification round (6104a8f8 ... 4b10a113)

(The commit ids cited in this section and the tables above are the pre-rebase ones from the original revision; the branch has since been rebased onto main at 1b58c7aa. The round itself is unchanged - it now runs 6104a8f8 ... 4b10a113.)

An adversarial pass over the revised model found six things, five of them user-visible. They are separate commits at the head of the branch so they can be read against the revision they audit.

• A creator-less project vanished from every list. on delete set null is what lets a firm's matter outlive the associate who opened it - and then the list RPCs dropped those rows on the floor. Every visibility predicate is a three-branch OR, and the grant and org branches carried p.user_id::text <> p_user_id to avoid re-matching the creator branch. In SQL's three-valued logic a comparison against NULL is not false, it is NULL: with user_id blanked, branch one yields NULL and branches two and three yield TRUE and NULL, which is also NULL, and where NULL keeps nothing. The project still existed and was still governed correctly when addressed by id - project_access_role was written the safe way - but no admin could find it in a list, a picker or a select-all. 22 predicates across both overloads of the projects, project-ids, project-summaries, filter-options and tabular-review functions are brought to the is null or <> spelling the workflows RPCs already used. The guard never earned its keep as logic anyway: A or (not A and B) is the same set as A or B; it only ever narrowed the result under NULL (2044a99b).
• A viewer could build folders by "resolving" a path. POST /projects/:projectId/folder-paths/resolve checked only that the caller could reach the project, while its four siblings - create, rename, delete, move - all require docs.organize. The name is what hid the hole: "resolve" sounds like a lookup, but resolve_project_folder_path inserts a project_subfolders row for every path segment that does not exist, which is the whole reason the upload flow calls it. A viewer could POST an arbitrary nested folder tree into someone else's project and have it persist. It now declares the same capability its siblings do, and the test asserts the refusal happens before the RPC is reached (e97e50d1).
• A retired role name was quietly downgraded instead of refused. Inviting someone as owner returned 201 and created a member invitation. The coercion failed safe, but it answered a request the product no longer supports by silently substituting a different one and reporting success - an integrator migrating off the old vocabulary would have shipped a fleet of accidental members with no signal. It is now a 400, matching its two neighbours (updateMember and POST /projects/:id/access already refuse). Omitting the role entirely still means member: the distinction is between not choosing and choosing something that does not exist (d7882cb3).
• Creator-scoped operations outlived their creator. Replacing or deleting a document version, folding a document in as a version, and moving a review between projects are scoped to authorship rather than to a tier - rules that predate the ladder and are not overturned here. But once account deletion blanks user_id, "only the creator may act" becomes "nobody may act", forever: a document left by a departed associate could never have a version replaced, an orphaned review could never be moved. The row was detached precisely so the firm would keep it, and then the firm could not touch it. creatorScopedAllowed keeps the authorship rule while there is an author to name and falls through to the container's admins once there is not - deliberately requiring container.delete (admin rank) rather than the weaker capability the operation might imply, because inheriting somebody else's authorship is an administrative act. The two refusals that still said "owner" now say "creator" (46220bc9).
• The firm keeps its content, not just its containers. The durability work retained "organization projects this user created" and destroyed everything else of theirs - which in a firm is close to backwards. Associates do not open matters; partners do. So a leaver's uploads, chats, folders and reviews almost all lived inside somebody else's org project, and every one was swept by the .eq("user_id", ...) deletions: the firm was left holding an empty matter and no record of what had been in it. Retention now keys on what the organization owns - the project, and therefore its contents, whoever put them there. orgProjectIdsHoldingUserContent finds every org project the leaver touched, including colleagues', and keeps and detaches those contents while the projects themselves stay with the colleague who still owns them (the projects detach gained its own .eq("user_id", ...) guard so a broader id set cannot blank a living colleague's authorship). Org-tagged rows outside any project are kept too - org_id is the whole claim - and org workflows are kept, because a firm's shared workflow is not the personal property of whoever first drafted it. Personal content is untouched: org_id IS NULL is still destroyed, files and all (f29118f4).
• Three more FKs still cascaded from auth.users and are converted to SET NULL alongside the original five, because keeping a parent while cascading its children away is its own kind of loss: workflows (org workflows carry org_id exactly like projects, and cascaded away with their author regardless), tabular_review_chats (the thread hangs off a review that now survives; losing it leaves a review nobody appears to have worked on), and workflow_reference_documents - which the audit turned up and was not on the original list: it hangs off a workflow whose workflow_id already cascades, so a surviving org workflow stripped of its references is still there and no longer works. The migration's conversion loop is table-driven, so this is three names in an array and stays re-runnable, and the comment above it now records which tables are deliberately excluded (user_api_keys, quick_actions, audit_events and friends, where the row is the account's own state and should die with it) (f29118f4).

One non-user-visible fix in the same round: the only test exercising org visibility against a real Postgres was still seeding the schema the review asked us to delete - an organization with personal: false (a column that no longer exists) and an org_members row with role: 'owner' (a value the check constraint refuses). Because it is gated behind SUPABASE_TEST_URL it skips in npm test, so npm run test:stack would have failed in beforeAll with a Postgres error before a single assertion (205d363d).

Post-review fix round (2026-08-26)

A second review round over the revision found twelve further defects, and the rebase onto main at 1b58c7aa (#383, model-selection policy) forced four reconciliation commits. Each fix is its own commit with its own regression test, so the fix can be read against the thing it repairs.

The fixes (2e2cd8a2 ... db7ad0ef):

The #383 reconciliation (ec99e7e6 ... d6058c22) - a rebase can merge text cleanly and still merge meaning wrongly, so the semantic half is kept in its own commits:

Why it changed

Three of the requested changes fix things that were actively wrong, not merely complicated:

1. owner was not a role. It was a row's user_id, permanently attached to whoever happened to create the project, making the creator structurally different from every other administrator forever. For firm content that is exactly backwards: the person who opened the matter is often not the person still running it a year later.
2. A roleless shared_with array could say who and nothing else. "Let outside counsel read this matter" and "let a colleague restructure it" were literally the same operation, and every collaborator landed on one hard-coded tier.
3. An admin's typo enrolled a stranger into a workspace of confidential matters, and the person it happened to was never asked. POST /orgs/:orgId/members took an email, resolved it to an account, and inserted a membership row.

And personal organizations cost more than they bought. user_id already anchored personal content, so the hidden org bought nothing - but getPersonalOrgId had to self-heal a signup trigger that deliberately swallows its own errors, resolveContentOrgId needed a user id purely to find that fallback, the org tables carried a row per account that existed only to be ignored, and "is this org real?" became a question every membership path had to remember to ask.

Base-case replication - the gap on main

Run the stack from docs/local-development.md (docker compose up --build; frontend :3000, backend :3001, Supabase gateway :54321) on main at 6a62d01a. Bearer tokens come from POST http://localhost:54321/auth/v1/token?grant_type=password using the well-known local anon key in docker-compose.yml; send them to :3001 as Authorization: Bearer <token>.

Accounts: A (project creator), B (a colleague), C (outside counsel - should be read-only).

1. There is no tenant. GET /orgs → 404 (the route does not exist). select * from organizations → relation does not exist. The only unit of access is a single user.
2. Sharing is per-row and roleless. The only way to give B access to A's project P is to put B's email in P.shared_with. Do it for a second project and you do it again; there is no group and no directory.
3. There is no way to express "read-only". Add C to P.shared_with. As C: upload a document, rename it, create a folder, rename a folder, move a folder, clear a review's extracted cells → 200 each. C was meant to read one matter; C can reshape it.
4. One boolean is the entire client contract. GET /projects/<P> returns is_owner and nothing else - no access_role, no owner_email, no admin_contacts. There is no vocabulary for "may edit content but not manage access", which is why the UI in #268 could only ever be right for one of two states.
5. A refusal cannot name anyone. Nothing in GET /projects/<P> or GET /projects/<P>/people gives the client an administrator's address, so the "only an admin can do that" popup has no one to point at.
6. A delete that deletes nothing reports success. As B (in shared_with, not the creator): DELETE /tabular-review/<R> where R is a review A created inside P → 204 No Content, and the review is still there on reload. The write was .eq("user_id", userId); a filter, not an authorization check.
7. Deleting an account destroys the matters. Delete A's account. Every project A created - and every document, chat and review inside - is cascaded away, including work B and C were collaborating on. There is no durable owner other than the person who happened to click New Project.
8. Directory search 500s for every caller. GET /projects?view=directory-search&q=test → 500. .contains("shared_with", [email]) serialises a JS array as the PgArray literal {a@b.com}, which Postgres rejects for a jsonb column (projects.ts:437).
9. The audit feed under-reports. As B, generate an event in A's shared project, then GET /audit. The event is absent - the identical containment misuse at audit.ts:34, except the error is swallowed rather than surfaced. The fix is no longer "correct the containment literal": accessibleProjectIds now reads project_access_grants by normalized email, like every other access path, so the audit feed stops authorizing off a display mirror at the same time as it stops under-reporting.
10. A review shared with a mixed-case address is a ghost. Put "B@Example.com" in a review's shared_with. As B (b@example.com): GET /tabular-review/<id> → 200, but the review never appears in GET /tabular-review. List and detail disagree.

PR replication - the same stack on this branch

Check out olp-pr/organizations-rbac (tip d6058c22), apply 20260831_01, _02, _03 in order (idempotent - verified applying twice over a main-shaped database at 1b58c7aa), restart the backend.

Accounts: A (creates the org and project P ⇒ project admin), D (org admin ⇒ project admin), M (plain org member ⇒ project member), V (holds a viewer grant on P, not in the org), G (holds a member grant on P, not in the org), N (outside@counsel.test - a valid address with no Mike account), X (outsider).

1. Organization lifecycle and invitations (18 rows)

Also worth asserting: POST /orgs/<org>/invitations/<already-accepted id>/resend → 409 That invitation has already been answered, and every one of the above writes an org.invite.* audit event.

2. Per-recipient sharing (10 rows)

3. Inheritance and strongest-wins (7 rows)

4. The write-gate matrix (12 rows)

5. Durability and account deletion (6 rows)

6. Pre-existing bugs closed on the way (3 rows)

7. Post-review verification round (7 rows)

Each of these fails on the branch as it stood at bfbb2659 - that is, against the revision itself, not against main.

Tradeoffs and design decisions

• projects.shared_with is kept as a derived legacy mirror, not deleted. Nothing reads it for authorization - it is rewritten from project_access_grants after every mutation purely so the un-revised web client keeps rendering. It goes away with #268; keeping it here is what makes this PR backend-only and independently mergeable. The cost is a column that can be stale if someone writes it directly, which is why every write path goes through syncSharedWithMirror - and a failed refresh is now logged loudly rather than swallowed, since a stale mirror is invisible from every other angle.
• There is no outbound email for invitations. Invitations are in-app only: an admin creates one, the recipient sees it at GET /user/invitations (and, in #268, at the top of Settings → Organizations). "Resend" therefore refreshes expires_at - it does not send anything, because there is no mailer in this repo to send with. That is a deliberate scope line, not an oversight: wiring a transactional email provider is its own PR (template, deliverability, an unsubscribe story, a secret). Named here because "resend" is a verb that promises something the button does not currently do.
• An organization with no members is kept if it still owns projects. The obvious cleanup - delete an org once its last member leaves - would SET NULL the org_id on its projects and strand exactly the content the durability work exists to protect. So a memberless-but-project-owning org survives as an orphan container, reachable only by re-granting membership out of band. The alternative (cascade-deleting the projects) is the bug; the alternative-alternative (refusing the last member's departure) traps people in an org. Flagged as the least-bad of three.
• user_id became nullable ON DELETE SET NULL on eight tables, not just projects - projects, project_subfolders, documents, chats, tabular_reviews, and (added by the verification round) workflows, tabular_review_chats, workflow_reference_documents. Detaching only the project row would not have helped: the auth.users cascade that follows account deletion would have taken every document, chat and review inside it anyway. The conversion is a table-driven DO block that looks up each FK by name and skips constraints already converted (confdeltype <> 'n'), so the migration re-runs cleanly and adding a table is one array entry. The exclusions are deliberate and now recorded in the migration: user_api_keys, quick_actions, audit_events and friends keep their CASCADE, because there the row is the account's own state and should die with it. The consequence is that user_id is string | null throughout the TypeScript, every comparison had to be guarded so a detached row cannot match a caller by accident, and every SQL predicate had to be made NULL-safe - which is a real class of bug, not a theoretical one (see rows 57 and 61).
• Detached content is inherited by the container's admins, not frozen. Once user_id is NULL, an operation scoped to authorship has no author, so creatorScopedAllowed falls through to container.delete - admin rank, deliberately stronger than the capability the operation would otherwise imply, because taking over somebody else's authorship is an administrative act rather than a content one. The alternative was leaving orphaned versions and reviews permanently untouchable, which defeats the point of keeping them. The cost is that "only the creator" is now "only the creator, or an admin once the creator is gone" - a rule with a second clause, which is worth stating in the UI when #268 surfaces it.
• An expired invitation answers 410, not 404 or 403. 404 would make an expired invitation indistinguishable from one that never existed, so the recipient could not tell "ask for a new one" from "you have the wrong link". 403 would be wrong twice over - nothing about the caller is at fault. 410 Gone is the one status that says "this existed and is past", and #268 maps it to "That invitation has expired. Ask an admin to send a new one."
• The last-admin guard is enforced in the database, not only in the API. org_members_protect_last_admin() is a security definer trigger with set search_path = public, firing before delete or update of role, taking select ... for update on the organizations row so two concurrent admin departures serialise, and raising SQLSTATE 23514. The service's own read-then-act check stays because it produces a better message on the common path; the trigger is what makes the invariant true under concurrency, and the service maps 23514 to the same last_admin verdict so both paths answer identically. Two escape hatches are deliberate: the org row already gone in-transaction (org-delete cascade), and the member's auth.users row already gone (account-delete cascade).
• POST /projects/:projectId/access does no account-existence check; PATCH /projects/:projectId's shared_with still does. The grant endpoint is the outside-counsel path - granting to an address before it has an account is the point, and refusing it would defeat the review's request. The legacy PATCH path keeps its does not belong to a Mike user 400 because the un-revised client shows no roles and no pending state, so a silent grant to a typo'd address would be invisible there. The asymmetry is intentional and disappears with #268.
• Enforcement lives in application code; RLS is defence in depth. The API runs as service_role for every request, so splitting enforcement across two layers means two places to get it wrong and no single test surface. The four new tables ship RLS-enabled with no policies and anon/authenticated revoked, so any future direct-client path starts from deny rather than allow.
• The access predicate is duplicated in SQL, but only twice. lib/access.ts decides detail access; the list RPCs decide list visibility, and they must agree branch for branch or a user sees rows they cannot open. In the previous revision ten RPCs each restated the predicate by hand. They now all call project_access_role() / review_access_role(), which is both the single definition and what makes returning access_role on every list row cheap enough to do at all.
• Refusals are 403 where the caller can already see the container and 404 where they cannot. PATCH /projects/:id now answers 403 rather than the old 404 (a real fix - the previous revision's live round recorded that asymmetry as a defect). Folder routes still answer 404 on refusal; they never adopted the split, and doing it in this PR would have widened an already large route sweep. Named because you need it to write assertions.
• workflows.ts keeps its own {allowEdit, isOwner} shape and never calls can(). Workflows have a third access scheme, including system workflows with a null user_id; folding them into the ladder is a separate change, named rather than hidden. What this PR does add is a coherent org arm on both sides: POST /workflows takes an optional org_id, validated exactly as POST /projects validates its own, and an org member may edit an org workflow (both org roles sit at member+ where editing content lives). Anything less was write-dead - no API call could create an org workflow and no one could edit one. Share and delete stay creator-scoped, so a detached org workflow can be edited by the firm but not deleted or shared; extending creatorScopedAllowed to cover them is a follow-up. ⚠️ Two calls here await maintainer sign-off: member-tier (not admin-tier) editing, and the creator-scoped share/delete gap.
• Version replace and delete stay creator-gated, not capability-gated. The matrix has no vocabulary for "the person who uploaded this file", and inventing one to model two routes would have put a lie in the shared table.
• The audit feed reads the grant table, and gets no org branch. accessibleProjectIds authorized off projects.shared_with - the derived mirror - which broke the model's one load-bearing rule, that no authorization decision consults it. It now reads project_access_grants by normalized email like every other access path. Visibility is unchanged (own ∪ direct-grant): whether an org admin should see a colleague's document downloads is its own design question and deserves its own PR.
• Teams are removed, not deleted. The tables, endpoints, cleanup and export code are preserved unmodified at 1e0f1478. They come back as their own PR with a team-scoped grant model, database-enforced membership, cascading cleanup and auditing - the conditions the review set - rather than riding along here as structure with no meaning.

Migrations

Three files, 20260831_01..03 - renumbered from 20260825_02..04 in e16a8693. While this branch was in review, main merged #383, whose migrations occupy 20260826_01 through 20260827_03, so every existing deployment is already recorded at 20260827_03. Deployments apply only files sorting after their recorded version, so shipping as 20260825_02..04 would have had every upgraded database judge them already-applied and silently skip them: fresh installs (schema.sql) would have organizations and every upgraded database would not - the exact split-brain the numbering convention exists to prevent. A rebase keeps a branch's diff clean; it does not keep this invariant, because sort position is decided at merge time against whatever main has shipped meanwhile. 20260828 is the first free date after #383's future-dated 20260827 set, and every in-tree reference (tests read migrations by path) moved with the files.

handle_new_user reverts to main's version: with personal orgs gone the signup trigger has no org work to do, so the migration simply stops touching it, and schema.sql's copy reverts to match - a fresh install must not create what an upgrade does not.

backend/schema.sql is updated in the same change. _02 is DML and correctly has no schema.sql counterpart.

Testing performed

Automated, on tip d6058c22 (rebased onto main 1b58c7aa):

• cd backend && npx tsc --noEmit → clean.
• npx vitest run → 1009 passed | 28 skipped, exit 0.
• The unhandled ERR_STREAM_WRITE_AFTER_END previously noted here as harmless is fixed on this branch (ec99e7e6). It was never harmless: an unhandled 'error' on a response stream can take the whole process down, so one disconnected client becomes an outage for every connected one. routeStreaming.ts's write() now refuses once the response is over - our own finish() ran, or res.writableEnded - and finish() is idempotent, because Node raises that error asynchronously on the stream's 'error' event where no try/catch around res.write() can observe it.

New test files - 112 declared cases - plus +70 added to existing suites, +26 of them from the post-review fix round (see below). Every fix commit carries its own regression test.

Database, verified independently for this description - scratch Postgres, main-shaped baseline (schema.sql at 1b58c7aa, i.e. with #383 in place), then 20260831_01, _02, _03:

• All three apply cleanly, and again on a second pass - 0 errors on both passes.
• Post-apply catalog inspection confirms: tables organizations, org_members, org_invitations, project_access_grants and no teams/team_members; functions project_access_role, review_access_role, org_members_protect_last_admin; trigger org_members_last_admin_guard on org_members; and exactly eight user_id foreign keys at confdeltype = 'n' (SET NULL) - projects, project_subfolders, documents, chats, tabular_reviews, workflows, tabular_review_chats, workflow_reference_documents - with the columns nullable to match.
• Schema-drift check replicated the way CI runs it - the upgraded database above versus a fresh install of this branch's schema.sql, each reduced by backend/scripts/schema-fingerprint.sql → 4164 fingerprint lines, identical, NO DRIFT. Fresh installs and upgraded deployments converge exactly.

Live. A ten-flow browser round against the revised model was recorded on 2026-08-26 - see Live demo above; the replication tables in this description are the script it follows. The three earlier rounds - 2026-08-21, 2026-08-18, 2026-08-16 - are retained for history, but every one of them exercised owner/manager/editor, personal orgs and admin-added members. Their matrices no longer replicate and should not be read as evidence for this branch.

Provenance

The original schema, org module and tenant stamping began as a port of amal66/mike@b3166dd. Almost none of that survives this revision: the role ladder, project_access_grants, lib/projectAccess.ts, the invitation lifecycle, the SQL role helpers and the account-deletion detach are all new code written for this PR in response to the review. The fork will adopt the same model.

Credits & prior art

• @Chris-o-O (Chris-o-O/mike-explor) - independently parallels this work: their fork built organizations and team management on top of Mike. Different implementation, same conviction that a firm is not one user.
• The three-role ladder follows matter-workspace conventions from legal practice tools - private by default, container-rooted inheritance, administrative oversight that does not require owning the row - rather than Drive's writer/fileOrganizer split, which the review correctly identified as a distinction legal teams do not need.

🤖 Generated with Claude Code

Second fix round - 2026-08-26 (architecture re-review)

A second code-level review pass at d6058c22 surfaced four blockers, fixed here with one regression test each. New tip: 17ed10b7 (this branch's diff only; the stack above was rebased on top).

Tradeoff flagged: deleteStorageFiles is deliberately best-effort (.catch) - once rows are gone, aborting on a failed file removal could only strand the caller in a worse state; the claim-filtered orphan sweep in the same request is the backstop.

One further test-only commit, 17ed10b7, pins the clock in history/page.test.tsx (Date-only fake timers, mid-month date): the suite derived calendar expectations from "today" and went red on CI just past midnight UTC on 2026-08-27 - a latent flake on main, untouched by this branch, surfaced by re-running CI. Verified green under TZ=UTC, UTC+14 and local time.

Testing performed (this round): npx tsc --noEmit clean; npx vitest run → 1018 passed | 28 skipped, exit 0 (at this branch's tip). Each fix verified red-before/green-after by stashing the code change and re-running its test. Schema untouched by this round; the fresh-vs-upgraded drift check was replicated locally at the stack tip (baseline 9a1277ba + all migrations added since vs current schema.sql): 3,812 fingerprint lines, identical, no drift.

Third fix round - 2026-08-26 (high-tier findings)

Two commits close the review's remaining high-severity findings at this layer. New tip: b9c2cdf3.

b9c2cdf3 - sharing plumbing fails closed, rosters answer their tier. Four fixes in one coherent sweep:

• listProjectGrants is result-shaped: a failed read no longer presents as "no grants", which used to (a) wipe the shared_with mirror to [] and (b) make legacy-path revocation a success-shaped no-op - the caller was told access was removed while nobody lost it. Base case at 17ed10b7: fail the grants read (kill the DB mid-request) during PATCH /projects/:id {"shared_with":[...]} → 200, no grants revoked. Now: 500, retryable, grants intact. removeGrantsForEmail throws on failure so account deletion can't report success over live grants.
• resolveContentOrgId is result-shaped: a failed project lookup no longer returns null, which IS the encoding of personal content - a blip while uploading into an org project filed the firm's document as the uploader's private property (destroyed with their account later). All six call sites refuse the request instead of guessing the tenant.
• GET /projects/:id/access is admin-only and GET /people's roster is member+; a viewer keeps the creator + admin_contacts (what refusal popups need) and nothing more. Base case: as a viewer-tier grantee, GET /access → full grant list with emails, roles, grantors. Now: 403; /people members list empty at viewer.
• The three grant endpoints route DB failures through sendInternalError instead of echoing raw driver messages.

Regression tests: fail-closed suite in projectAccess.test.ts (mirror untouched on failed read, replace refuses, deletion throws), tenant-refusal cases in access.test.ts and tabular.routes.test.ts, roster-tiering cases in orgs.routes.test.ts. Backend: 1,026 passed, tsc clean at this layer.

Tradeoff flagged: POST /projects's legacy share path logs-and-continues on a failed grant write (project 201s unshared) rather than 500ing after the insert - a 500 would invite a duplicate-creating retry, and the revised modal grants per-recipient with its own retry.

Migration renumber - 2026-08-27 (decided deploy order)

The maintainer decided the landing order: the durable-queues PRs (#294, and #295 stacked on it) merge and deploy first; this stack lands after. Deployments apply only migration files sorting past their recorded watermark, so this stack's 20260828_01..03 - older than #294's 20260829_01 - would have been silently skipped on any deployment that took #294 first. Commit 746d9df4 renumbers them to 20260831_01..03 (past #294's slot and past the chat-agents branch's reserved 20260830_01), moving every internal cross-reference, the static SQL-predicate test's literal paths, and the stale date headers in the same commit. New tip: 746d9df4.

Verified on a real local Postgres: the decided production sequence - main's schema → 20260829_01_db_jobs.sql (from #294 at e18c30ec) → 20260831_01..05 applied twice - runs clean end to end, all four stack suites pass 22/22 against that combined database, and the fresh-vs-upgraded drift fingerprints are identical (3,812 lines). Earlier mentions of 20260828_* in this body refer to the same files under their previous names.

Rebase onto September main - 2026-09-01

The stack now sits on main at fdd4ed19, which brought three reworks this branch had to meet semantically, not just textually. New tip: 66ff80d5 (65 commits). Each re-port is its own commit:

Three verification loose ends from the 2026-09-01 independent review round are also closed here:

Testing performed (this round): backend npx tsc --noEmit clean; npx vitest run → 1,361 passed | 40 skipped at the stack tip (this branch's layer green standalone); fresh-worktree replay of the full battery; each new fix verified red-before/green-after by stashing its code change. The commit history is marker-clean and each commit's diff reads against the thing it changes. One commit dropped out of the branch as already-merged: the history/page.test.tsx clock pin landed on main via #390.

Post-push amendments (same day): CI's drift gate caught a syntax error the RPC re-sync introduced in _03 (a comment line swallowed the create or replace for get_project_ids_overview); fixed in place by fixup into d80cfd80, and the full drift check was replicated locally on a scratch Postgres both at this branch's tip and at the stack tip - baseline schema (9a1277ba) + all 51 migrations added since, org files applied twice - 0 fingerprint lines of drift (4,889 / 4,926 lines respectively). And 66ff80d5 absorbs today's browserslist advisories (word-addin lockfile) so the new dependency-audit gate stays green; raised standalone as #422 for main, whichever lands second dedupes.