@prisma-next/sql-runtime 0.11.0 → 0.12.0

package/README.md

@@ -27,7 +27,7 @@ Execute SQL query Plans with deterministic verification, guardrails, and feedbac
 - **Codec Encoding/Decoding**: Encode parameters and decode rows using SQL codec registries
 - **Codec Validation**: Validate that codec registries contain all required codecs
 - **SQL Family Adapter**: Implement `RuntimeFamilyAdapter` for SQL contracts (defined in `runtime-spi.ts`)
-- **Marker Verification**: Parse contract-marker rows from the database (`marker.ts`) and gate execution on hash equality
+- **Marker Verification**: Read contract-marker rows from the database (`marker.ts`) on first execute and compare storage/profile hashes against the contract. On the first `execute()` call, any drift — hash mismatch, absent row, or missing marker table — is reported via a single `warn`-level structured log line through the runtime's `Log` interface (payload includes `code`, `scope`, `expected`, `actual`, `message`) and the query proceeds normally. The check runs once per runtime lifetime; subsequent queries skip the marker read. Pass `verifyMarker: false` to skip the marker read entirely.
 - **Telemetry Fingerprinting**: Compute SQL fingerprints for telemetry events (`fingerprint.ts`)
 - **Raw-SQL Guardrails**: Heuristic safety checks for raw SQL plans (`guardrails/raw.ts`)
 - **`beforeCompile` Chain**: AST-rewrite middleware chain run pre-lowering (`middleware/before-compile-chain.ts`)
@@ -72,7 +72,6 @@ const runtime = createRuntime({
   stackInstance,
   context,
   driver,
-  verify: { mode: 'onFirstUse', requireMarker: false },
   middleware: [budgets()],
 });
 
