resolutionflow/docs/superpowers/specs/2026-04-09-tenant-data-isolation-design.md

Tenant Data Isolation — Design Spec

Date: 2026-04-09 Status: Approved — ready for implementation planning Approach: PostgreSQL RLS as safety net; application-layer filtering as primary enforcement

---

Overview

ResolutionFlow is a multi-tenant SaaS. The tenant boundary is account_id (UUID foreign key to accounts.id). Two accounts must be completely isolated at every layer: one client must never be able to see, access, query, or receive data belonging to another client — even if there is a bug in application code.

This spec establishes the complete foundation that must be in place before further feature development proceeds.

Design Principle

Application code is the primary enforcement mechanism. PostgreSQL Row-Level Security (RLS) is the safety net.

Both layers must always be present. Developers must never rely on RLS to do filtering that application code should be doing. A missing tenant_filter() in application code is a code review failure even if RLS would have caught it.

---

Current State

• Tenant boundary: account_id (not team_id — that column is legacy)
• Isolation today: 100% application-layer, manual per-endpoint .where(account_id == ...)
• No RLS, no DB session variables, no middleware tenant injection
• Nullable account_id on ~8 core models (User, Tree, TreeCategory, etc.)
• ~20 tables with no direct account_id (scoped only through join chains)
• 4 models with team_id only, no account_id: TargetList, ScriptBuilderSession, ScriptTemplate, ScriptGeneration
• Known existing gaps: see Section 4

---

Section 1: Schema Changes

1a. Denormalize account_id onto all tenant-relevant tables

Add account_id UUID NOT NULL (with FK to accounts.id and index) to each of the following tables that currently lack it:

Table	Backfill path
sessions	sessions.user_id → users.account_id
attachments	attachments.session_id → sessions.user_id → users.account_id
session_supporting_data	session_supporting_data.session_id → sessions.user_id → users.account_id
audit_logs	audit_logs.user_id → users.account_id
maintenance_schedules	maintenance_schedules.tree_id → trees.account_id
user_folders	user_folders.user_id → users.account_id
user_pinned_trees	user_pinned_trees.user_id → users.account_id
session_branches	session_branches.ai_session_id → ai_sessions.account_id (verify column name — may be session_id)
session_handoffs	session_handoffs.ai_session_id → ai_sessions.account_id (verify column name — may be session_id)
session_resolution_outputs	session_resolution_outputs.session_id → sessions.user_id → users.account_id
fork_points	fork_points.session_id → ai_sessions.account_id
ai_session_steps	ai_session_steps.session_id → ai_sessions.account_id
ai_suggestions	ai_suggestions.tree_id → trees.account_id
step_ratings	step_ratings.user_id → users.account_id (backfill from rater, not the step)
step_usage_logs	step_usage_logs.user_id → users.account_id (backfill from user, not the step)
psa_post_logs	psa_post_logs.psa_connection_id → psa_connections.account_id (psa_connections already has account_id NOT NULL)
psa_member_mappings	psa_member_mappings.psa_connection_id → psa_connections.account_id
notification_logs	notification_logs.notification_config_id → notification_configs.account_id

Deferred: tree_shares — backfill strategy and RLS policy depend on whether sharing is intra-tenant only or cross-tenant. Must be resolved before RLS is enabled on this table. See Section 7 (Open Questions).

1b. Make existing nullable account_id columns NOT NULL

These tables have account_id already but it is nullable:

• users
• trees
• tree_categories
• tree_tags
• step_categories
• step_library
• tree_embeddings
• feedback

Action: Backfill any NULL rows (assign to correct account or delete if orphaned test/seed data), then ALTER COLUMN account_id SET NOT NULL.

1c. Global / template content

Move global content out of tenant tables into dedicated tables with no RLS:

• template_trees — default and publicly visible trees (currently is_default=True or visibility='public' in trees). All tenants can read; no RLS.
• platform_steps — public steps from step library (currently visibility='public' in step_library). All tenants can read; no RLS.
• Tables already global (no change needed): script_categories, platform_settings, plan_limits, feature_flags, plan_feature_defaults.

1d. Migration sequence (per table)

Every table that gains account_id follows this exact sequence. Each step must succeed before the next begins:

