stream-error-envelope-audit 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 1.0.0 - 2026-10-27
+
+- Add bounded normalization for direct, `error`, and `data.error` envelopes.
+- Add conservative retry evidence classification and unsafe-replay diagnostics.
+- Ship ESM, CommonJS, TypeScript declarations, tests, and a runnable example.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,3 @@
+# Code of Conduct
+
+Be respectful, constructive, and specific. Harassment, discrimination, threats, doxxing, and abusive conduct are not accepted. Maintainers may remove harmful content or participation. Report sensitive conduct concerns privately.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Huzaifa Asif
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,5 @@
+# Notice
+
+Copyright (c) 2026 Huzaifa Asif.
+
+This project is original MIT-licensed code. It references public issue reports and package names for interoperability context; no third-party source code is included.

package/README.md

@@ -1,3 +1,120 @@
-# Temporary Holding Version
+# stream-error-envelope-audit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Normalize and audit decoded provider or gateway error envelopes without losing the evidence needed for a safe retry decision. The package is deterministic, bounded, zero-dependency, and ships ESM, CommonJS, and TypeScript entry points.
+
+It **does not retry requests**, parse SSE bytes, contact a provider, or promise that a retry is safe.
+
+## Why
+
+Streaming systems frequently deliver errors through several shapes: a direct error object, an `error` event, or a gateway's `data.error` wrapper. A valid provider code may be null, while status, retry delay, and partial-output state still matter. Rejecting such an envelope as malformed can hide the original failure; blindly retrying can duplicate output or side effects.
+
+The package was motivated by current public integration reports:
+
+- [Vercel AI #21360](https://github.com/vercel/ai/issues/21360) (2026-09-22): a valid Responses error with `code: null` was rejected by a schema and obscured an upstream retryable 500.
+- [Vercel AI #18303](https://github.com/vercel/ai/issues/18303) (2026-07-31): gateway streaming surfaced a validation error instead of preserving the upstream provider error context.
+- [Vercel AI #22671](https://github.com/vercel/ai/issues/22671) (2026-10-10): callers need failure-aware control over retries, including privacy-sensitive metadata decisions.
+- [Vercel AI #23762](https://github.com/vercel/ai/issues/23762) (2026-10-21): callback timing could skip an expected stream retry, demonstrating that classification and retry execution should remain observable and separate.
+
+This is an independent package and is not affiliated with Vercel or any model provider.
+
+## Install
+
+```sh
+npm install stream-error-envelope-audit
+```
+
+Node.js 20 or newer is supported.
+
+## Quick start
+
+```js
+import { createErrorEnvelopeAudit } from 'stream-error-envelope-audit';
+
+const audit = createErrorEnvelopeAudit({ maxRetryAfterMs: 30_000 });
+const result = audit.observe(
+  { type: 'error', error: { code: null, message: 'provider overloaded' } },
+  { status: 503, retryAfterMs: 1_000, partialOutput: false },
+);
+
+if (result.normalized.retryClass === 'retryable' &&
+    !result.issues.some(({ severity }) => severity === 'error') &&
+    applicationPolicyAllowsRetry(result.normalized)) {
+  scheduleRetry(result.normalized.retryAfterMs);
+}
+```
+
+CommonJS:
+
+```js
+const { createErrorEnvelopeAudit } = require('stream-error-envelope-audit');
+```
+
+## API
+
+### `createErrorEnvelopeAudit(options?)`
+
+- `maxObservations` (default `10_000`) bounds processed envelopes.
+- `maxIssues` (default `1_000`) bounds retained diagnostics.
+- `maxTextLength` (default `512`) truncates copied code, type, and message strings.
+- `maxRetryAfterMs` (default `120_000`) marks delays beyond an application budget.
+
+### `audit.observe(raw, context?)`
+
+Recognizes a direct object, `raw.error`, or `raw.data.error`. Context may contain:
+
+- `status`: HTTP-like numeric status.
+- `retryable`: explicit caller or adapter hint.
+- `retryAfterMs`: already-parsed delay in milliseconds.
+- `partialOutput`: output was exposed before the failure.
+- `sideEffectStarted`: a tool or other side effect may have begun.
+
+The immutable normalized result includes bounded `code`, `type`, and `message` strings plus `retryClass`: `retryable`, `non_retryable`, or `unknown`. The conservative built-in retryable status set is 408, 425, 429, 502, 503, and 504; an explicit boolean hint can override it. Other 5xx statuses remain unknown. Partial output or a possible side effect always reduces the class to `unknown`; the package never asserts idempotency.
+
+### `audit.normalize(raw, context?)`
+
+Normalizes without incrementing counts or retaining diagnostics. It returns `null` for a non-object envelope.
+
+### `audit.snapshot()` and `audit.finalize()`
+
+Snapshots report bounded counters only. `finalize()` seals the audit and returns retained issues. `valid` means no error-severity diagnostic occurred; warning-only metadata gaps such as a nullable code remain valid. Source payloads, headers, stack traces, and arbitrary fields are never retained.
+
+## Diagnostics
+
+- warning: `missing-code` and `missing-message`
+- error: `invalid-status`
+- `retry-after-exceeds-budget`
+- `retry-contradiction`
+- `partial-output-retry-unsafe`
+- `side-effect-retry-unsafe`
+- `invalid-envelope`, `invalid-context`, and `observation-limit`
+
+## Limitations
+
+- Classification uses status and explicit hints; it cannot know a provider's complete retry contract.
+- It does not parse `Retry-After` header strings. Parse and validate them at your HTTP boundary.
+- It does not retain response bodies or headers, deduplicate retries, calculate backoff, or execute a retry.
+- `retryable` means the envelope contains retry evidence, not that replay is safe. Idempotency, billing, privacy, partial output, and side effects remain application decisions.
+- Hostile getters are treated as missing fields; the package cannot make arbitrary proxy objects safe.
+
+## Alternatives
+
+- Provider SDK retry logic is preferable when its semantics and telemetry meet your needs.
+- [`p-retry`](https://www.npmjs.com/package/p-retry) and [`async-retry`](https://www.npmjs.com/package/async-retry) execute retry policies; this package only audits decoded evidence.
+- [`ai-stream-auditor`](https://www.npmjs.com/package/ai-stream-auditor) validates OpenAI/Anthropic event lifecycles and terminal outcomes; it does not normalize arbitrary gateway error envelopes.
+- `stream-part-lifecycle`, `stream-sequence-fence`, and `abort-settlement-audit` cover keyed parts, ordering/replay, and cancellation settlement respectively—not error-shape preservation.
+
+## Troubleshooting
+
+- `missing-code`: do not reject the event solely because code is null; use other evidence.
+- `retry-contradiction`: stop automatic retry and inspect the adapter/provider contract.
+- `partial-output-retry-unsafe`: reconcile displayed or persisted output before any replay.
+- `side-effect-retry-unsafe`: require an idempotency key or manual decision.
+- `retry-after-exceeds-budget`: fail or defer according to your latency budget.
+
+## Security and privacy
+
+Pass only already-decoded error metadata. Do not include secrets in messages or codes. See [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE) and [NOTICE.md](NOTICE.md).

package/SECURITY.md

@@ -0,0 +1,11 @@
+# Security policy
+
+## Supported version
+
+The latest released major version receives security fixes.
+
+## Reporting
+
+Report vulnerabilities privately through GitHub Security Advisories for `Huzaifa-Asif/stream-error-envelope-audit`. Do not open a public issue containing credentials, sensitive error bodies, or exploit details.
+
+The package does not make untrusted values safe for logging. It copies only bounded code/type/message fields, but callers should redact secrets before observation.

package/examples/audit-errors.mjs

@@ -0,0 +1,8 @@
+import { createErrorEnvelopeAudit } from '../src/index.mjs';
+
+const audit = createErrorEnvelopeAudit({ maxRetryAfterMs: 30_000 });
+const result = audit.observe(
+  { type: 'error', error: { code: null, message: 'provider overloaded', retryable: true } },
+  { status: 503, retryAfterMs: 1_000, partialOutput: false },
+);
+console.log(JSON.stringify({ retryClass: result.normalized.retryClass, issues: result.issues.map(({ code }) => code) }));

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "stream-error-envelope-audit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Normalize and audit provider error envelopes without losing retry evidence.",
+  "type": "module",
+  "main": "./src/index.cjs",
+  "module": "./src/index.mjs",
+  "types": "./src/index.d.ts",
+  "exports": { ".": { "types": "./src/index.d.ts", "import": "./src/index.mjs", "require": "./src/index.cjs" } },
+  "files": ["src/", "examples/", "README.md", "LICENSE", "NOTICE.md", "CHANGELOG.md", "SECURITY.md", "CODE_OF_CONDUCT.md"],
+  "scripts": {
+    "build": "node scripts/verify-package.mjs",
+    "lint": "node scripts/lint.mjs",
+    "test": "node --test --experimental-test-coverage",
+    "example": "node examples/audit-errors.mjs",
+    "check": "npm run lint && npm run build && npm test && npm run example && npm pack --dry-run --json --cache ./.npm-cache"
+  },
+  "engines": { "node": ">=20" },
+  "keywords": ["ai", "stream", "error", "retry", "audit", "diagnostics"],
+  "license": "MIT",
+  "author": "Huzaifa Asif",
+  "repository": { "type": "git", "url": "git+https://github.com/Huzaifa-Asif/stream-error-envelope-audit.git" },
+  "bugs": { "url": "https://github.com/Huzaifa-Asif/stream-error-envelope-audit/issues" },
+  "homepage": "https://github.com/Huzaifa-Asif/stream-error-envelope-audit#readme",
+  "publishConfig": { "access": "public" }
+}

package/src/index.cjs

@@ -0,0 +1,113 @@
+'use strict';
+
+function positiveInteger(value, name, fallback) {
+  if (value === undefined) return fallback;
+  if (!Number.isSafeInteger(value) || value < 1) throw new TypeError(`${name} must be a positive safe integer`);
+  return value;
+}
+
+function object(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+function own(value, key) { return object(value) && Object.prototype.hasOwnProperty.call(value, key); }
+function safeRead(value, key) { try { return own(value, key) ? value[key] : undefined; } catch { return undefined; } }
+function text(value, limit) { return typeof value === 'string' && value.length > 0 ? value.slice(0, limit) : null; }
+function number(value) { return typeof value === 'number' && Number.isFinite(value) ? value : null; }
+function httpStatus(value) { return Number.isSafeInteger(value) && value >= 100 && value <= 599 ? value : null; }
+
+function createErrorEnvelopeAudit(options = {}) {
+  if (!object(options)) throw new TypeError('options must be an object');
+  const maxObservations = positiveInteger(options.maxObservations, 'maxObservations', 10_000);
+  const maxIssues = positiveInteger(options.maxIssues, 'maxIssues', 1_000);
+  const maxTextLength = positiveInteger(options.maxTextLength, 'maxTextLength', 512);
+  const maxRetryAfterMs = positiveInteger(options.maxRetryAfterMs, 'maxRetryAfterMs', 120_000);
+  const issues = [];
+  const counts = { retryable: 0, non_retryable: 0, unknown: 0 };
+  let observations = 0;
+  let totalIssues = 0;
+  let errorIssues = 0;
+  let warningIssues = 0;
+  let droppedIssues = 0;
+  let finalized = false;
+
+  function retain(code, message, detail = {}, severity = 'error') {
+    totalIssues += 1;
+    if (severity === 'warning') warningIssues += 1; else errorIssues += 1;
+    const issue = Object.freeze({ code, severity, observation: observations, message, ...detail });
+    if (issues.length < maxIssues) issues.push(issue); else droppedIssues += 1;
+    return issue;
+  }
+
+  function findEnvelope(raw) {
+    if (!object(raw)) return null;
+    const direct = safeRead(raw, 'error');
+    if (object(direct)) return direct;
+    const data = safeRead(raw, 'data');
+    const nested = safeRead(data, 'error');
+    return object(nested) ? nested : raw;
+  }
+
+  function normalize(raw, context = {}) {
+    if (!object(context)) throw new TypeError('context must be an object');
+    const envelope = findEnvelope(raw);
+    if (!envelope) return null;
+    const contextStatus = safeRead(context, 'status');
+    const rawStatus = safeRead(raw, 'status');
+    const envelopeStatus = envelope === raw ? rawStatus : safeRead(envelope, 'status');
+    const suppliedStatus = contextStatus ?? rawStatus ?? envelopeStatus;
+    const status = httpStatus(suppliedStatus);
+    const contextRetryable = safeRead(context, 'retryable');
+    const envelopeRetryable = safeRead(envelope, 'retryable');
+    const explicitRetryable = typeof contextRetryable === 'boolean'
+      ? contextRetryable
+      : (typeof envelopeRetryable === 'boolean' ? envelopeRetryable : null);
+    const contextRetryAfter = safeRead(context, 'retryAfterMs');
+    const envelopeRetryAfter = safeRead(envelope, 'retryAfterMs');
+    const rawRetryAfter = number(contextRetryAfter) ?? number(envelopeRetryAfter);
+    const retryAfterMs = rawRetryAfter !== null && rawRetryAfter >= 0 ? rawRetryAfter : null;
+    const codeValue = safeRead(envelope, 'code');
+    const code = typeof codeValue === 'string' || typeof codeValue === 'number' ? String(codeValue).slice(0, maxTextLength) : null;
+    const type = text(safeRead(envelope, 'type'), maxTextLength);
+    const envelopeMessage = safeRead(envelope, 'message');
+    const rawMessage = envelope === raw ? envelopeMessage : safeRead(raw, 'message');
+    const message = text(envelopeMessage, maxTextLength) ?? text(rawMessage, maxTextLength);
+    const partialOutput = safeRead(context, 'partialOutput') === true;
+    const sideEffectStarted = safeRead(context, 'sideEffectStarted') === true;
+    let retryClass = 'unknown';
+    if (explicitRetryable === true || [408, 425, 429, 502, 503, 504].includes(status)) retryClass = 'retryable';
+    if (explicitRetryable === false || (status !== null && status >= 400 && status <= 499 && ![408, 425, 429].includes(status))) retryClass = 'non_retryable';
+    if (partialOutput || sideEffectStarted) retryClass = 'unknown';
+    return Object.freeze({ code, type, message, status, retryAfterMs, explicitRetryable, partialOutput, sideEffectStarted, retryClass, statusSupplied: suppliedStatus !== undefined && suppliedStatus !== null });
+  }
+
+  function snapshot() {
+    return Object.freeze({ observations, counts: Object.freeze({ ...counts }), issueCount: totalIssues, errorIssueCount: errorIssues, warningIssueCount: warningIssues, retainedIssueCount: issues.length, droppedIssues, finalized });
+  }
+
+  function observe(raw, context = {}) {
+    if (finalized) throw new Error('audit is finalized');
+    if (observations >= maxObservations) return Object.freeze({ status: 'rejected', normalized: null, issues: Object.freeze([retain('observation-limit', 'observation would exceed maxObservations', { limit: maxObservations })]), snapshot: snapshot() });
+    observations += 1;
+    let normalized;
+    try { normalized = normalize(raw, context); }
+    catch (error) { return Object.freeze({ status: 'rejected', normalized: null, issues: Object.freeze([retain('invalid-context', error.message)]), snapshot: snapshot() }); }
+    if (!normalized) return Object.freeze({ status: 'rejected', normalized: null, issues: Object.freeze([retain('invalid-envelope', 'error envelope must be a non-array object')]), snapshot: snapshot() });
+    counts[normalized.retryClass] += 1;
+    const found = [];
+    if (normalized.statusSupplied && normalized.status === null) found.push(retain('invalid-status', 'status must be an integer from 100 through 599'));
+    if (normalized.code === null) found.push(retain('missing-code', 'error code is absent or null; classification remains evidence-based', {}, 'warning'));
+    if (normalized.message === null) found.push(retain('missing-message', 'error message is absent', {}, 'warning'));
+    if (normalized.retryAfterMs !== null && normalized.retryAfterMs > maxRetryAfterMs) found.push(retain('retry-after-exceeds-budget', 'retry delay exceeds configured budget', { retryAfterMs: normalized.retryAfterMs, limit: maxRetryAfterMs }));
+    if (normalized.explicitRetryable === true && normalized.status !== null && normalized.status >= 400 && normalized.status < 500 && ![408, 425, 429].includes(normalized.status)) found.push(retain('retry-contradiction', 'explicit retryable flag conflicts with a normally terminal client status', { status: normalized.status }));
+    if (normalized.partialOutput) found.push(retain('partial-output-retry-unsafe', 'automatic retry is unsafe after partial output without application reconciliation'));
+    if (normalized.sideEffectStarted) found.push(retain('side-effect-retry-unsafe', 'automatic retry is unsafe after a side effect may have started'));
+    return Object.freeze({ status: 'accepted', normalized, issues: Object.freeze(found), snapshot: snapshot() });
+  }
+
+  function finalize() {
+    finalized = true;
+    return Object.freeze({ valid: errorIssues === 0, issues: Object.freeze([...issues]), snapshot: snapshot() });
+  }
+
+  return Object.freeze({ observe, normalize, snapshot, finalize });
+}
+
+module.exports = { createErrorEnvelopeAudit };

package/src/index.d.ts

@@ -0,0 +1,11 @@
+export type RetryClass = 'retryable' | 'non_retryable' | 'unknown';
+export interface ErrorContext { readonly status?: number; readonly retryable?: boolean; readonly retryAfterMs?: number; readonly partialOutput?: boolean; readonly sideEffectStarted?: boolean; }
+export interface NormalizedError { readonly code: string | null; readonly type: string | null; readonly message: string | null; readonly status: number | null; readonly retryAfterMs: number | null; readonly explicitRetryable: boolean | null; readonly partialOutput: boolean; readonly sideEffectStarted: boolean; readonly retryClass: RetryClass; readonly statusSupplied: boolean; }
+export interface AuditIssue { readonly code: string; readonly severity: 'warning' | 'error'; readonly observation: number; readonly message: string; readonly [key: string]: unknown; }
+export interface AuditSnapshot { readonly observations: number; readonly counts: Readonly<Record<RetryClass, number>>; readonly issueCount: number; readonly errorIssueCount: number; readonly warningIssueCount: number; readonly retainedIssueCount: number; readonly droppedIssues: number; readonly finalized: boolean; }
+export interface ObserveResult { readonly status: 'accepted' | 'rejected'; readonly normalized: NormalizedError | null; readonly issues: readonly AuditIssue[]; readonly snapshot: AuditSnapshot; }
+export interface ErrorEnvelopeAudit { observe(raw: unknown, context?: ErrorContext): ObserveResult; normalize(raw: unknown, context?: ErrorContext): NormalizedError | null; snapshot(): AuditSnapshot; finalize(): { readonly valid: boolean; readonly issues: readonly AuditIssue[]; readonly snapshot: AuditSnapshot }; }
+export interface ErrorEnvelopeAuditOptions { readonly maxObservations?: number; readonly maxIssues?: number; readonly maxTextLength?: number; readonly maxRetryAfterMs?: number; }
+export declare function createErrorEnvelopeAudit(options?: ErrorEnvelopeAuditOptions): ErrorEnvelopeAudit;
+declare const api: { createErrorEnvelopeAudit: typeof createErrorEnvelopeAudit };
+export default api;

package/src/index.mjs

@@ -0,0 +1,3 @@
+import api from './index.cjs';
+export const { createErrorEnvelopeAudit } = api;
+export default api;