@db3.ai/app 0.1.0-beta.1 → 0.1.0

package/src/ai/Ai.ts

@@ -1,4 +1,7 @@
 /// <reference path="./sdkNodeCompatibility.d.ts" preserve="true" />
+import type { GenerateEmbeddingOptions } from './contracts/AI';
+import { AIProviderAdmission, AIProviderDeferredError, AIProviderStoppedError } from './AIProviderAdmission';
+import { isQueueRetryLaterError } from '@db3.ai/app/queue';
 import OpenAI from 'openai';
 import { OpenAIProvider, type ModelProvider } from '@openai/agents';
 import { aiExecutionContext, scopedAiOptions } from './AiExecutionContext';
@@ -10,15 +13,18 @@ import { AiMessage, AI_MESSAGE_ROLE, type AiMessageRole } from './AiMessage';
 import { AiRequest, AI_REQUEST_STATUS } from './AiRequest';
 const defaultAIConfig = { model: 'gpt-4.1-mini' };
 import { estimateTokensFromText } from './Estimates.js';
-import { calculateAIImageRequestCostUSD, calculateAIRequestCostUSD } from './Models.js';
+import { calculateAIImageRequestCostUSD, calculateAIRequestCostUSD } from './modelPricing.js';
 import { AI_PROVIDER } from './contracts/AI.js';
 import { AIAllowanceExceededError, AIConfigurationError, AIRequestError } from './AIErrors.js';
+import { AIRequestTrackingError } from './AIRequestTrackingError.js';
 import { isFailoverableFailure, isFailoverableResponse } from './AIFailover.js';
 import { providerChainFromEnvironment, resolveProviderChain, simulatedProviderOutage, type AIProviderAttempt, type AIProviderAttemptFailure } from './AIProviders.js';
 import { AIRateLimitDeferredError, AIRateLimiter, embeddingsRateLimitEndpoint, imagesRateLimitEndpoint, providerResponseMetadata, responsesRateLimitEndpoint, type AIProviderResponseMetadata, type AIRateLimitLease } from './AIRateLimiter.js';
 import { isOpenAIQuotaError, openAIProviderError } from './OpenAIProviderError.js';
 import { providerReportedCostUSD } from './ProviderCosts.js';
 import { sendResponsesRequest } from './ResponsesProviderCall.js';
+import type { AIServiceTier } from './contracts/AIServiceTier';
+import { assertAIServiceTier, effectiveAIServiceTier } from './aiServiceTier';
 import type { AIAllowanceCheckInput, AIRecordIdentity, AIModels, AIConfig, AIOptions, AIProvider, AIProviderSelection, AIResponseLogOptions, EmbeddingResponsePayloadWithUsage, GenerateEmbeddingResult, GenerateImageInput, GenerateImageOptions, GenerateImageResult, GenerateStructuredInput, GenerateTextInput, GenerateTextResult, ImageResponsePayloadWithUsage, RequestLogOptions, TextResponsePayloadWithUsage, TokenUsage, TrackedEmbeddingRequest, TrackedImageRequest, TrackedRequest } from './contracts/AI.js';
 
 /**
@@ -94,6 +100,7 @@ export class Ai {
 	/** Logical ownership field used by this application. */
 	readonly scopeField: string;
 	private readonly rateLimiter: AIRateLimiter | null;