1. ADD COLUMN account_id UUID (nullable)
2. Backfill via UPDATE ... JOIN ...
3. SELECT COUNT(*) WHERE account_id IS NULL — must be zero before proceeding
4. ALTER COLUMN account_id SET NOT NULL
5. CREATE INDEX ON <table>(account_id)
6. Enable RLS (in Phase 3, not here)

Any migration that cannot reach step 3 (zero NULLs) must roll back completely. No partial state.

---

Section 2: PostgreSQL Roles & RLS Infrastructure

2a. Database roles

Two PostgreSQL roles:

resolutionflow_app

• Used by all application requests
• Subject to all RLS policies
• Standard table privileges: SELECT, INSERT, UPDATE, DELETE on all tenant tables

resolutionflow_admin

• Used by: Alembic migrations, seed scripts, super admin API endpoints, scheduled background jobs requiring cross-tenant access
• Has BYPASSRLS attribute — not subject to RLS policies
• Same table privileges as resolutionflow_app
• Connection string exposed as DATABASE_ADMIN_URL env var

The current postgres superuser is replaced in the application by these two roles. The connection string in DATABASE_URL transitions to resolutionflow_app. Alembic uses DATABASE_URL_SYNC pointing to resolutionflow_admin.

2b. Per-request tenant context injection

Every request that passes through get_db() must execute, inside a transaction boundary:

SET LOCAL app.current_account_id = '<account_uuid>';

SET LOCAL is transaction-scoped — it resets automatically when the transaction ends. No cleanup needed. This is implemented in a modified get_db() dependency that receives current_user and executes the SET before yielding the session.

Fail-closed behavior: If app.current_account_id is not set (e.g., a bug where SET LOCAL was skipped), current_setting('app.current_account_id', false)::uuid returns NULL. NULL = NULL is false in SQL — the RLS policy matches zero rows. This is the correct fail-closed behavior.

Public endpoints (no authenticated user) do not call SET LOCAL. RLS matches zero rows for all tenant tables. This is correct.

2c. RLS policy pattern

Every tenant table (from Section 1 + all existing tables with account_id) gets:

ALTER TABLE <table> ENABLE ROW LEVEL SECURITY;
ALTER TABLE <table> FORCE ROW LEVEL SECURITY;

-- SELECT
CREATE POLICY tenant_select ON <table> FOR SELECT
  USING (account_id = current_setting('app.current_account_id', false)::uuid);

-- INSERT
CREATE POLICY tenant_insert ON <table> FOR INSERT
  WITH CHECK (account_id = current_setting('app.current_account_id', false)::uuid);

-- UPDATE
CREATE POLICY tenant_update ON <table> FOR UPDATE
  USING (account_id = current_setting('app.current_account_id', false)::uuid)
  WITH CHECK (account_id = current_setting('app.current_account_id', false)::uuid);

-- DELETE
CREATE POLICY tenant_delete ON <table> FOR DELETE
  USING (account_id = current_setting('app.current_account_id', false)::uuid);

FORCE ROW LEVEL SECURITY ensures the table owner is also subject to policies. The resolutionflow_admin role bypasses via its BYPASSRLS attribute, not via ownership.

audit_logs exception: SELECT policy only. No WITH CHECK on INSERT (app inserts audit logs freely). No UPDATE or DELETE policies ever. These constraints are permanent and must be documented in the migration comment.

Global tables (platform_settings, plan_limits, feature_flags, plan_feature_defaults, template_trees, platform_steps): No RLS.

2d. Connection pool reuse safety

The SET LOCAL approach is transaction-scoped. A connection pool reuse test (see Section 6) must verify that a connection returned to the pool after tenant A's request does not carry tenant A's account_id into tenant B's request. This is guaranteed by SET LOCAL (resets on transaction end) but must be explicitly verified.

---

Section 3: Application-Layer Enforcement Patterns

3a. tenant_filter() helper

Add to backend/app/core/filters.py:

def tenant_filter(model, account_id: uuid.UUID):
    """
    Primary app-layer tenant filter.
    MUST be used in every SELECT/UPDATE/DELETE on tenant tables.
    RLS is the safety net — this is the primary enforcement.
    """
    return model.account_id == account_id

All existing filter helpers (build_tree_access_filter, build_step_visibility_filter) must internally call tenant_filter() as their base constraint.

3b. Fetch-and-verify pattern

