mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 09:50:48 +01:00
## Thinking Path > - Paperclip manages AI agents at work. > - Assigning a task or resuming it from a comment can create a queued run. > - The wake-queue module handles admission behind an active execution. Heartbeat also writes the receipt and run when a new execution is needed. > - These writes share the issue lock. Splitting them across transactions would allow duplicate or partially bound work. > - This change puts the fresh writes in the wake-queue module under the existing lock. ## Linked Issues or Issue Description **What existing behavior does this improve?** Creating a queued run for an assigned or continued task. **Subsystem affected** Server task admission. **Current behavior** Heartbeat constructs the receipt and run, handles retry lineage, and ties adopted receipts to the run. **Proposed behavior** Wake-queue owns receipt promotion, fresh-run construction, and receipt binding. Heartbeat still selects saved comments and orders recovery effects inside the same transaction. **Additional context** Earlier module boundaries were introduced in #13136 and #13145. ## What Changed - Move fresh receipt, run, and binding writes to a transaction-bound Postgres adapter. - Keep explicit continuation and reconciled retry lineage in the application layer. - Scope receipt updates by company and durable promotion by agent. Cover both predicates with a database test. ## Verification On commit7479acbd22, all 104 heartbeat queue tests passed using the repository Postgres command runner. All 297 assertions passed in the six-file sweep. The standalone cluster cleanup timeout also reproduced on pristine base92dbf39e6fafter all 103 base tests passed. `node cli/node_modules/tsx/dist/cli.mjs packages/db/src/test-postgres-command.ts -- node node_modules/vitest/vitest.mjs run server/src/services/heartbeat/queue.test.ts` Run `pnpm exec vitest run server/src/services/heartbeat/queue.test.ts server/src/__tests__/heartbeat-comment-wake-batching.test.ts server/src/__tests__/heartbeat-stale-queue-invalidation.test.ts`. Run `pnpm --filter @paperclipai/server typecheck` and `node scripts/check-module-boundaries.mjs`. ## Risks Changing write order can attach the wrong receipt or lose retry lineage. The caller retains the transaction and the interleaved chat and recovery effects. This is a structural change. No latency improvement is claimed. ## Model Used OpenAI GPT-6.2 Sol (`gpt-6.2-sol`) implemented the change. OpenAI Codex directed the work, reviewed the diff, and ran qualification. ## 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 - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge Co-authored-by: Paperclip <noreply@paperclip.ing>