tRPC compatibility

On 2026-09-23, #7726 changed page.list from a bare array to { items, nextCursor }. It updated every caller on main, so typecheck and tests passed. Desktop 1.30.0–1.30.2 still called .map on the result, and every workspace view crashed (SEV1, 337 Sentry events, postmortem "page.list response change crashed released desktop apps"). CI only sees main. This skill is how you check the builds CI cannot see.

1. Find released callers

Search the release tags, not main. Run git fetch --tags first in a fresh clone.

PROC='page\.list(?!Paginated)'   # the procedure path; exclude longer names that share the prefix
FLOOR=1.29.0                     # MINIMUM_DESKTOP_VERSION in apps/api/src/app/api/desktop/version/route.ts
for v in $({ echo "$FLOOR"; git tag -l 'desktop-v*' | sed 's/^desktop-v//'; } | awk '!/-/' | sort -uV | sed -n "/^$FLOOR\$/,\$p"); do
  git rev-parse -q --verify "refs/tags/desktop-v$v" >/dev/null || continue
  git grep -q -P "$PROC" "desktop-v$v" -- apps/desktop && echo "desktop-v$v calls it"
done

• Desktop: every desktop-v* tag at or above the floor is live.
• CLI: same loop with cli-v* tags and -- packages/cli. The CLI has no floor, so check every tag you can; old installs stay in use.
• Mobile: no tags, and MINIMUM_MOBILE_VERSION is 1.0.0. If apps/mobile on main calls it, or git log -S shows it ever did, treat it as called by a live build.
• SDK: packages/sdk calls procedures by string (/api/trpc/<procedure>). Search main and git log -S the same way.
• host-service procedures: callers are desktop, CLI, and mobile, and the host can be older or newer than the client. See packages/host-service/AGENTS.md.

Any hit means the procedure is live. Its input and output are frozen.

2. Check usage data

The API samples 1% of calls into the PostHog event api_procedure_called. Run this in the PostHog SQL editor or through the PostHog MCP:

SELECT properties.client_product AS product, properties.client_version AS version,
       count() * 100 AS est_calls, max(timestamp) AS last_seen
FROM events
WHERE event = 'api_procedure_called' AND properties.procedure = 'page.list'
  AND timestamp > now() - INTERVAL 30 DAY
GROUP BY product, version ORDER BY product, version

Zero rows is weak evidence for a rarely called procedure: 1% of a small number rounds to zero. Calls from web and from builds older than the x-superset-client header are not recorded.

3. Pick the pattern

You want to	Do this	Example
Change an output shape	New procedure; old one keeps its shape	page.list + page.listPaginated (#7756)
Add an input	New optional field, default in the handler (safe: old clients do not send it)
Accept a new input shape	Accept both, convert server-side	rrule + triggers in automation/schema.ts
Rename a procedure	New name; old name stays as a @deprecated alias	task.all → task.list in task/task.ts
Drop an input	Keep accepting it and ignore it	branch in task/schema.ts
Drop an output field	Keep sending it until removal is allowed	the plugins catalog field that #7317 removed crashed old desktops
Drop or rename a DB column	Pick the procedure's output columns first, keep the old field	db.query.*.find* without columns returns every column
Make an input stricter	Only on a new input or procedure	publishPageSchema is .strict() from the start, so a newer CLI fails loudly on an older server
Change an error code, default, or sort order	New procedure, or a new optional input that opts in (absent keeps the old behavior)	desktop branches on NOT_FOUND and CONFLICT
Call a new procedure from a client	Merge the API first, then the client after the API is live	#7317's API deploy stalled two days behind migration 0119

To check the API is live, the latest Deploy Production run after your API merge must have passed: gh run list --workflow deploy-production.yml --branch main --limit 5.

In client code, expect the unknown: guard new optional fields, handle enum values the client has not seen, and keep a failing widget from taking its parent view down with it. #7726 crashed the whole workspace view from one menu.

Keep the schema migration in its own PR. #7726 had a migration inside it, so the bad API change could not be reverted.

4. Remove a deprecated procedure or field

Only when both are true:

• Step 1 finds no call in a live desktop tag and no call from mobile, CLI, or SDK.
• Step 2 shows no calls from a live version over the last 30 days.

If a live desktop build still calls it, the only path is to raise MINIMUM_DESKTOP_VERSION. That is a product decision; ask, do not do it in a cleanup PR. Put the evidence in the PR description, as d1aee0922f did for device.heartbeat.

5. If released clients are already broken

1. Confirm with Sentry: a new desktop issue that starts at the API deploy time.
2. Does the PR that broke it include a migration that production already applied?
   • No: revert the PR. The API redeploys on merge.
   • Yes: write a forward fix that restores the old contract and moves the new shape to a new procedure, as #7756 did. Do not roll back the migration.
3. Tell affected users to reload (Cmd+R). Some needed to restart the app or the terminal daemon.

Checklist

• Step 1 run for every procedure whose input or output changed, with the result in the PR
• No existing input field is new-required, renamed, retyped, or more strictly validated
• No existing output field is removed, renamed, retyped, wrapped, or newly nullable, including through a DB column change on a find* without columns
• No change to an existing error code, default limit, sort order, or meaning of null
• No change to a procedure's type (query, mutation, subscription), the link, or the transformer
• No new required header or stricter auth on an existing procedure
• Client code that needs a new procedure merges after the API is live in production
• Every new input field is optional with a server-side default
• A replaced procedure is kept as a @deprecated alias
• No schema migration in the same PR as the contract change
• Removals: step 1 and step 2 evidence is in the PR