For ID-based lookups, filter by both id AND account_id in the query — not fetch-then-check:

# Correct
stmt = select(Tree).where(
    Tree.id == tree_id,
    tenant_filter(Tree, current_user.account_id)
)
tree = (await db.execute(stmt)).scalar_one_or_none()
if not tree:
    raise HTTPException(status_code=404)

# Prohibited — fetch first, then check
tree = await db.get(Tree, tree_id)
if tree.account_id != current_user.account_id:
    raise HTTPException(status_code=403)  # Reveals existence — also wrong

Endpoints must return 404, not 403, for cross-tenant ID lookups. Never confirm that a resource exists.

3c. get_tenant_context dependency

Add to backend/app/api/deps.py:

async def get_tenant_context(
    current_user: User = Depends(get_current_active_user)
) -> uuid.UUID:
    """
    Returns the current user's account_id.
    Raises 403 if the user has no account association.
    Inject this instead of accessing current_user.account_id directly.
    """
    if current_user.account_id is None:
        raise HTTPException(status_code=403, detail="User not associated with any account")
    return current_user.account_id

3d. Insert pattern

All inserts on tenant tables must explicitly set account_id. RLS WITH CHECK rejects inserts where account_id doesn't match the session variable, but application code must also set it:

new_record = Tree(
    account_id=tenant_account_id,  # Required — never omit
    ...
)

3e. Code review checklist rule

Every PR that touches a tenant table must be verified against:

1. Every SELECT/UPDATE/DELETE includes tenant_filter() or a wrapper that calls it
2. ID lookups filter by both id and account_id in the same query
3. Inserts explicitly set account_id
4. 404 (not 403) returned for cross-tenant ID lookups
5. A cross-tenant isolation test is included (Phase 2 onwards)

3f. CI grep check

A grep-based CI check is active from the end of Phase 0 on all PRs. It flags:

• Queries on known tenant tables that don't include tenant_filter or account_id as a filter term
• Initial implementation: warn (not block) to allow calibration; switch to block after 2 weeks of false-positive tuning

Pattern to be defined during Phase 0 implementation.

---

Section 4: Existing Gap Fixes

Immediate Hotfix (ships before Phase 0)

CRITICAL: Copilot tree access bypass

• Files: backend/app/api/endpoints/copilot.py, backend/app/services/copilot_service.py
• Issue: start_conversation() loads a tree by UUID without verifying the requesting user has access. An attacker who knows a tree UUID from another account can extract its full structure, node names, and descriptions via the AI system prompt.
• Fix: Add can_access_tree(current_user, tree) check in the endpoint after loading the tree. Also add tenant_filter(Tree, account_id) to the tree query in copilot_service.py. Raise 404 (not 403) if the tree is not found or not accessible.
• Ships as an independent hotfix PR, merged immediately.

Phase 0 Fixes

LOW: Analytics flow endpoint (backend/app/api/endpoints/analytics.py)

• GET /analytics/flows/{tree_id} returns analytics for any tree by UUID with no access check
• Fix: Add tenant_filter(Tree, current_user.account_id) to the tree fetch query. 404 if not found.

LOW: Category tree count (backend/app/api/endpoints/categories.py)

• Tree count per category includes trees from all accounts
• Fix: Add tenant_filter(Tree, current_user.account_id) to the count subquery

LOW: AI session scope inconsistency (backend/app/api/endpoints/ai_sessions.py)

• List endpoint is user-scoped (user_id == current_user.id); search endpoint uses OR(user_id, account_id) exposing other users' session summaries within the same account
• Sessions are user-scoped only. Cross-user access permitted only via explicit escalation or session sharing
• Fix: Restrict search endpoint to user_id == current_user.id. List and search must behave consistently.

Phase 0 UUID endpoint audit

• Systematically review every endpoint with a {resource_id} URL parameter
• For each: verify that the ID lookup either (a) filters by id AND account_id in the query, or (b) calls can_access_<resource>(current_user, resource) on the fetched object
• Document every instance found, classify by severity, fix all before Phase 0 closes

---

Section 5: Legacy team_id Migration

5a. TargetList — audit-gated

Before any migration work on TargetList:

1. Run a full codebase reference audit: grep for all references to TargetList, target_list, target-list
2. Query the production and staging databases for row count
3. Decision tree:
   • Zero code references AND zero rows → drop the table entirely
   • Zero rows but code references exist → deprecate code, then drop
   • Rows exist → migrate (see sequence below)
