PaperClipAI/doc/connection-review-counts.md

# Connection review counts

The contextual App sidebar uses `GET /api/tool-connections/:connectionId/review-counts`
for its Review badge. The response contains `pendingActionRequestCount` and
`quarantinedCatalogEntryCount`. The badge adds the pending count and one when the
quarantine count is positive. Both sidebar variants keep the 30 second cadence.
The key is a child of the existing company attention prefix so current mutations
and events still invalidate it.

The route uses existing connection read admission. It resolves UUIDs and UIDs,
checks company and current actor/responsible-user authority, and enforces personal
account restrictions before reading counts. An authorized archived connection
returns zero counts, as its absent legacy attention item did. Missing and hidden
connections retain normal admission errors. This read adds no execution authority.

The catalog owner reads two independent scalar aggregates in one SQL statement.
Pending counts join requests to invocations by invocation ID and constrain both
company IDs. SQL NULL signed arguments are excluded; empty signed text counts.
Multiple requests for one invocation count separately. No profile, rule or active
catalog projection runs for this read. The company-wide attention API is unchanged.

## Local performance proof (2026-11-02)

Baseline: `3f8ebfff8aa9febd0733c6f65b07485dcadfd0e2` on current master, including
both prior evaluator fixes (#18673 and #18681). Treatment is the count reader in
this change. Node v24.22.2, macOS, disposable real embedded PostgreSQL, one database
connection, no cross-request cache. The comparison calls the actual legacy
attention service and selects one connection's two counts, then calls the new
reader. All normalized results equal `{pendingActionRequestCount: 2,
quarantinedCatalogEntryCount: 3}`.

Fixture: 200 profiles, 76,000 rules, 1,900 active tools, 695 removed references,
12 agents, one sibling connection, six quarantine entries, signed/unsigned/resolved
requests and 2,000 unrelated historical invocations. Reproduction:

```sh
cd server
node --expose-gc --import ./node_modules/tsx/dist/loader.mjs scripts/benchmark-connection-review-counts.ts
```

After two warmup pairs, seven alternating measured pairs in a coordinated quiet
window produced:

| Service measurement | Legacy attention → selected counts | Scoped counts |
| --- | --- | --- |
| Queries | 7 | 1 |
| Returned application rows | 80,115 | 1 |
| Process CPU median (range), ms | 213.891 (209.329–228.552) | 1.680 (0.515–6.137) |
| Wall median (range), ms | 156.867 (151.739–162.289) | 1.248 (1.115–1.386) |

Separate work-volume instrumentation serialized database result values to JSON:
32,978,153 versus 66 bytes. This measures decoded application values, not network
bytes or HTTP response size. The legacy HTTP response never contains the rule
arrays. Work-volume serialization is disabled during every timed sample.

These are local source-service measurements, not deployed latency or capacity
claims. They exclude HTTP admission, network transport and serialization. They do
not measure PostgreSQL CPU. Scoped SQL still scans relevant pending/catalog data
using existing indexes; no migration or new cache was needed.

## Correctness and preserved failures

PostgreSQL differential tests cover sibling/company boundaries, multiple requests,
NULL and empty signed text, unsigned/resolved requests, null invocation connections,
cross-company historical references, unhealthy-only connections, archive/restore,
and changed rows between reads. Assembled HTTP tests use actual human sessions
and agent JWT authentication with explicit permissions. They exercise UID lookup,
missing/foreign resources, personal grant revocation and membership revocation.
Both sidebar variants have badge, disabled-before-identity and prefix invalidation
component tests.

The first SQL attempt embedded column references directly into scalar raw SQL.
Real PostgreSQL rejected the resulting ambiguous unqualified columns. Typed
Drizzle subqueries fixed that failure; the passing differential test exercises the
corrected query. An initial benchmark serialized result values inside its timed
instrumentation and inflated CPU. That run was discarded; the results above come
from a fresh alternating run with byte accounting outside timing. Initial HTTP
fixtures lacked agent membership/management grants and correctly received 403;
the accepted fixture supplies both and retains revocation denial checks.

The built static UI was also exercised in Chromium against an owned local-trusted
server and disposable PostgreSQL. The connection Permissions page showed Review 3,
issued the scoped count request, and made no company attention request. After
resolving requests and clearing quarantines, reload removed the badge. An archived
connection returned zero counts. This browser path uses board authority; separate
authenticated HTTP fixtures prove delegated agent authority. The first ad hoc
browser launcher omitted required decision-service options and failed at startup;
adding the standard no-op wake callback allowed the same journey to pass. No
product behavior was changed to recover that harness setup failure.

Required local recursive typecheck and full build passed. The first sandboxed
typecheck could not open the tsx IPC socket; the escalated rerun passed. Greptile
identified an invalid resolved-request fixture label (`denied`); it was corrected
to the declared `rejected` status. This preserves the non-pending exclusion that
the differential test verifies.

The first final-head CI run flagged the new explicit resource company assertion
because the route lacked a local `hasCompanyAccess` existence gate. Management
admission already rejects foreign resources with 404, but the route now also
follows the repository's two-step gate pattern. The static existence-oracle guard
and actual authenticated HTTP negative cases verify that pattern together.