feat(run-ops): webapp db topology, flags, and split-mode resolver wiring

[d-cs]

What

Wires the run-ops split into the webapp: database topology, environment flags, split-mode gating, and the control-plane resolver/cache layer that the run-store and run-engine seams from the previous PR plug into.

• DB topology & env (apps/webapp/app/db.server.ts, env.server.ts, entry.server.tsx): adds the run-ops database clients/topology and the environment variables that configure and gate the split.
• runOpsMigration module (new apps/webapp/app/v3/runOpsMigration/): the webapp-side machinery — splitMode.server.ts, controlPlaneResolver.server.ts + controlPlaneCache.server.ts, readThrough.server.ts, crossSeamGuard.server.ts, distinctDbSentinel.server.ts, id-minting helpers (mintBatchFriendlyId, runOpsMintKind, resolveInheritedMintKind), runOpsCascadeCleanup.server.ts, the split read gate, and route/unblock catalogs.
• Store/engine wiring (app/v3/runStore.server.ts, runEngine.server.ts, runEngineHandlers.server.ts + new runEngineHandlersShared.server.ts): points the webapp's store/engine construction at the resolver, and factors shared handler logic out so both seams use one path.
• Read-path touch-ups: runtimeEnvironment.server.ts, eventRepository/index.server.ts, taskRunHeartbeatFailed.server.ts, engineVersion.server.ts route their run/environment lookups read-through the resolver.
• 413a94511 — interlocks split mode against the native realtime backend so the two aren't enabled in an incompatible combination (see .server-changes/run-ops-split-realtime-interlock.md).
• dc74c57fd — drops the earlier "known-migrated" read layer; residency is determined by id-shape only.

Why

PR5 of the run-ops split stack. This is the webapp foundation layer: it stands up the DB topology, flags, and resolver/cache the rest of the stack depends on, and repoints webapp read paths through the resolver. Additive when the split is not enabled (existing single-DB behavior preserved behind flags); behavior-changing on the read-through paths and the realtime interlock.

Tests

New vitest coverage across apps/webapp/test/ and colocated *.server.test.ts files: db topology, split mode, split read gate, cross-seam guard, mint cutover / flip latency, control-plane cache, control-plane resolver, distinct-db sentinel, read-through loaders (route loaders, run-detail loaders, findEnvironmentFromRun), and the run-engine handlers. Testcontainers-backed; no mocks. pnpm-lock.yaml synced for the two new webapp deps.

Notes

Draft, stacked on #4116 (runops/pr04-store-engine). 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: 071cdc1

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 PR introduces a gated dual-database "run-ops split" architecture separating control-plane data from run-scoped task/batch data. It adds a cache-first ControlPlaneResolver, a split-aware RunStore with residency-based routing, a readThroughRun cross-DB read layer, a crossSeamGuard for completion routing, boot-time distinct-database and realtime interlocks, and a cuid/ksuid run-id mint-kind cutover mechanism with inheritance rules for child runs and batches. Run-engine event handlers and batch completion logic are refactored to use these shared helpers. New environment variables gate all behavior (OFF by default), and extensive unit and Testcontainers-based integration tests validate cross-database resolution, routing, caching, and cutover semantics. A cascade cleanup service and cache invalidation hooks are also added for consistency on writes.

Changes

Related PRs: None identified.

Suggested labels: review_needed_junior_swe, review_depth_standard

Suggested reviewers: None specified.

Poem

A rabbit hops between two dens,
One old, one new, with cache-lined pens,
It sniffs each run-id, cuid or ksuid,
Routes it home where it belongs, unswayed.
Boot-time checks stand guard at the door—
Split enabled? Probe once more.
Hop, hop, hooray, the burrow's split with care! 🐇

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 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: webapp DB topology, flags, and split-mode resolver wiring.
Description check	✅ Passed	The description is thorough and on-topic, but it does not follow the template headings for Closes, checklist, changelog, or screenshots.

✨ 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/pr05-webapp-foundation

---

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@071cdc1

trigger.dev

npm i https://pkg.pr.new/trigger.dev@071cdc1

@trigger.dev/core

npm i https://pkg.pr.new/@trigger.dev/core@071cdc1

@trigger.dev/python

npm i https://pkg.pr.new/@trigger.dev/python@071cdc1

@trigger.dev/react-hooks

npm i https://pkg.pr.new/@trigger.dev/react-hooks@071cdc1

@trigger.dev/redis-worker

npm i https://pkg.pr.new/@trigger.dev/redis-worker@071cdc1

@trigger.dev/rsc

npm i https://pkg.pr.new/@trigger.dev/rsc@071cdc1

@trigger.dev/schema-to-json

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

@trigger.dev/sdk

npm i https://pkg.pr.new/@trigger.dev/sdk@071cdc1

commit: 071cdc1