4. Migration only proceeds after audit result is documented and approved

If migration proceeds:

• Backfill path: team_id → teams → users WHERE is_team_admin → account_id
• If any row cannot be backfilled to a valid account_id → full rollback, no exceptions, no manual review queues

5b. Pre-migration: teams-to-accounts orphan check

Before any backfill using team_id → account_id chains, run:

SELECT COUNT(*) FROM teams t
LEFT JOIN users u ON u.team_id = t.id AND u.account_id IS NOT NULL
WHERE u.id IS NULL;

Count must be zero before any backfill proceeds. Report and resolve orphaned teams first.

5c. Approved migrations (no audit gate)

ScriptBuilderSession: Add account_id, backfill from user_id → users.account_id, set NOT NULL.

ScriptTemplate: Add account_id, backfill from created_by_id → users.account_id, set NOT NULL.

ScriptGeneration: Add account_id, backfill from user_id → users.account_id, set NOT NULL.

5d. team_id cleanup

Do NOT drop team_id columns during migration. Keep until all application code is updated to use account_id exclusively. Drop team_id columns in a later cleanup migration after verification.

---

Section 6: Testing Strategy

Phase 1: RLS validation tests

File: backend/tests/test_rls_isolation.py

This test suite validates RLS policies at the database layer, independent of any application code. It connects to the test database using the resolutionflow_app role.

Setup fixture:

• Creates two accounts (account_a, account_b) with seed rows in all tenant tables
• Creates an async DB connection using resolutionflow_app role
• Sets SET LOCAL app.current_account_id = '<account_a_uuid>' before each test

Test cases per table (~5 cases per table, ~32 tables ≈ ~160 total):

1. SELECT isolation — querying as account_a returns zero rows for account_b's data
2. INSERT enforcement — inserting with account_id = account_b_uuid raises a PostgreSQL exception (rejected by WITH CHECK)
3. INSERT cross-tenant FK — inserting with correct account_id but a FK value (e.g., tree_id) that belongs to account_b is also rejected
4. UPDATE enforcement — updating account_b's rows as account_a affects zero rows
5. DELETE enforcement — deleting account_b's rows as account_a affects zero rows

Fail-closed test:

# Unset app.current_account_id — must raise a database exception
# Acceptable: psycopg2.errors.InvalidTextRepresentation (NULL::uuid cast fails)
# NOT acceptable: query returning zero rows silently
with pytest.raises(asyncpg.PostgresError):
    await conn.execute("SELECT * FROM trees")

The exact exception type must be documented based on the behavior of current_setting('app.current_account_id', false)::uuid when unset. The test asserts on that specific exception.

audit_logs special cases:

• No INSERT WITH CHECK test — audit logs must be insertable freely
• No UPDATE or DELETE tests — those policies must not exist
• Verify via pg_policies that only a SELECT policy exists on audit_logs

tree_shares: Intentionally deferred. A TODO comment is included:

# TODO: tree_shares RLS tests deferred pending sharing model decision.
# Must be added before RLS is enabled on the tree_shares table.
# See: docs/superpowers/specs/2026-04-09-tenant-data-isolation-design.md Section 7

Tables covered in Phase 1: trees, ai_sessions, ai_chat_sessions, ai_conversations, sessions, step_library, tree_categories, tree_tags, step_categories, flow_proposals, attachments, audit_logs, psa_connections, copilot_conversations, file_uploads, kb_imports, subscriptions, account_invites, ai_usage, notifications, session_shares, script_builder_sessions, script_templates, script_generations, maintenance_schedules, user_folders, user_pinned_trees, session_supporting_data, session_branches, session_resolution_outputs, psa_post_logs, notification_logs

Connection pool reuse test:

async def test_set_local_does_not_leak_between_connections():
    """SET LOCAL must not leak account_id when a connection is returned to the pool."""
    conn = await pool.acquire()
    async with conn.transaction():
        await conn.execute("SET LOCAL app.current_account_id = $1", str(account_a_id))
        # transaction ends, SET LOCAL resets
    # Return conn to pool, re-acquire — verify account_id is not set
    conn2 = await pool.acquire()
    result = await conn2.fetchval("SELECT current_setting('app.current_account_id', true)")
    assert result is None or result == ""

