fix(storage): stop workspace ledger locks from deadlocking on FK key-share

[waleedlatif1]

Summary

• Workspace storage accounting locked workspace, organization, and user_stats with SELECT ... FOR UPDATE. All three are foreign-key parent rows, so a transaction that has already inserted a billable child row (a workspace_files row, in the same transaction) holds an implicit FOR KEY SHARE on the parent. The FOR UPDATE is then a lock upgrade, and two concurrent uploads in one workspace take it on each other — deadlock detected.
• Switched these locks to FOR NO KEY UPDATE. It does not conflict with FOR KEY SHARE, still conflicts with itself and with FOR UPDATE, and is exactly the lock a plain UPDATE of these non-key counters takes anyway — so the ledgers stay serialized against each other and against payer transfers.
• Applied the same downgrade to every remaining workspace-row lock (permissions, credentials, table creation, copilot file materialization, workspace payer moves). FOR UPDATE on a workspace row also blocks every insert into its 49 child tables for the life of the transaction; the weaker lock preserves each site's mutual exclusion without that stall.
• Left knowledge_base / knowledge_connector / user_table_definitions mutation locks alone — different resources, and relaxing those changes what they serialize against.

Root cause evidence

Reproduced end-to-end against a local Postgres with the real migrated schema, driving the actual code path:

concurrent uploads to one workspace	FOR UPDATE	FOR NO KEY UPDATE
2	1 committed, 1 deadlock detected	2 committed
6	1 committed, 5 deadlock detected	6 committed

The failing statement is byte-for-byte the one in the error report, and the counter drifts (100 instead of 600) because the losing transactions roll back. Also measured the row-lock conflict matrix directly: NO KEY UPDATE conflicts with itself and with FOR UPDATE, but not with KEY SHARE; and a parent held FOR UPDATE blocks a concurrent child insert, while one held FOR NO KEY UPDATE does not.

Type of Change

• Bug fix

Testing

• End-to-end deadlock reproduction and fix verification against a real Postgres, as above
• Added regression tests asserting every storage ledger lock is no key update; confirmed they fail when the lock strength is reverted
• 480 test files / 6177 tests pass across billing, workspaces, uploads, knowledge, tables, credentials, copilot, workspace API
• bun run type-check, bun run lint, bun run check:audits (37 audits) all pass

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Aug 28, 2026 1:33am

[greptile-apps]

Greptile Summary

The PR replaces unnecessarily strong PostgreSQL workspace and payer ledger locks with FOR NO KEY UPDATE, preserving writer serialization while avoiding conflicts with foreign-key KEY SHARE locks.

• Updates storage tracking and payer-transfer locks for workspace, organization, and user ledgers.
• Applies the same workspace lock mode to permission, credential, table-creation, materialization, and organization-move transactions.
• Adds regression assertions covering individual and batched payer lock modes.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
apps/sim/lib/billing/storage/tracking.ts	Changes workspace and payer ledger locks to FOR NO KEY UPDATE while retaining consistent workspace-before-payer ordering and adds rationale for the lock contract.
apps/sim/lib/billing/storage/payer-transfer.ts	Uses FOR NO KEY UPDATE for ordered workspace and payer locks without changing payer-transfer calculations or mutation ordering.
apps/sim/lib/billing/storage/tracking.test.ts	Adds regression coverage asserting the weaker lock mode for both user and organization payers in individual and batched mutations.
apps/sim/lib/workspaces/organization-workspaces.ts	Downgrades workspace-row locks used during organization attachment and payer transitions while retaining mutual exclusion among row writers.
apps/sim/lib/workspaces/permissions/utils.ts	Updates the optional transactional workspace lock used by permission mutations to FOR NO KEY UPDATE.

Sequence Diagram

sequenceDiagram
    participant U1 as Upload transaction A
    participant U2 as Upload transaction B
    participant C as Billable child rows
    participant W as Workspace ledger
    participant P as Payer ledger
    U1->>C: Insert billable row
    U2->>C: Insert billable row
    Note over U1,U2: Each transaction holds KEY SHARE on parent rows
    U1->>W: FOR NO KEY UPDATE
    U1->>P: FOR NO KEY UPDATE
    Note over U2,W: Waits for transaction A without a KEY SHARE lock upgrade
    U1->>W: Update storage counter
    U1->>P: Update payer counter
    U1-->>U2: Commit and release locks
    U2->>W: Acquire FOR NO KEY UPDATE
    U2->>P: Acquire FOR NO KEY UPDATE
    U2->>W: Update storage counter
    U2->>P: Update payer counter

Loading

_{Reviews (3): Last reviewed commit: "docs(table): correct the stale FOR UPDAT..." | Re-trigger Greptile}

[cubic-dev-ai]

1 issue found across 11 files

Confidence score: 4/5

• In apps/sim/lib/billing/storage/tracking.test.ts, both regression tests use ORG_CONTEXT, so they verify only workspace and organization locks while leaving the userStats payer lock unchecked; a lock-mode regression there could pass unnoticed. Add coverage using the appropriate user-stats payer context.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/sim/lib/billing/storage/tracking.test.ts">

<violation number="1" location="apps/sim/lib/billing/storage/tracking.test.ts:219">
P2: The new regression tests claim to assert every storage ledger lock is FOR NO KEY UPDATE, but both use ORG_CONTEXT (organization payer), so only the workspace and organization locks are checked. The userStats payer lock (lib/billing/storage/tracking.ts lines 160-163 and 333-337) is never exercised by these assertions, so a revert of only the user-payer lock to FOR UPDATE would still let both new tests pass. Add a test that runs a mutation against a `user` billing entity and asserts mockTxFor/mockTxOrderedFor is called with 'no key update' to close the gap.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[waleedlatif1]

@greptile

[waleedlatif1]

@cubic review

[cubic-dev-ai]

@cubic review

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

No issues found across 11 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Re-trigger cubic}

[waleedlatif1]

@greptile