@@ -81,6 +80,18 @@ for await (const row of runtime.execute(plan)) {
 }
 ```
 
+Use `verifyMarker: false` to skip the marker read entirely — e.g. during a known-skewed deploy window where contract drift is expected and tolerated.
+
+```typescript
+const runtime = createRuntime({
+  stackInstance,
+  context,
+  driver,
+  verifyMarker: false,
+  middleware: [budgets()],
+});
+```
+
 ## Exports
 
 ### Runtime
@@ -88,7 +99,7 @@ for await (const row of runtime.execute(plan)) {
 - `createRuntime` - Create a SQL runtime instance
 - `Runtime` - Runtime instance type
 - `CreateRuntimeOptions` - Options for `createRuntime`
-- `RuntimeVerifyOptions` - Verification mode configuration
+- `VerifyMarkerOption` - Marker-verification option (`'onFirstUse'` default; `false` to skip)
 - `RuntimeTelemetryEvent`, `TelemetryOutcome` - Telemetry event types
 
 ### Context

package/dist/{exports-BsRNNJxU.mjs → exports-CXYd2w6k.mjs}

@@ -2,10 +2,11 @@ import { AsyncIterableResult, RuntimeCore, checkAborted, checkMiddlewareCompatib
 import { type } from "arktype";
 import { PreparedParamRef, collectOrderedParamRefs, isQueryAst } from "@prisma-next/sql-relational-core/ast";
 import { ifDefined } from "@prisma-next/utils/defined";
-import { checkContractComponentRequirements } from "@prisma-next/framework-components/components";
+import { checkContractComponentRequirements, mergeCapabilityMatrices } from "@prisma-next/framework-components/components";
 import { createExecutionStack } from "@prisma-next/framework-components/execution";
 import { canonicalizeJson } from "@prisma-next/framework-components/utils";
 import { isPostgresEnumStorageEntry } from "@prisma-next/sql-contract/types";
+import { blindCast } from "@prisma-next/utils/casts";
 import { createSqlOperationRegistry } from "@prisma-next/sql-operations";
 import { buildCodecDescriptorRegistry } from "@prisma-next/sql-relational-core/codec-descriptor-registry";
 import { APP_SPACE_ID } from "@prisma-next/framework-components/control";
@@ -436,6 +437,9 @@ function validateTypeParams$1(paramsSchema, ref) {
 }
 //#endregion
 //#region src/sql-context.ts
+function documentScopedCodecTypes(contract) {
+	return blindCast(contract.storage.types);
+}
 function createSqlExecutionStack(options) {
 	return createExecutionStack({
 		target: options.target,
@@ -539,12 +543,11 @@ function collectTypeRefSites(storage) {
 	}
 	return sites;
 }
-function initializeTypeHelpers(storage, codecDescriptors) {
+function initializeTypeHelpers(storage, documentTypes, codecDescriptors) {
 	const helpers = {};
-	const storageTypes = storage.types;
-	if (!storageTypes) return helpers;
+	if (!documentTypes) return helpers;
 	const typeRefSites = collectTypeRefSites(storage);
-	for (const [typeName, typeInstance] of Object.entries(storageTypes)) {
+	for (const [typeName, typeInstance] of Object.entries(documentTypes)) {
 		const enumView = readEnumViewIfApplicable(typeInstance);
 		const codecId = enumView ? enumView.codecId : typeInstance.codecId;
 		const typeParams = enumView ? enumView.typeParams : typeInstance.typeParams;
@@ -640,7 +643,7 @@ function buildContractCodecRegistry(contract, codecDescriptors) {
 	const usedAtByKey = /* @__PURE__ */ new Map();
 	const nameByKey = /* @__PURE__ */ new Map();
 	const typeRefSites = collectTypeRefSites(contract.storage);
-	for (const [typeName, typeInstance] of Object.entries(contract.storage.types ?? {})) {
+	for (const [typeName, typeInstance] of Object.entries(documentScopedCodecTypes(contract) ?? {})) {
 		const enumView = readEnumViewIfApplicable(typeInstance);
 		const key = refKeyOf(enumView ? {
 			codecId: enumView.codecId,
@@ -774,8 +777,19 @@ function scopedCache(stability, rowCache, queryCache) {
 	}
 }
 function createExecutionContext(options) {
-	const { contract, stack } = options;
-	assertExecutionStackContractRequirements(contract, stack);
+	const { stack, driver } = options;
+	assertExecutionStackContractRequirements(options.contract, stack);
+	const capabilityContributors = [
+		stack.target,
+		stack.adapter,
+		...driver ? [driver] : [],
+		...stack.extensionPacks
+	];
+	const mergedCapabilities = mergeCapabilityMatrices(options.contract.capabilities, capabilityContributors);
+	const contract = {
+		...options.contract,
+		capabilities: mergedCapabilities
+	};
 	const contributors = [
 		stack.target,
 		stack.adapter,
@@ -792,7 +806,7 @@ function createExecutionContext(options) {
 	const mutationDefaultGeneratorRegistry = collectMutationDefaultGenerators(contributors);
 	assertMutationDefaultGeneratorsAvailable(contract, mutationDefaultGeneratorRegistry);
 	if (parameterizedCodecDescriptors.size > 0) validateColumnTypeParams(contract.storage, parameterizedCodecDescriptors);
-	const types = initializeTypeHelpers(contract.storage, parameterizedCodecDescriptors);
+	const types = initializeTypeHelpers(contract.storage, documentScopedCodecTypes(contract), parameterizedCodecDescriptors);
 	return {
 		contract,
 		contractCodecs: buildContractCodecRegistry(contract, codecDescriptors),
@@ -990,12 +1004,9 @@ function wrapIncludeAggregateFailure(error, alias, wireValue) {
 function decodeIncludeAggregate(alias, wireValue) {
 	if (wireValue === null || wireValue === void 0) return [];
 	try {
-		let parsed;
-		if (typeof wireValue === "string") parsed = JSON.parse(wireValue);
-		else if (Array.isArray(wireValue)) parsed = wireValue;
-		else parsed = JSON.parse(String(wireValue));
-		if (!Array.isArray(parsed)) throw new Error(`Expected array for include alias '${alias}', got ${typeof parsed}`);
-		return parsed;
+		if (typeof wireValue === "string") return JSON.parse(wireValue);
+		if (typeof wireValue === "object") return wireValue;
+		return JSON.parse(String(wireValue));
 	} catch (error) {
 		wrapIncludeAggregateFailure(error, alias, wireValue);
 	}
@@ -1324,14 +1335,13 @@ var SqlRuntimeImpl = class extends RuntimeCore {
 	contractCodecs;
 	codecDescriptors;
 	sqlCtx;
-	verify;
+	verifyMarkerOption;
+	verifyMarkerPromise;
 	#preparedStatementHandles = /* @__PURE__ */ new WeakMap();
 	codecRegistryValidated;
-	verified;
-	startupVerified;
 	_telemetry;
 	constructor(options) {
-		const { context, adapter, driver, verify, middleware, mode, log } = options;
+		const { context, adapter, driver, verifyMarker, middleware, mode, log } = options;
 		if (middleware) for (const mw of middleware) checkMiddlewareCompatibility(mw, "sql", context.contract.target);
 		const sqlCtx = {
 			contract: context.contract,
@@ -1339,7 +1349,8 @@ var SqlRuntimeImpl = class extends RuntimeCore {
 			now: () => Date.now(),
 			log: log ?? noopLog,
 			contentHash: (exec) => computeSqlContentHash(exec),
-			scope: "runtime"
+			scope: "runtime",
+			planExecutionId: ""
 		};
 		super({
 			middleware: middleware ?? [],
@@ -1352,15 +1363,10 @@ var SqlRuntimeImpl = class extends RuntimeCore {
 		this.contractCodecs = context.contractCodecs;
 		this.codecDescriptors = context.codecDescriptors;
 		this.sqlCtx = sqlCtx;
-		this.verify = verify;
+		this.verifyMarkerOption = verifyMarker ?? "onFirstUse";
 		this.codecRegistryValidated = false;
-		this.verified = verify.mode === "startup" ? false : verify.mode === "always";
-		this.startupVerified = false;
+		this.verifyMarkerPromise = this.verifyMarkerOption === false ? Promise.resolve() : null;
 		this._telemetry = null;
-		if (verify.mode === "startup") {
-			validateCodecRegistryCompleteness(this.codecDescriptors, context.contract);
-			this.codecRegistryValidated = true;
-		}
 	}
 	/**
 	* Lower a `SqlQueryPlan` (AST + meta) into a `SqlExecutionPlan`
@@ -1442,12 +1448,11 @@ var SqlRuntimeImpl = class extends RuntimeCore {
 	async *streamRows(exec, decodeContext, driverCall, codecCtx, execMiddlewareCtx) {
 		this.familyAdapter.validatePlan(exec, this.contract);
 		this._telemetry = null;
-		if (!this.startupVerified && this.verify.mode === "startup") await this.verifyMarker();
-		if (!this.verified && this.verify.mode === "onFirstUse") await this.verifyMarker();
+		if (this.verifyMarkerPromise === null) this.verifyMarkerPromise = this.verifyMarker();
+		await this.verifyMarkerPromise;
 		const startedAt = Date.now();
 		let outcome = null;
 		try {
-			if (this.verify.mode === "always") await this.verifyMarker();
 			const iterator = runWithMiddleware(exec, this.middleware, execMiddlewareCtx, driverCall)[Symbol.asyncIterator]();
 			try {
 				while (true) {
@@ -1476,7 +1481,8 @@ var SqlRuntimeImpl = class extends RuntimeCore {
 		const execMiddlewareCtx = {
 			...self.ctx,
 			...ifDefined("signal", signal),
-			...scope !== "runtime" ? { scope } : {}
+			...scope !== "runtime" ? { scope } : {},
+			planExecutionId: crypto.randomUUID()
 		};
 		const generator = async function* () {
 			checkAborted(codecCtx, "stream");
@@ -1543,7 +1549,8 @@ var SqlRuntimeImpl = class extends RuntimeCore {
 		const execMiddlewareCtx = {
 			...self.ctx,
 			...ifDefined("signal", signal),
-			...scope !== "runtime" ? { scope } : {}
+			...scope !== "runtime" ? { scope } : {},
+			planExecutionId: crypto.randomUUID()
 		};
 		const generator = async function* () {
 			checkAborted(codecCtx, "stream");
@@ -1643,24 +1650,35 @@ var SqlRuntimeImpl = class extends RuntimeCore {
 	}
 	async verifyMarker() {
 		const readResult = await this.familyAdapter.markerReader.readMarker(this.driver);
+		const expectedStorageHash = this.contract.storage.storageHash;
+		const expectedProfileHash = this.contract.profileHash ?? null;
+		const expected = {
+			storageHash: expectedStorageHash,
+			profileHash: expectedProfileHash
+		};
 		if (readResult.kind !== "present") {
-			if (this.verify.requireMarker) throw runtimeError("CONTRACT.MARKER_MISSING", "Contract marker not found in database");
-			this.verified = true;
+			this.sqlCtx.log.warn({
+				code: "CONTRACT.MARKER_MISSING",
+				scope: "marker-verification",
+				expected,
+				actual: null,
+				message: "Contract marker not found in database"
+			});
 			return;
 		}
 		const marker = readResult.record;
-		const contract = this.contract;
-		if (marker.storageHash !== contract.storage.storageHash) throw runtimeError("CONTRACT.MARKER_MISMATCH", "Database storage hash does not match contract", {
-			expected: contract.storage.storageHash,
-			actual: marker.storageHash
-		});
-		const expectedProfile = contract.profileHash ?? null;
-		if (expectedProfile !== null && marker.profileHash !== expectedProfile) throw runtimeError("CONTRACT.MARKER_MISMATCH", "Database profile hash does not match contract", {
-			expectedProfile,
-			actualProfile: marker.profileHash
+		const storageHashMatch = marker.storageHash === expectedStorageHash;
+		const profileHashMatch = expectedProfileHash === null || marker.profileHash === expectedProfileHash;
+		if (!storageHashMatch || !profileHashMatch) this.sqlCtx.log.warn({
+			code: "CONTRACT.MARKER_MISMATCH",
+			scope: "marker-verification",
+			expected,
+			actual: {
+				storageHash: marker.storageHash,
+				profileHash: marker.profileHash ?? null
+			},
+			message: "Contract marker hash does not match runtime contract"
 		});
-		this.verified = true;
-		this.startupVerified = true;
 	}
 	recordTelemetry(plan, outcome, durationMs) {
 		const contract = this.contract;
@@ -1748,12 +1766,12 @@ async function withTransaction(runtime, fn) {
 	}
 }
 function createRuntime(options) {
-	const { stackInstance, context, driver, verify, middleware, mode, log } = options;
+	const { stackInstance, context, driver, verifyMarker, middleware, mode, log } = options;
 	return new SqlRuntimeImpl({
 		context,
 		adapter: stackInstance.adapter,
 		driver,
-		verify,
+		...ifDefined("verifyMarker", verifyMarker),
 		...ifDefined("middleware", middleware),
 		...ifDefined("mode", mode),
 		...ifDefined("log", log)
@@ -1762,4 +1780,4 @@ function createRuntime(options) {
 //#endregion
 export { ensureTableStatement as a, createExecutionContext as c, budgets as d, parseContractMarkerRow as f, validateContractCodecMappings as g, validateCodecRegistryCompleteness as h, ensureSchemaStatement as i, createSqlExecutionStack as l, extractCodecIds as m, withTransaction as n, readContractMarker as o, lowerSqlPlan as p, APP_SPACE_ID as r, writeContractMarker as s, createRuntime as t, lints as u };
 
-//# sourceMappingURL=exports-BsRNNJxU.mjs.map
+//# sourceMappingURL=exports-CXYd2w6k.mjs.map