Phase 2: Per-endpoint cross-tenant tests

As each endpoint is touched in any PR from Phase 1 onward, a cross-tenant isolation test is added in the same PR:

async def test_cannot_access_other_account_<resource>(
    client_account_a, account_b_resource
):
    """Account A cannot access Account B's resource by UUID."""
    response = await client_account_a.get(f"/<resource>/{account_b_resource.id}")
    assert response.status_code == 404  # Not 403 — never reveal existence

This is a hard requirement per the code review checklist.

---

Section 7: Phased Rollout Plan

Immediate Hotfix (before everything else)

• Fix CRITICAL: Copilot tree access bypass (see Section 4)
• Ships as independent PR, merged immediately, does not wait for Phase 0

---

Phase 0 — Foundation

Goal: Fix all existing gaps; establish patterns and tooling; gate future PRs.

1. Fix LOW: Analytics flow endpoint missing ownership check
2. Fix LOW: Category tree count scope
3. Fix LOW: AI session search/list inconsistency (restrict both to user_id)
4. Full UUID endpoint audit — every {resource_id} URL param checked. All gaps documented and fixed before Phase 0 closes.
5. Add get_tenant_context dependency to deps.py
6. Add tenant_filter() helper to filters.py. Update existing filter helpers to call it.
7. Dead code audit: TargetList references + database row count. Report result.
8. Orphan check: Teams without a resolvable account_id. Report result.
9. Define and activate CI grep check for missing tenant_filter() on tenant tables. Active on all PRs from Phase 1 forward.

Gate: All gaps patched. CI grep check active. TargetList and team orphan audit results documented.

---

Phase 1 — Schema Migration

Goal: Every tenant-relevant table has a direct, NOT NULL account_id column.

10. Add account_id to all tables in Section 1a (migration per logical domain group: core sessions, PSA, AI, steps, notifications)
11. Make nullable account_id NOT NULL on models from Section 1b
12. Migrate ScriptBuilderSession, ScriptTemplate, ScriptGeneration from team_id to account_id
13. TargetList: execute result of Phase 0 audit (drop or migrate)
14. Create template_trees and platform_steps tables; migrate global content

Gate: Zero NULL account_id values in any tenant table. All backfills verified. Database passes zero-NULL assertion query for every table in scope.

---

Phase 2 — PostgreSQL Infrastructure

Goal: Database roles established; SET LOCAL wired into every request; RLS test suite green.

15. Create resolutionflow_app and resolutionflow_admin PostgreSQL roles; grant privileges
16. Update DATABASE_URL to resolutionflow_app; add DATABASE_ADMIN_URL for admin connections
17. Update Alembic to use DATABASE_ADMIN_URL
18. Modify get_db() to execute SET LOCAL app.current_account_id per request, inside transaction boundary
19. Update super admin endpoints to use resolutionflow_admin connection
20. Write test_rls_isolation.py — all ~160 RLS tests. Must be 100% green before Phase 3. Connection pool reuse test included.
21. Measure SET LOCAL per-request overhead baseline

Gate: All RLS tests green. All existing integration tests green. Connection pool reuse test green. Performance baseline documented.

---

Phase 3 — Enable RLS

Goal: RLS policies active on all tenant tables. Phased by domain, not all at once.

Enable RLS in these batches. Run full test suite after each batch before proceeding:

Batch A: Core data trees, tree_categories, tree_tags, sessions, attachments, session_supporting_data, maintenance_schedules

Batch B: AI & sessions ai_sessions, ai_chat_sessions, ai_conversations, ai_usage, ai_session_steps, session_branches, session_handoffs, session_resolution_outputs, fork_points, copilot_conversations, flow_proposals

Batch C: Steps & library step_library, step_categories, step_ratings, step_usage_logs, ai_suggestions, template_trees (no RLS), platform_steps (no RLS)

Batch D: Integrations & users psa_connections, psa_post_logs, psa_member_mappings, subscriptions, account_invites, file_uploads, kb_imports, notifications, notification_logs, session_shares, user_folders, user_pinned_trees

Batch E: Scripts & auth script_builder_sessions, script_templates, script_generations, audit_logs

For each batch migration: ENABLE ROW LEVEL SECURITY + FORCE ROW LEVEL SECURITY + create all applicable policies.