+	readonly providerAdmission: AIProviderAdmission;
 
 	/**
 	 * Create an AI service instance.
@@ -106,6 +113,8 @@ export class Ai {
 		private readonly modelConfig: AIConfig = defaultAIConfig,
 	) {
 		if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) throw new AIConfigurationError('timeoutMs must be positive.');
+		this.providerAdmission = new AIProviderAdmission({ recoveryLeaseSeconds: (options.timeoutMs ?? 60_000) / 1000 + 30, ...options.providerAdmission });
+		if ((options.providerAdmission?.recoveryLeaseSeconds ?? Infinity) * 1000 <= (options.timeoutMs ?? 60_000)) throw new AIConfigurationError('Recovery lease must exceed provider timeout.');
 		this.models = { conversation: AiConversation, request: AiRequest, message: AiMessage, ...options.models };
 		this.scopeField = options.scopeField ?? 'scope';
 		this.rateLimiter = options.rateLimiter === false
@@ -247,6 +256,8 @@ export class Ai {
 		const result = await this.generateTextResult({
 			model: input.model,
 			provider: input.provider,
+			transientFailureScope: input.transientFailureScope,
+			serviceTier: input.serviceTier,
 			instructions: input.instructions,
 			input: input.input,
 			maxOutputTokens: input.maxOutputTokens,
@@ -303,6 +314,9 @@ export class Ai {
 		const operation = options.operation ?? 'responses.create';
 		const attempts = this.resolveProviders(input.provider ?? null, input.model ?? null)
 			.filter(attempt => attempt.supportsResponsesApi);
+		const serviceTier = input.serviceTier ?? 'default';
+		for (const attempt of attempts) assertAIServiceTier(attempt.provider, serviceTier);
+		const timeoutMs = this.requestTimeoutMs(serviceTier);
 		const attemptFailures: AIProviderAttemptFailure[] = [];
 		let tracked: TrackedRequest | null = null;
 		let trackedSettled = false;
@@ -312,7 +326,7 @@ export class Ai {
 		}
 
 		for (let index = 0; index < attempts.length; index++) {
-			const attempt = attempts[index]!;
+			const attempt = { ...attempts[index]!, transientFailureScope: input.transientFailureScope };
 			const hasFallback = index < attempts.length - 1;
 			const attemptStartMs = Date.now();
 			const request = {
@@ -320,7 +334,7 @@ export class Ai {
 				instructions: input.instructions,
 				input: input.input,
 				store: false,
-				...(attempt.provider === AI_PROVIDER.openai ? { service_tier: 'default' } : {}),
+				...(attempt.provider === AI_PROVIDER.openai ? { service_tier: serviceTier } : {}),
 				...maxOutputTokensPayload(input.maxOutputTokens),
 				...extraRequest,
 			};
@@ -371,14 +385,15 @@ export class Ai {
 					baseUrl: attempt.baseUrl,
 					apiKey: attempt.apiKey,
 					request,
-					fetcher: this.fetcher(),
+					fetcher: this.providerAdmission.transport(attempt, this.fetcher(timeoutMs), timeoutMs),
 				});
 				const { payload, metadata } = result;
+				const admissionFailure = this.providerAdmission.requestFailure(attempt, null);
 
-				if (!result.ok) {
+				if (!result.ok || admissionFailure) {
 					const message = responseErrorMessage(payload) || `AI provider ${attempt.provider} request failed with HTTP ${result.status}.`;
 
-					if (hasFallback && isFailoverableResponse(result.status, payload)) {
+					if (hasFallback && (isFailoverableFailure(admissionFailure) || isFailoverableResponse(result.status, payload))) {
 						const failure = providerAttemptFailure(attempt, attemptStartMs, message, result.status, responseErrorCode(payload));
 
 						attemptFailures.push(failure);
@@ -401,9 +416,9 @@ export class Ai {
 						continue;
 					}
 
-					const deferred = isRateLimitFailure(result.status, payload)
+					const deferred = admissionFailure ?? (isRateLimitFailure(result.status, payload)
 						? rateLimitDeferredError(lease, metadata, message)
-						: null;
+						: null);
 
 					if (tracked) {
 						attachProviderAttempts(tracked.aiRequest, attemptFailures);
@@ -416,7 +431,7 @@ export class Ai {
 
 					if (deferred) throw deferred;
 
-					throw new AIRequestError(message, responseErrorCode(payload));
+					throw new AIRequestError(message, responseErrorCode(payload), { status: result.status, requestId: metadata.providerRequestId });
 				}
 
 				const text = payload?.status !== undefined && payload.status !== 'completed' ? null : responseOutputText(payload);
@@ -497,15 +512,15 @@ export class Ai {
 					continue;
 				}
 
-				if (tracked && !trackedSettled && !(error instanceof AIRequestError) && !(error instanceof AIRateLimitDeferredError)) {
+				if (tracked && !trackedSettled && (!(error instanceof AIRequestError) || error instanceof AIProviderStoppedError) && !(error instanceof AIRateLimitDeferredError)) {
 					attachProviderAttempts(tracked.aiRequest, attemptFailures);
 					await this.failTrackedRequest(
 						tracked,
-						null,
+						providerAdmissionResponse(error),
 						errorMessage(error),
-						emptyProviderResponseMetadata(),
+						providerAdmissionMetadata(error),
 						failedLease,
-						providerStarted,
+						providerAdmissionStarted(error, providerStarted),
 					);
 				}
 
@@ -558,7 +573,7 @@ export class Ai {
 		input: TrackedProviderAttemptFailure,
 	): Promise<void> {
 		const usage = tokenUsage(input.response);
-		const modelCostUSD = textRequestCostUSD(input.attempt.provider, input.attempt.model, usage, input.response);
+		const modelCostUSD = textRequestCostUSD(input.attempt.provider, input.attempt.model, usage, input.response, input.request.service_tier);
 
 		const aiRequest = new this.models.request({
 			conversation: tracked.conversation,
@@ -693,7 +708,7 @@ export class Ai {
 		lease: AIRateLimitLease | null = null,
 	): Promise<void> {
 		const usage = tokenUsage(response);
-		const costUSD = textRequestCostUSD(tracked.provider, tracked.model, usage, response);
+		const costUSD = textRequestCostUSD(tracked.provider, tracked.model, usage, response, asRecord(tracked.aiRequest.request)?.service_tier);
 
 		tracked.aiRequest.assign({
 			response,
@@ -738,7 +753,7 @@ export class Ai {
 		const usage = tokenUsage(response);
 		const costUSD = !providerStarted
 			? 0
-			: textRequestCostUSD(tracked.provider, tracked.model, usage, response);
+			: textRequestCostUSD(tracked.provider, tracked.model, usage, response, asRecord(tracked.aiRequest.request)?.service_tier);
 
 		tracked.aiRequest.assign({
 			response,
@@ -890,7 +905,12 @@ export class Ai {
 			request,
 			metadata: options.metadata ?? null,
 			startedAt: new Date(),
-		}).save();
+		});
+		try {
+			await aiRequest.save();
+		} catch (error) {
+			throw new AIRequestTrackingError(error);
+		}
 
 		return {
 			aiRequest,
@@ -907,12 +927,13 @@ export class Ai {
 		response: EmbeddingResponsePayloadWithUsage | null,
 		metadata: AIProviderResponseMetadata = emptyProviderResponseMetadata(),
 		lease: AIRateLimitLease | null = null,
+		retainResult = false,
 	): Promise<void> {
 		const usage = embeddingTokenUsage(response);
 		const costUSD = calculateAIRequestCostUSD(tracked.model, usage);
 
 		tracked.aiRequest.assign({
-			response: compactEmbeddingResponse(response),
+			response: retainResult ? response : compactEmbeddingResponse(response),
 			providerRequestId: metadata.providerRequestId,
 			providerProcessingMs: metadata.providerProcessingMs,
 			rateLimitBucket: lease?.bucket ?? null,
@@ -1153,9 +1174,11 @@ export class Ai {
 	 * @param initialLease - Optional preflight reservation consumed by the first request.
 	 * @returns SDK provider using the service's transport and rate-limit lifecycle.
 	 */
