fix(runtime): dedupe in-flight contract verification

[aqrln]

K concurrent queries against a cold runtime in onFirstUse/startup modes used to issue K separate marker round-trips before the first one flipped verified=true. They now share a single in-flight verify promise so cold page loads pay one marker_read RTT instead of (K-1) extra ones.

always mode keeps its per-call semantics — concurrent callers each observe a fresh marker read, so re-verify under concurrency does not silently degrade to onFirstUse.

Closes: TML-2303

Summary by CodeRabbit

• Performance

  • Reduced redundant database queries by deduplicating concurrent marker verification during cold starts, while preserving fresh reads for "always" mode.
  • Improved concurrency handling so successful validation sets startup state and failures propagate to concurrent callers.

• Tests

  • Added tests covering marker verification deduplication, warm vs cold semantics, non-deduping mode behavior, failure sharing, and retry after failure.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 33ddee26-d957-47a8-948e-a61f8fb6a120

📥 Commits

Reviewing files that changed from the base of the PR and between 2d30446 and 354c31a.

📒 Files selected for processing (2)

• packages/2-sql/5-runtime/src/sql-runtime.ts
• packages/2-sql/5-runtime/test/sql-runtime.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/2-sql/5-runtime/src/sql-runtime.ts

---

📝 Walkthrough

Walkthrough

Adds in-flight deduplication for SQL contract marker verification by introducing a shared verifyInFlight promise, refactoring verifyMarker to coordinate callers and extracting runMarkerRead(). Tests add a driver query spy and a suite covering concurrent verification behaviors and failure propagation.

Changes

Marker Verification Deduplication

Layer / File(s)	Summary
In-flight field packages/2-sql/5-runtime/src/sql-runtime.ts	Adds private verifyInFlight and initializes it in the constructor to track concurrent marker-read promises.
verifyMarker coordination packages/2-sql/5-runtime/src/sql-runtime.ts	Refactors verifyMarker() to return early if already verified, use per-call reads for always, await or set verifyInFlight for other modes, and clear it after completion.
Marker read implementation packages/2-sql/5-runtime/src/sql-runtime.ts	Extracts marker read and validation into private runMarkerRead(); preserves semantics for required-marker, storage/profile hash checks, and sets startupVerified/verified.
Test spy additions packages/2-sql/5-runtime/test/sql-runtime.test.ts	Extends DriverMockSpies with driverQuery and exposes it via mock driver's __spies to observe query calls.
Test coverage packages/2-sql/5-runtime/test/sql-runtime.test.ts	Adds marker verification dedupe test suite exercising concurrent callers, always/onFirstUse/startup semantics, failure sharing, and retry-after-failure behavior.

Sequence Diagram

sequenceDiagram
    participant Caller1 as Caller 1
    participant Caller2 as Caller 2
    participant Runtime as SQL Runtime
    participant Driver as Driver

    Caller1->>Runtime: verifyMarker()
    activate Runtime
    Note over Runtime: Check verified / verifyInFlight
    alt no in-flight & not always
        Runtime->>Driver: runMarkerRead() (store promise in verifyInFlight)
        activate Driver
    else always
        Runtime->>Driver: runMarkerRead() (per-call)
        activate Driver
    end
    Caller2->>Runtime: verifyMarker()
    Note over Runtime: reuse verifyInFlight or start own read
    Driver-->>Runtime: Marker result / error
    deactivate Driver
    deactivate Runtime
    Runtime-->>Caller1: Result / throw
    Runtime-->>Caller2: Result / throw

Loading

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 I nibble code by moonlit gleam,

Two callers race, one gentle scheme.
A single promise keeps the night—
No double hops, just shared delight. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title 'fix(runtime): dedupe in-flight contract verification' accurately summarizes the main change: deduplicating redundant marker verification calls in-flight to reduce database round-trips on cold starts.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 tml-2303-dedupe-in-flight-contract-verification

---

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

[pkg-pr-new]

Open in StackBlitz

@prisma-next/mongo-runtime

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-runtime@431

@prisma-next/family-mongo

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/family-mongo@431

@prisma-next/sql-runtime

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-runtime@431

@prisma-next/family-sql

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/family-sql@431

@prisma-next/extension-arktype-json

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/extension-arktype-json@431

@prisma-next/middleware-telemetry

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/middleware-telemetry@431

@prisma-next/mongo

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo@431

@prisma-next/extension-paradedb

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/extension-paradedb@431

@prisma-next/extension-pgvector

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/extension-pgvector@431

@prisma-next/postgres

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/postgres@431

@prisma-next/sql-orm-client

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-orm-client@431

@prisma-next/sqlite

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sqlite@431

@prisma-next/target-mongo

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/target-mongo@431

@prisma-next/adapter-mongo

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/adapter-mongo@431

@prisma-next/driver-mongo

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/driver-mongo@431

@prisma-next/contract

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/contract@431

@prisma-next/utils

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/utils@431

@prisma-next/config

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/config@431

@prisma-next/errors

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/errors@431

@prisma-next/framework-components

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/framework-components@431

@prisma-next/operations

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/operations@431

@prisma-next/ts-render

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/ts-render@431

@prisma-next/contract-authoring

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/contract-authoring@431

@prisma-next/ids

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/ids@431

@prisma-next/psl-parser

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/psl-parser@431

@prisma-next/psl-printer

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/psl-printer@431

@prisma-next/cli

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/cli@431

@prisma-next/emitter

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/emitter@431

@prisma-next/migration-tools

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/migration-tools@431

prisma-next

npm i https://pkg.pr.new/prisma/prisma-next@431

@prisma-next/vite-plugin-contract-emit

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/vite-plugin-contract-emit@431

@prisma-next/mongo-codec

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-codec@431

@prisma-next/mongo-contract

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-contract@431

@prisma-next/mongo-value

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-value@431

@prisma-next/mongo-contract-psl

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-contract-psl@431

@prisma-next/mongo-contract-ts

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-contract-ts@431

@prisma-next/mongo-emitter

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-emitter@431

@prisma-next/mongo-schema-ir

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-schema-ir@431

@prisma-next/mongo-query-ast

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-query-ast@431

@prisma-next/mongo-orm

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-orm@431

@prisma-next/mongo-query-builder

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-query-builder@431

@prisma-next/mongo-lowering

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-lowering@431

@prisma-next/mongo-wire

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-wire@431

@prisma-next/sql-contract

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-contract@431

@prisma-next/sql-errors

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-errors@431

@prisma-next/sql-operations

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-operations@431

@prisma-next/sql-schema-ir

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-schema-ir@431

@prisma-next/sql-contract-psl

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-contract-psl@431

@prisma-next/sql-contract-ts

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-contract-ts@431

@prisma-next/sql-contract-emitter

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-contract-emitter@431

@prisma-next/sql-lane-query-builder

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-lane-query-builder@431

@prisma-next/sql-relational-core

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-relational-core@431

@prisma-next/sql-builder

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-builder@431

@prisma-next/target-postgres

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/target-postgres@431

@prisma-next/target-sqlite

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/target-sqlite@431

@prisma-next/adapter-postgres

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/adapter-postgres@431

@prisma-next/adapter-sqlite

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/adapter-sqlite@431

@prisma-next/driver-postgres

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/driver-postgres@431

@prisma-next/driver-sqlite

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/driver-sqlite@431

commit: 354c31a