Gate: All RLS tests green after each batch. All integration tests green. Staging smoke test after Batch E. No performance regressions.

---

Phase 4 — Ongoing

• Every PR that touches a tenant endpoint includes a cross-tenant isolation test
• CI grep check blocks PRs with missing tenant_filter() (warn → block after 2-week calibration)
• tree_shares RLS: design sharing model, implement tests, enable RLS before any sharing feature ships
• team_id columns: drop in a cleanup migration after all application code is fully migrated

---

Section 8: Background Job Policy

Background jobs and scheduled tasks that process tenant data are a distinct isolation surface. Unlike request-scoped endpoints, they do not have a current_user and must manage tenant context explicitly.

Policy

Every background job that touches tenant tables must comply with one of two patterns:

Pattern A — resolutionflow_admin with explicit per-query account_id filtering

Use when: the job is inherently cross-tenant (e.g., processes all pending work across all accounts in a single pass). The admin role bypasses RLS, so explicit account_id filters in every query are mandatory — RLS is not the safety net here.

# Allowed: cross-tenant batch SELECT for IDs only, then loop per-account
result = await db.execute(
    select(Model.id, Model.account_id).where(Model.status == "pending")
)
for row in result.all():
    await _process_one(row.id, row.account_id, db)  # account_id threaded through

# In the processing function: all queries must filter by account_id
async def _process_one(record_id, account_id, db):
    result = await db.execute(
        select(Model).where(Model.id == record_id, Model.account_id == account_id)
    )

Pattern B — resolutionflow_app with SET LOCAL per tenant loop iteration

Use when: the job processes tenants one at a time and it is practical to set the tenant context per iteration.

for account_id in account_ids:
    async with async_session_maker() as db:
        await db.execute(
            text("SET LOCAL app.current_account_id = :id"),
            {"id": str(account_id)}
        )
        # All queries in this block are RLS-enforced to this tenant

No cross-tenant queries without justification

No background job may issue a SELECT, UPDATE, or DELETE that spans multiple tenants' data in a single query without explicit written justification in the code comment and in this spec. Approved cross-tenant operations are documented below.

Inventory: Current Background Jobs

Job	File	Pattern	Status	Notes
Knowledge Flywheel	knowledge_flywheel_scheduler.py	Admin + explicit filter	Needs update	Batch SELECT across all accounts with no account_id filter. Must thread account_id from the session into all processing calls.
PSA Retry	psa_retry_scheduler.py	Admin + explicit filter	Needs update	Batch SELECT across all accounts with no account_id filter. Must add account_id to batch query and thread through to retry_failed_push.
Chat Retention Cleanup	retention_cleanup.py	Admin + explicit filter	Correct pattern	Already loops per-account with explicit account_id in all queries. Model for other jobs. Needs role update to resolutionflow_admin.
Maintenance Schedule Firing	scheduler.py (_fire_maintenance_schedule)	Admin + explicit filter	Needs update	Fetches MaintenanceSchedule and Tree by ID without account_id filter. After Phase 1, Session creation must set account_id. Add account_id to all queries.
AI Conversation Expiry	scheduler.py (_cleanup_expired_ai_conversations)	Admin, cross-tenant approved	Correct pattern	Cross-tenant DELETE by expires_at is explicitly justified: rows are expired regardless of tenant. Needs role update to resolutionflow_admin. Document this approval in code comment.

Approved cross-tenant queries

The following cross-tenant operations are explicitly approved. All others require a new entry here before shipping:

Job	Query	Justification
AI Conversation Expiry	DELETE FROM ai_conversations WHERE expires_at < NOW()	Time-based expiry is tenant-independent. Deleting expired rows does not expose data across tenants.
Chat Retention Cleanup	SELECT id FROM accounts	Required to iterate per-account. Read of account IDs only; no tenant data accessed.
Knowledge Flywheel (after fix)	SELECT id, account_id FROM ai_sessions WHERE analysis_status='pending'	Cross-tenant ID harvest only. No tenant data in the SELECT. account_id is threaded into per-tenant processing.
PSA Retry (after fix)	SELECT id, account_id FROM psa_post_logs WHERE status='pending_retry'	Cross-tenant ID harvest only. account_id threaded into per-tenant processing.

