Files
PaperClipAI/server/src/modules
Nicky LeachandPaperclip 8af66f48e9 Admit explicit queued steering with durable acknowledgement in wake-queue (#22276)
## Thinking Path

> - A board user can send a queued message into an active agent turn.
> - The server must know which queue, issue and run the user selected.
> - A provider can accept a message even when the client loses the HTTP
response.
> - The route previously handled authorization, replay, delivery,
database writes and response construction in one block.
> - Wake-queue can own the steering operation and its acknowledgement
while the route keeps the board access decision.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

Explicit same-turn delivery of a queued board comment or interaction.

**Subsystem affected**

Server task admission.

**Current behavior**

The issue route issues SQL, interprets the provider acknowledgement and
updates the wake, run and identity.

**Proposed behavior**

The route calls one steering command. The command decides replay, checks
the revision and the selected entry, and leaves an uncertain delivery
pending. The adapter handles identity reservation, the issue and wake
locks, and persistence after acknowledgement.

**Additional context**

Builds on the board queue extraction. Related earlier work in #13160
locked the target run while waiting for a provider. Today's runner
writes its acknowledgement to that row.

## What Changed

- Use the shared board queue read and lock for pending messages and
acknowledgement replay.
- Keep the target run available while waiting for the provider. Re-read
and lock the scoped run after acknowledgement and preserve concurrent
result updates.
- Leave HTTP access, activity logging, response redaction and error
translation with the route.

## Verification

On a3d18b1b66, the full route and mutation suites passed 162 tests
together with the repository Postgres runner. An independent route-only
run passed all 145 assertions and timed out cleaning up the database.
Eleven focused checks passed, including the final interrupt audit
assertion. Server typecheck and module boundaries passed.

Run the queued-comment route suite and the wake-queue application tests.
Exercise exact replay, concurrent acknowledgement writes, stopped
targets, fresh-session approvals, permission checks, definite rejection
and an uncertain timeout.

## Risks

A wrong acknowledgement decision could consume a message twice or drop
an undelivered message. The transaction checks the company, issue, agent
and run and merges the latest result before consuming the queue entry.

## 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>
2026-11-18 19:24:40 -08:00
..

Feature modules

A feature module under server/src/modules/<name>/ uses three layers. Each layer has one rule: which layer below it, it may import from.

adapters  →  application  →  domain
  • domain/ holds pure business rules. A domain file takes plain data in and returns plain data out. A domain file must not import drizzle-orm, @paperclipai/db, a service under server/src/services/, a route under server/src/routes/, or a Node.js I/O module (node:child_process, node:fs, node:net). A domain function must not read the system clock; the caller passes now as an explicit Date value.
  • application/ holds use cases and the ports they need. A use case takes its ports as constructor arguments and calls domain functions for policy decisions. An application file must not import drizzle-orm, a SQL client, a concrete adapter, or the server's HTTP error helpers. The outer service or route translates application errors into transport responses.
  • adapters/ holds the concrete implementations of the ports: Postgres queries, transactions, and process control. An adapter file may import drizzle-orm, @paperclipai/db, and Node.js I/O modules.

A module exposes its commands through index.ts, which composes the adapters and the use cases behind a factory function. Code outside the module imports that entry point, never a file inside domain/, application/, or adapters/ directly.

pnpm check:module-boundaries enforces these rules for production source files. It also checks access to the company deletion entry point below.

Company deletion

The existing company deletion service owns the database transaction and deletion order. A module can expose a separate company-deletion.ts entry point. Only services/company-deletion.ts can import this entry point. The entry point exports an implementation of CompanyDeletionParticipant from lib/company-deletion.ts. Do not export it through the normal module index.

The service must complete external cleanup before it starts the transaction. It must lock the company before it deletes dependent records or calls a module. Creation commands must use the same company lock. The service removes dependent records before it calls the module. The module checks its deletion conditions and deletes the records it owns. Use the supplied transaction. Do not start another transaction or call external systems. Throw an error if deletion cannot proceed. An error must roll back all database changes in the deletion transaction.

Call each module explicitly in dependency order. No module registry is required.

The agent lifecycle module also has a restricted configuration.ts entry point. It saves configuration and invalidates verification in the caller's transaction. The lifecycle guide lists its permitted callers. Ordinary configuration updates use the root lifecycle command.

The agent lifecycle module owns agent creation, pause, resume, and termination. Use its commands for these changes.

The execution admission module owns project task-execution policy and the durable admission records that charge project capacity. Today it exposes only internal policy commands and the deletion guards that project, agent, and company deletion call. Settlement releases active charges but keeps each admission's complete project set for later retained-session resolution. Execution claims still belong to services/heartbeat/queue.ts and native review dispatch. See execution admission accounting.

Execution admission accounting

The execution-admission module (server/src/modules/execution-admission/) owns three tables. Nothing writes admissions or caps in production yet, and no claim path enforces a project maximum.

  • project_task_execution_policies stores a project's maximum concurrent tasks apart from projects, so project readers never return an unenforced cap. No row means never configured. A row with a null maximum means an explicit "no limit", which a later legacy migration must not overwrite. Maximums are positive. The row is deleted with its project.
  • execution_admissions stores one admission attempt of a run. A run can be released before dispatch and admitted again, so (run_id, attempt) is unique and a partial unique index allows one unsettled attempt per run. The row keeps the context revision, the nullable primary project as provenance (no foreign key) and the settlement identity, which is set together with settled_at. admitted_project_ids is the complete admitted project set, sorted, kept after settlement and immutable (a trigger rejects any change). It has no project foreign key, so settled history never blocks project deletion and keeps the deleted project's ID. {} is a known empty set. Null means unknown and is allowed only on settled rows: migration 0428 filled it from the charges of unsettled rows, but settled 0426 rows had already lost their set. A retained provider session resumes with the previous set ∪ the current references; an unknown previous set requires a fresh context, never an empty or primary-only guess.
  • execution_admission_project_charges stores one row per distinct admitted project, including unlimited projects. An admission without projects has no rows. Composite (company_id, …) foreign keys keep admissions and projects in one company. Rows are the only active capacity and exist only while the admission is unsettled: settlement deletes the whole set in one transaction, and (company_id, project_id) is indexed for active counts, so lookups scale with active work, not history.

Archiving a project changes no charge. Deleting a project with a charge returns 409 project_execution_admission_pending; the foreign key is the backstop. Deleting an agent refuses unsettled admissions on its runs and removes settled ones, with their sets, together with the runs. Company deletion removes the company's admissions before its runs and projects.

The proposed global lock order for the admission transaction is: company row (FOR NO KEY UPDATE), native finalization recovery owner, the whole project set in ascending ID order (FOR NO KEY UPDATE, one statement), issues, wake requests, the run, the external-admission advisory lock, the admission row and its charges, then budget reservations. Policy updates take the same project lock. Settlement takes no project lock. Only the project-set step is implemented so far; claim paths keep their current locks until they are integrated.