-	createAgentProvider(attempt: AIProviderAttempt, initialLease: AIRateLimitLease | null = null): ModelProvider {
+	createAgentProvider(attempt: AIProviderAttempt, initialLease: AIRateLimitLease | null = null, serviceTier: AIServiceTier = 'default'): ModelProvider {
+		assertAIServiceTier(attempt.provider, serviceTier);
+		const timeoutMs = this.requestTimeoutMs(serviceTier);
 		return new OpenAIProvider({
-			openAIClient: new OpenAI({ apiKey: attempt.apiKey, baseURL: attempt.baseUrl, fetch: this.agentFetcher(attempt, initialLease), timeout: this.options.timeoutMs ?? 60_000, maxRetries: 0 }),
+			openAIClient: new OpenAI({ apiKey: attempt.apiKey, baseURL: attempt.baseUrl, fetch: this.agentFetcher(attempt, initialLease, timeoutMs), timeout: timeoutMs, maxRetries: 0 }),
 			useResponses: attempt.supportsResponsesApi,
 		});
 	}
@@ -1172,9 +1195,9 @@ export class Ai {
 	 * @param initialLease - First-request reservation, if acquired by the agent.
 	 * @returns Transport that maintains provider capacity and request diagnostics.
 	 */
-	private agentFetcher(attempt: AIProviderAttempt, initialLease: AIRateLimitLease | null): typeof fetch {
+	private agentFetcher(attempt: AIProviderAttempt, initialLease: AIRateLimitLease | null, timeoutMs: number): typeof fetch {
 		let pendingLease = initialLease;
-		const transport = this.fetcher();
+		const transport = this.providerAdmission.transport(attempt, this.fetcher(timeoutMs), timeoutMs);
 		return async (url, init) => {
 			const aiRequest = aiExecutionContext.getStore()?.aiRequest ?? null;
 			const lease = pendingLease ?? await this.acquireRateLimit({
@@ -1213,12 +1236,22 @@ export class Ai {
 		};
 	}
 
+	/** Resolves the account connection for OpenAI-only images and embeddings. */
+	private openAIAdmissionAttempt(model: string): AIProviderAttempt {
+		return { provider: AI_PROVIDER.openai, model, apiKey: this.requireApiKey(), baseUrl: this.baseUrl(), supportsResponsesApi: true };
+	}
+
+	/** Resolves a tier-aware request timeout while respecting an explicit service override. */
+	private requestTimeoutMs(serviceTier: AIServiceTier): number {
+		return this.options.timeoutMs ?? (serviceTier === 'flex' ? 900_000 : 60_000);
+	}
+
 	/**
 	 * Fetch implementation used by provider calls.
 	 */
-	private fetcher(): typeof fetch {
+	private fetcher(timeoutMs = this.options.timeoutMs ?? 60_000): typeof fetch {
 		const transport = this.options.fetch || fetch;
-		return (url, init) => transport(url, { ...init, signal: init?.signal ?? AbortSignal.timeout(this.options.timeoutMs ?? 60_000) });
+		return (url, init) => transport(url, { ...init, signal: init?.signal ?? AbortSignal.timeout(timeoutMs) });
 	}
 
 	/**
@@ -1325,6 +1358,7 @@ export class Ai {
 		const model = input.model || this.config('ImageGeneration', 'gpt-image-2');
 		const prompt = input.prompt.replace(/\s+/g, ' ').trim();
 		const outputFormat = input.outputFormat ?? 'png';
+		const admissionAttempt = this.openAIAdmissionAttempt(model);
 		const operation = options.operation ?? 'images.generate';
 		const request = {
 			model,
@@ -1378,7 +1412,7 @@ export class Ai {
 			await this.attachRateLimitRequest(lease, tracked?.aiRequest ?? null);
 
 			providerStarted = true;
-			const response = await this.fetcher()(this.imagesUrl(), {
+			const response = await this.providerAdmission.transport(admissionAttempt, this.fetcher())(this.imagesUrl(), {
 				method: 'POST',
 				headers: {
 					authorization: `Bearer ${apiKey}`,
@@ -1389,11 +1423,12 @@ export class Ai {
 			const metadata = providerResponseMetadata(response.headers);
 			const payload = await response.json().catch(() => null) as ImageResponsePayloadWithUsage | null;
 
-			if (!response.ok) {
+			const admissionFailure = this.providerAdmission.requestFailure(admissionAttempt, null);
+			if (!response.ok || admissionFailure) {
 				const message = responseErrorMessage(payload as TextResponsePayloadWithUsage | null) || `OpenAI image request failed with HTTP ${response.status}.`;
-				const deferred = isRateLimitFailure(response.status, payload)
+				const deferred = admissionFailure ?? (isRateLimitFailure(response.status, payload)
 					? rateLimitDeferredError(lease, metadata, message)
-					: null;
+					: null);
 
 				if (tracked) {
 					await this.failTrackedImageRequest(tracked, payload, message, metadata, lease);
@@ -1405,7 +1440,7 @@ export class Ai {
 
 				if (deferred) throw deferred;
 
-				throw new AIRequestError(message, responseErrorCode(payload));
+				throw new AIRequestError(message, responseErrorCode(payload), { status: response.status, requestId: metadata.providerRequestId });
 			}
 
 			const b64Json = imageBase64(payload);
@@ -1477,18 +1512,18 @@ export class Ai {
 
 			await this.releaseRateLimit(lease);
 
-			if (tracked && !trackedSettled && !(error instanceof AIRequestError) && !(error instanceof AIRateLimitDeferredError)) {
+			if (tracked && !trackedSettled) {
 				await this.failTrackedImageRequest(
 					tracked,
-					null,
+					providerAdmissionResponse(error),
 					errorMessage(error),
-					emptyProviderResponseMetadata(),
+					providerAdmissionMetadata(error),
 					lease,
-					providerStarted,
+					providerAdmissionStarted(error, providerStarted),
 				);
 			}
 
-			if (error instanceof AIRateLimitDeferredError) throw error;
+			if (isQueueRetryLaterError(error) || error instanceof AIProviderStoppedError) throw error;
 			if (error instanceof AIAllowanceExceededError) throw error;
 			if (error instanceof AIRequestError) throw error;
 
@@ -1507,7 +1542,7 @@ export class Ai {
 	async generateEmbedding(
 		input: string,
 		model: string = 'text-embedding-3-small',
-		options: RequestLogOptions = {},
+		options: GenerateEmbeddingOptions = {},
 	): Promise<GenerateEmbeddingResult> {
 		options = scopedAiOptions(options, this.scopeField);
 		assertIndependentUsage(options);
@@ -1515,6 +1550,7 @@ export class Ai {
 		if (!input) throw new Error('Input is required for embedding generation.');
 
 		const apiKey = this.requireApiKey();
+		const admissionAttempt = this.openAIAdmissionAttempt(model);
 		const operation = options.operation ?? 'embeddings.create';
 		const request = {
 			model,
@@ -1556,7 +1592,7 @@ export class Ai {
 
 			await this.attachRateLimitRequest(lease, tracked?.aiRequest ?? null);
 			providerStarted = true;
-			const response = await this.fetcher()(this.embeddingsUrl(), {
+			const response = await this.providerAdmission.transport(admissionAttempt, this.fetcher())(this.embeddingsUrl(), {
 				method: 'POST',
 				headers: {
 					authorization: `Bearer ${apiKey}`,
@@ -1567,11 +1603,12 @@ export class Ai {
 			const metadata = providerResponseMetadata(response.headers);
 			const payload = await response.json().catch(() => null) as EmbeddingResponsePayloadWithUsage | null;
 
-			if (!response.ok) {
+			const admissionFailure = this.providerAdmission.requestFailure(admissionAttempt, null);
+			if (!response.ok || admissionFailure) {
 				const message = responseErrorMessage(payload as TextResponsePayloadWithUsage | null) || `OpenAI embedding request failed with HTTP ${response.status}.`;
-				const deferred = isRateLimitFailure(response.status, payload)
+				const deferred = admissionFailure ?? (isRateLimitFailure(response.status, payload)
 					? rateLimitDeferredError(lease, metadata, message)
-					: null;
+					: null);
 
 				if (tracked) {
 					await this.failTrackedEmbeddingRequest(tracked, payload, message, metadata, lease);
@@ -1583,7 +1620,7 @@ export class Ai {
 
 				if (deferred) throw deferred;
 
-				throw new AIRequestError(message, responseErrorCode(payload));
+				throw new AIRequestError(message, responseErrorCode(payload), { status: response.status, requestId: metadata.providerRequestId });
 			}
 
 			const vector = payload?.data?.[0]?.embedding;
@@ -1602,7 +1639,7 @@ export class Ai {
 			}
 
 			if (tracked) {
-				await this.completeTrackedEmbeddingRequest(tracked, payload, metadata, lease);
+				await this.completeTrackedEmbeddingRequest(tracked, payload, metadata, lease, options.retainResult === true);
 				trackedSettled = true;
 			}
 
@@ -1625,18 +1662,19 @@ export class Ai {
 
 			await this.releaseRateLimit(lease);
 
-			if (tracked && !trackedSettled && !(error instanceof AIRequestError) && !(error instanceof AIRateLimitDeferredError)) {
+			if (tracked && !trackedSettled && (!(error instanceof AIRequestError) || error instanceof AIProviderStoppedError) && !(error instanceof AIRateLimitDeferredError)) {
 				await this.failTrackedEmbeddingRequest(
 					tracked,
-					null,
+					providerAdmissionResponse(error),
 					errorMessage(error),
-					emptyProviderResponseMetadata(),
+					providerAdmissionMetadata(error),
 					lease,
-					providerStarted,
+					providerAdmissionStarted(error, providerStarted),
 				);
 			}
 
-			if (error instanceof AIRateLimitDeferredError) throw error;
+			if (isQueueRetryLaterError(error) || error instanceof AIProviderStoppedError) throw error;
+			if (error instanceof AIRequestTrackingError) throw error;
 			if (error instanceof AIRequestError) throw error;
 
 			throw new AIRequestError(errorMessage(error));
@@ -1839,7 +1877,9 @@ function attachProviderAttempts(aiRequest: AiRequest, failures: AIProviderAttemp
  * @returns True when the provider indicates a rate-limit failure.
  */
 function isRateLimitFailure(status: number, payload: unknown): boolean {
-	if (isOpenAIQuotaError(payload)) return false;
+	// Some credit-exhaustion responses omit a stable code. Do not turn their
+	// explicit billing failure into an unlimited queue capacity deferral.
+	if (isOpenAIQuotaError(payload) || /\b(?:you have )?no credits remaining\b/i.test(openAIProviderError(payload).message)) return false;
 
 	const code = responseErrorCode(payload);
 
@@ -1930,9 +1970,10 @@ function textRequestCostUSD(
 	model: string,
 	usage: TokenUsage,
 	payload: TextResponsePayloadWithUsage | null,
+	requestedTier?: unknown,
 ): number | null {
 	if (provider === AI_PROVIDER.openai) {
-		return calculateAIRequestCostUSD(model, usage);
+		return calculateAIRequestCostUSD(typeof payload?.model === 'string' ? payload.model : model, { ...usage, serviceTier: effectiveAIServiceTier(payload?.service_tier, requestedTier) });
 	}
 
 	return providerReportedCostUSD(provider, payload);
@@ -2174,3 +2215,18 @@ function scopeRecordId(scope: AIRecordIdentity | string | null): string | null {
 
 	return id === null || id === undefined ? null : String(id);
 }
+
+/** Retains safe provider diagnostics for admission failures in the existing audit trail. */
+function providerAdmissionResponse(error: unknown): null | { error: { code: string | null; message: string } } {
+	return error instanceof AIProviderStoppedError ? { error: { code: error.providerCode ?? error.code, message: error.message } } : null;
+}
+
+/** Distinguishes actual provider rejection from blocked-before-provider work. */
+function providerAdmissionStarted(error: unknown, fallback: boolean): boolean {
+	return error instanceof AIProviderStoppedError || error instanceof AIProviderDeferredError ? error.providerStarted : fallback;
+}
+
+/** Keeps provider support identifiers without duplicating response bodies. */
+function providerAdmissionMetadata(error: unknown): AIProviderResponseMetadata {
+	return { ...emptyProviderResponseMetadata(), providerRequestId: error instanceof AIProviderStoppedError ? error.requestId : null };
+}

package/src/ai/OpenAIProviderError.ts

@@ -58,7 +58,7 @@ export function openAIProviderError(value: unknown): OpenAIProviderErrorDetails
 export function isOpenAIQuotaError(value: unknown): boolean {
 	const code = openAIProviderError(value).code;
 
-	return code !== null && OPENAI_QUOTA_ERROR_CODES.has(code);
+	return (code !== null && OPENAI_QUOTA_ERROR_CODES.has(code)) || /\b(?:you have )?no credits remaining\b/i.test(openAIProviderError(value).message);
 }
 
 /**

package/src/ai/ProviderSseObserver.ts

@@ -0,0 +1,89 @@
+/** Maximum retained decoded characters for one SSE line or joined data event. */
+const MAX_EVENT_CHARACTERS = 1_048_576;
+
+/**
+ * Observes SSE framing without rewriting transport bytes or dispatching SDK events.
+ * CR, LF and CRLF terminate lines; blank lines dispatch joined data fields. An
+ * oversized event is discarded until its blank boundary, allowing later errors
+ * to remain observable. Malformed or unfinished input permanently disqualifies
+ * this observer from asserting recovery, even if a later event completes.
+ */
+export class ProviderSseObserver {
+	#line = '';
+	#lineNonempty = false;
+	#skipLf = false;
+	#data: string[] = [];
+	#dataLength = 0;
+	#eventOpen = false;
+	#discardEvent = false;
+	#valid = true;
+
+	/** Receives complete joined data fields; the caller owns provider semantics. */
+	constructor(readonly onData: (data: string) => Promise<void>) {}
+
+	/** Records malformed JSON/encoding while continuing to observe later events. */
+	invalidate(): void { this.#valid = false; }
+
+	/** True only when every observed event is valid and ends at a blank boundary. */
+	get complete(): boolean { return this.#valid && !this.#lineNonempty && !this.#eventOpen && !this.#discardEvent; }
+
+	/** Consumes one decoded fragment; CRLF may be split between calls. */
+	async push(text: string): Promise<void> {
+		let start = 0;
+		for (let index = 0; index < text.length; index++) {
+			const character = text[index];
+			if (this.#skipLf) {
+				this.#skipLf = false;
+				if (character === '\n') { start = index + 1; continue; }
+			}
+			if (character !== '\r' && character !== '\n') continue;
+			this.#append(text.slice(start, index));
+			await this.#finishLine();
+			this.#skipLf = character === '\r';
+			start = index + 1;
+		}
+		this.#append(text.slice(start));
+	}
+
+	/** Bounds retained line and event storage before adding another fragment. */
+	#append(fragment: string): void {
+		if (!fragment.length) return;
+		this.#lineNonempty = true;
+		if (this.#discardEvent) return;
+		if (this.#line.length + this.#dataLength + fragment.length > MAX_EVENT_CHARACTERS) {
+			this.invalidate();
+			this.#discardEvent = true;
+			this.#line = '';
+			this.#data = [];
+			this.#dataLength = 0;
+		} else this.#line += fragment;
+	}
+
+	/** Dispatches only complete events, retaining SSE's joined-data semantics. */
+	async #finishLine(): Promise<void> {
+		const line = this.#line;
+		const nonempty = this.#lineNonempty;
+		this.#line = '';
+		this.#lineNonempty = false;
+		if (!nonempty) {
+			const data = this.#discardEvent || !this.#data.length ? null : this.#data.join('\n');
+			this.#data = [];
+			this.#dataLength = 0;
+			this.#eventOpen = false;
+			this.#discardEvent = false;
+			if (data !== null) await this.onData(data);
+			return;
+		}
+		if (this.#discardEvent || line.startsWith(':')) return;
+		this.#eventOpen = true;
+		if (line !== 'data' && !line.startsWith('data:')) return;
+		const data = line === 'data' ? '' : line.slice(line[5] === ' ' ? 6 : 5);
+		this.#dataLength += data.length + 1;
+		if (this.#dataLength > MAX_EVENT_CHARACTERS) {
+			this.invalidate();
+			this.#discardEvent = true;
+			this.#data = [];
+			this.#dataLength = 0;
+		} else this.#data.push(data);
+	}
+}