Checklist additions (Phase 2)

• All background jobs updated to use resolutionflow_admin role via DATABASE_ADMIN_URL
• Knowledge Flywheel: account_id added to batch query and threaded through to analyze_session
• PSA Retry: account_id added to batch query and threaded through to retry_failed_push
• Maintenance Schedule Firing: all queries include account_id; Session creation sets account_id after Phase 1 migration
• AI Conversation Expiry: cross-tenant approval comment added to code
• All jobs reviewed against this policy before Phase 3 (RLS enable)

---

Section 9: Open Questions

Question	Impact	Owner
Is tree sharing intra-tenant only, or can trees be shared across accounts?	Determines tree_shares schema, backfill strategy, and RLS policy. Tree_shares table deferred until resolved.	Product
What is the exact PostgreSQL exception raised when current_setting('app.current_account_id', false)::uuid is evaluated with no value set?	Determines the fail-closed test assertion. Must be tested in Phase 2.	Engineering
TargetList audit complete: active code references found in 12+ files across backend and frontend (full CRUD API, frontend page, used in MaintenanceScheduleSection and BatchLaunchModal). Cannot be dropped. Row count confirmed: 0 rows in production. Decision: migrate to account_id in Phase 1 via backfill from team_id → accounts. Zero rows means backfill is trivial (no data to migrate, just schema change).	✓ Resolved — migrate in Phase 1. Zero rows confirmed 2026-04-09.	✓ Done
Teams orphan check: 0 orphaned teams confirmed 2026-04-09. Phase 1 backfill using team_id → account_id chain is safe to proceed.	✓ Resolved — Phase 1 can proceed without team cleanup.	✓ Done

---

Appendix: Pre-Implementation Checklist

Everything that must be in place before writing feature code on any tenant-data endpoint:

Foundation (Phase 0)

• Copilot tree access bypass hotfix shipped
• Analytics flow endpoint ownership check added
• Category tree count scoped to account
• AI session list and search both restricted to user_id
• Full UUID endpoint audit completed; all gaps documented and fixed
• get_tenant_context dependency added to deps.py
• tenant_filter() helper added to filters.py
• Existing filter helpers updated to use tenant_filter() internally
• TargetList dead code audit result documented
• Teams orphan count query run and result documented
• CI grep check defined and active

Schema (Phase 1)

• account_id NOT NULL on all tables in Section 1a denormalization list
• account_id NOT NULL on all existing nullable models from Section 1b
• ScriptBuilderSession, ScriptTemplate, ScriptGeneration migrated from team_id
• TargetList: dropped or migrated per audit result
• template_trees and platform_steps tables created
• Zero NULL assertion passes for every tenant table
• Migration sequence (add nullable → backfill → verify → NOT NULL → index) followed for each table

Infrastructure (Phase 2)

• resolutionflow_app role created with correct privileges
• resolutionflow_admin role created with BYPASSRLS
• DATABASE_URL updated to resolutionflow_app
• DATABASE_ADMIN_URL added for admin connections
• Alembic uses DATABASE_ADMIN_URL
• get_db() executes SET LOCAL app.current_account_id per request inside transaction
• Super admin endpoints use admin connection
• All background jobs updated to use resolutionflow_admin role (see Section 8)
• Knowledge Flywheel: account_id threaded through batch query and analyze_session
• PSA Retry: account_id threaded through batch query and retry_failed_push
• Maintenance Schedule: all queries include account_id; Session creation sets account_id
• AI Conversation Expiry: cross-tenant approval comment added to code
• test_rls_isolation.py written with ~160 test cases
• All RLS tests pass (100%)
• Connection pool reuse test passes
• Fail-closed exception documented and asserted
• Performance baseline for SET LOCAL overhead documented

RLS Active (Phase 3)

• Batch A RLS policies applied and all tests green
• Batch B RLS policies applied and all tests green
• Batch C RLS policies applied and all tests green
• Batch D RLS policies applied and all tests green
• Batch E RLS policies applied and all tests green
• Staging smoke test passed
• All existing integration tests green with RLS active

Ongoing Standards

• Every new endpoint PR includes cross-tenant isolation test
• CI grep check blocks PRs with missing tenant_filter()
• tree_shares deferred — not enabled until sharing model documented
• team_id cleanup migration scheduled after full migration complete