mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 03:31:44 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The board UI polls `GET /api/companies/:companyId/skills`, and the server runs all requests on one Node main thread > - The cost on that thread is per database statement, so a polled read must stay small > - Each skills list read reconciles the bundled skill folders, and that opened two transactions with a company advisory lock, even when all folders already existed > - A write-path guard must not run a lock and a transaction on every poll > - This pull request checks the current folders with a plain read first and takes the lock only when a folder must change > - The benefit is a skills list read with no transaction and no advisory lock, and 13 fewer statements (58 to 45) ## Linked Issues or Issue Description **What existing behavior does this improve?** `folderService.ensureBundledCategory` and `pruneEmptyBundledCategories` always open a transaction and take `pg_advisory_xact_lock` for the company folders. **Subsystem affected** Server: skill folders service, used by the company skills list. **Current behavior** Every `GET /api/companies/:companyId/skills` sends 58 statements, including 2 transactions (BEGIN, lock, reads, COMMIT), even when nothing changes. **Proposed behavior** `ensureBundledCategory` reads the company skill folders once. When the bundled root exists and the category folder exists with the expected name, it returns that folder. `pruneEmptyBundledCategories` computes the empty categories with plain reads and returns when there is nothing to delete. In all other cases, both functions take the lock and run the old code, which reads the folders again under the lock. The same request sends 45 statements with no transaction. **Reason and benefit** The polled read stops taking a company lock, and it sends fewer statements. **Breaking changes** None. ## What Changed - `ensureBundledCategory`: a plain read fast path when the category folder and the bundled root exist and the name matches. Create and rename still run under the company folder lock. - `pruneEmptyBundledCategories`: a plain read pre-check. The delete still runs under the lock, and it computes the empty set again under the lock. - New test `company-skills-list-statements.test.ts`: a warm skills list read has no transaction and no advisory lock and at most 45 statements; two concurrent first ensures create exactly one folder; two concurrent first list requests create no duplicate folder; a renamed category is repaired and an empty category is pruned through the locked path. ## Verification - Red: before the change, the warm read had 2 transactions (`expected 2 to be +0`) and 58 statements. - Green: after the change, the warm read has 0 transactions, no `pg_advisory` statement, and 45 statements. The response body is equal to the first read. - Concurrency: two `ensureBundledCategory` calls at once return the same folder, and there is exactly one row for the system key. - `pnpm exec vitest run` on `company-skills-list-statements`, `company-skills-service`, `company-skills-routes`, `company-skills-runtime-concurrency`, `company-skills-catalog-service`, `company-skills` and the folder tests: 215 tests pass. Two `company-skills.test.ts` tests in "project workspace skill discovery" fail on my machine with and without this change. They test file system discovery and do not use the folders service. - `pnpm --filter @paperclipai/server typecheck` passes. ## Risks - Low risk. The fast path returns only when the locked path would return the same folder without a write. Every write still happens under the lock, after a fresh read. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude Code with tool use (shell, file edits, test runs). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>