feat(run-ops): webapp routes — friendlyId reads, cross-seam token resolution, co-location writes

[d-cs]

What

Wires the run-ops split into the webapp routes so requests are routed correctly across the store boundary. Builds on the presenter rework from the previous PR; this layer is the route/loader/action glue that calls those presenters and the run store.

• Route loaders and actions that previously looked runs up by internal id now resolve by friendlyId through the run store, so a run is found regardless of which store holds it. This spans the dashboard run routes, the resource routes (resources.runs.*, resources.taskruns.* cancel/debug/replay, logs download), the API batch/run routes (api.v1/api.v2/api.v3), realtime routes, sync-traces, and the admin debugRun helper.
• Public wait-token routes are updated to resolve tokens across the split boundary: the waitpoint-token complete / callback / retrieve / wait routes look the token up through the store, and the resolver re-checks auth after resolution rather than relying on a co-located join. Waitpoint writes go to the co-location store that owns them.
• Waitpoint-token handling is moved onto an always-cuid contract, and the token tests are rewritten against that contract.

New tests cover token resolution across the seam (waitpointTokenResolve), the cross-seam guard on the complete route, the control-plane callback path, and the api.v1.waitpoints.tokens surface.

Why

Part of the run-ops database split. This is PR9 of the series (PR8/9/10): it connects the split-aware read presenters (PR8) to the actual HTTP/loader surface so reads and token resolution route correctly, without yet enabling the split. The behaviour-changing activation stays isolated in PR10 on top of this.

Tests

pnpm run test --filter webapp for the affected route/resolver suites, including the new cross-seam-guard and waitpoint-token suites.

Notes

Draft, stacked on #4122 (runops/pr08-presenters). Review that first; this diff is against it.

Server-change / changeset note to be added at stack-assembly time.

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: daf148a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Walkthrough

This change migrates numerous webapp routes and admin tooling from directly querying Prisma relations (run.runtimeEnvironment, run.project, waitpoint.environment) to resolving environments via a new controlPlaneResolver and runStore abstraction. Waitpoint lookups now use a resolveWaitpointThroughReadThrough helper that fans out across run-ops and control-plane replica databases. Batch task run lookups migrate to runStore methods. Presenters (waitpoint, batch list/detail) are wired with explicit run-ops replica clients and split-read flags. Extensive new tests validate cross-seam waitpoint residency, completion guard ordering, store selection, and HTTP-callback resolution across heterogeneous Postgres databases. A changelog entry documents the routing change.

Changes

Area	Change
Run redirect/impersonation routes	Narrow findRun selections, add explicit authorization checks and controlPlaneResolver.resolveAuthenticatedEnv calls
Run detail/debug/cancel/replay/download routes	Replace embedded Prisma joins with separate authorization plus resolved environment/locked-worker context
Realtime routes	Resolve environment via control plane instead of nested runtimeEnvironment relations
Waitpoint completion/callback routes	Use resolveWaitpointThroughReadThrough for cross-store resolution; createDateTimeWaitpoint now passes runId
Batch routes	Migrate lookups from $replica queries to runStore methods; idempotency checks enforce environment match
Presenters	Construct with explicit runOpsNewReplicaClient/runOpsLegacyReplica/splitEnabled dependencies
Admin debug tool	Use resolved environment for Redis/MarQS key generation
Tests	New suites for cross-seam waitpoint residency, completion guards, store selection, and callback resolution
Docs	New changelog entry describing run-ops split route read routing

Sequence Diagram(s)

sequenceDiagram
participant Route as Route Loader/Action
participant RunStore as runStore
participant Replica as $replica (authorization)
participant Resolver as controlPlaneResolver
Route->>RunStore: findRun(friendlyId, select ids)
Route->>Replica: project.findFirst (membership check)
Replica-->>Route: authorized project or null
Route->>Resolver: resolveAuthenticatedEnv(runtimeEnvironmentId)
Resolver-->>Route: resolved environment or null
Route-->>Route: build redirect/response using resolved environment

Loading

sequenceDiagram
participant Route as Waitpoint Route
participant ReadThrough as resolveWaitpointThroughReadThrough
participant RunOps as run-ops replica
participant ControlPlane as control-plane replica
participant Resolver as controlPlaneResolver
Route->>ReadThrough: resolve(waitpointId, environmentId)
ReadThrough->>RunOps: waitpoint.findFirst
alt not found in run-ops
ReadThrough->>ControlPlane: waitpoint.findFirst
end
ReadThrough-->>Route: waitpoint record
Route->>Resolver: resolveAuthenticatedEnv(waitpoint.environmentId)
Resolver-->>Route: environment (with parentEnvironment apiKey fallback)
Route-->>Route: verify hash / complete waitpoint

Loading

Related PRs: None identified.

Suggested labels: area: webapp, area: runengine

Suggested reviewers: ericallam, matt-aitken

<sub>🥕 A carrot in the codebase, resolved through the plane,

No longer hopping down the relation lane.

Read-through routes across two stores it goes,

Where waitpoints live, now only the resolver knows.

Tests dig deep in PG14 and PG17's soil.</sub>

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description covers intent and testing, but it does not follow the required template and omits Closes #issue, checklist, and screenshots sections.	Rewrite the PR description to match the template: add Closes #issue, complete the checklist, keep Testing/Changelog, and include Screenshots.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title is concise and accurately summarizes the main change: run-ops split-aware reads and waitpoint token handling.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch runops/pr09-routes

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

@trigger.dev/build

npm i https://pkg.pr.new/@trigger.dev/build@56ec38c

trigger.dev

npm i https://pkg.pr.new/trigger.dev@56ec38c

@trigger.dev/core

npm i https://pkg.pr.new/@trigger.dev/core@56ec38c

@trigger.dev/python

npm i https://pkg.pr.new/@trigger.dev/python@56ec38c

@trigger.dev/react-hooks

npm i https://pkg.pr.new/@trigger.dev/react-hooks@56ec38c

@trigger.dev/redis-worker

npm i https://pkg.pr.new/@trigger.dev/redis-worker@56ec38c

@trigger.dev/rsc

npm i https://pkg.pr.new/@trigger.dev/rsc@56ec38c

@trigger.dev/schema-to-json

npm i https://pkg.pr.new/@trigger.dev/schema-to-json@56ec38c

@trigger.dev/sdk

npm i https://pkg.pr.new/@trigger.dev/sdk@56ec38c

commit: 56ec38c

[d-cs]

On the three maintainability nitpicks in the review summary:

• The as unknown as PrismaClientOrTransaction double-casts on the injected run-ops replica clients are intentional and consistent across the waitpoint presenter wiring. The run-ops replica client types are structurally compatible at the call sites we use; aligning the exported client types to drop the cast is a broader typing change outside this PR's read-routing scope. Kept as-is for consistency (the newly-wired waitpoint detail route follows the same pattern).
• The tag-write test asserting the write lands on the control-plane client: noted; the production tag path is covered by the route-level tests, and rewiring this assertion through the model function pulls in unrelated route deps for no additional coverage of the split behaviour under test.

No code changes for these; the security/correctness comments have been addressed in the latest commit.

[devin-ai-integration]

Devin Review found 1 new potential issue.