ai-stream-auditor 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project uses [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [1.0.2] - 2026-10-10
+
+### Added
+
+- Ship the runnable OpenAI Responses lifecycle example in the npm tarball.
+- Execute the example as part of the aggregate package check.
+- Document how lifecycle auditing composes with async-iterator deadlines.
+
+## [1.0.1] - 2026-10-06
+
+### Fixed
+
+- Preserve structural error state independently of bounded diagnostic storage, so warning saturation cannot turn malformed streams into successful reports.
+- Reject OpenAI content-part starts, deltas, and stops without an open parent output item.
+
 ## [1.0.0] - 2026-10-03
 
 ### Added

package/README.md

@@ -142,6 +142,7 @@ This function deliberately accepts only synchronous iterables. Use `createStream
 
 - `response.created` lifecycle start
 - Output-item and content-part added/done pairing
+- Content-part starts, deltas, and stops require their output item to remain open
 - Delta events targeting an open item or content part
 - Non-increasing `sequence_number` values when present
 - `response.completed`, `response.failed`, `response.incomplete`, `response.cancelled`, and `error` terminals
@@ -215,7 +216,9 @@ Provider protocols can add event types. The report remains successful if no stru
 
 ### Too many diagnostics
 
-`droppedDiagnostics` counts records beyond `maxDiagnostics`. The first bounded set is retained. Increase the limit only when your logging and memory budgets permit.
+`droppedDiagnostics` counts records beyond `maxDiagnostics`. The first bounded set is retained. Errors still affect the final outcome even when their diagnostic records are dropped. Increase the limit only when your logging and memory budgets permit.
+
+Content parts are checked against their parent output item's lifecycle, as defined in the [OpenAI streaming events reference](https://developers.openai.com/api/reference/resources/responses/streaming-events). Orphan content parts and content activity after the output item completes make a nominal completion invalid.
 
 ## Security and privacy
 
@@ -223,6 +226,17 @@ The auditor does not retain raw event payloads or generated text by default beca
 
 See [SECURITY.md](SECURITY.md) for vulnerability reporting.
 
+## Runnable example and related tool
+
+[`examples/audit-openai.mjs`](examples/audit-openai.mjs) feeds a minimal valid
+OpenAI Responses lifecycle through the auditor. It is executed by
+`npm run check` and ships in the npm tarball.
+
+Use [`async-iterator-watchdog`](https://www.npmjs.com/package/async-iterator-watchdog)
+when you also need active first-progress, idle, or total deadlines around the
+source iterator. The watchdog enforces time; this package validates protocol
+lifecycle and outcome.
+
 ## Development
 
 ```sh

package/examples/audit-openai.mjs

@@ -0,0 +1,14 @@
+import { createStreamAuditor } from 'ai-stream-auditor';
+
+const auditor = createStreamAuditor('openai-responses');
+
+// Feed decoded SDK events as they arrive. The auditor does not parse SSE bytes.
+for (const event of [
+  { type: 'response.created', sequence_number: 0 },
+  { type: 'response.completed', sequence_number: 1, response: { status: 'completed' } },
+]) {
+  auditor.push(event);
+}
+
+const report = auditor.finish({ cause: 'iterator_end' });
+console.log(report);

package/package.json

@@ -1,26 +1,55 @@
 {
   "name": "ai-stream-auditor",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Audit decoded OpenAI Responses and Anthropic Messages event lifecycles for silent or malformed stream endings.",
-  "keywords": ["ai", "streaming", "openai", "anthropic", "llm", "diagnostics", "testing"],
+  "keywords": [
+    "ai",
+    "streaming",
+    "openai",
+    "anthropic",
+    "llm",
+    "diagnostics",
+    "testing"
+  ],
   "license": "MIT",
   "author": "Huzaifa Asif",
-  "repository": { "type": "git", "url": "git+https://github.com/Huzaifa-Asif/ai-stream-auditor.git" },
-  "bugs": { "url": "https://github.com/Huzaifa-Asif/ai-stream-auditor/issues" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Huzaifa-Asif/ai-stream-auditor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Huzaifa-Asif/ai-stream-auditor/issues"
+  },
   "homepage": "https://github.com/Huzaifa-Asif/ai-stream-auditor#readme",
   "type": "module",
   "main": "./src/index.cjs",
   "module": "./src/index.js",
   "types": "./src/index.d.ts",
-  "exports": { ".": { "types": "./src/index.d.ts", "import": "./src/index.js", "require": "./src/index.cjs" } },
-  "files": ["src", "README.md", "LICENSE", "CHANGELOG.md"],
-  "engines": { "node": ">=18" },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "require": "./src/index.cjs"
+    }
+  },
+  "files": [
+    "src",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
   "sideEffects": false,
   "scripts": {
     "lint": "node scripts/lint.mjs",
     "test": "node --test",
     "test:coverage": "node --experimental-test-coverage --test",
-    "check": "npm run lint && npm run test:coverage && npm pack --dry-run"
+    "check": "npm run lint && npm run test:coverage && node examples/audit-openai.mjs && npm pack --dry-run"
   },
-  "publishConfig": { "access": "public" }
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/src/index.cjs

@@ -57,6 +57,7 @@ class StreamAuditor {
     this.eventCount = 0;
     this.counts = new Map();
     this.diagnostics = [];
+    this.hasErrors = false;
     this.droppedDiagnostics = 0;
     this.terminal = undefined;
     this.started = false;
@@ -69,6 +70,7 @@ class StreamAuditor {
   }
 
   _diagnostic(severity, code, index, type, details) {
+    if (severity === 'error') this.hasErrors = true;
     if (this.diagnostics.length >= this.limits.maxDiagnostics) {
       this.droppedDiagnostics += 1;
       return;
@@ -95,6 +97,13 @@ class StreamAuditor {
     }
   }
 
+  _requireOpenItem(event, index, type) {
+    const parent = `item:${event.output_index}`;
+    if (!this.openUnits.has(parent)) {
+      this._diagnostic('error', this.doneUnits.has(parent) ? 'content_after_item_done' : 'content_without_item', index, type, { parent });
+    }
+  }
+
   _done(key, index, type) {
     if (!this.openUnits.has(key)) {
       this._diagnostic('error', this.doneUnits.has(key) ? 'duplicate_done' : 'done_without_start', index, type, { unit: key });
@@ -167,14 +176,17 @@ class StreamAuditor {
       return;
     }
     if (type === 'response.content_part.added') {
+      this._requireOpenItem(event, index, type);
       this._open(`content:${event.output_index}:${event.content_index}`, index, type);
       return;
     }
     if (type === 'response.content_part.done') {
+      this._requireOpenItem(event, index, type);
       this._done(`content:${event.output_index}:${event.content_index}`, index, type);
       return;
     }
     if (/\.delta$/.test(type)) {
+      if (Number.isSafeInteger(event.content_index)) this._requireOpenItem(event, index, type);
       const key = Number.isSafeInteger(event.content_index)
         ? `content:${event.output_index}:${event.content_index}`
         : `item:${event.output_index}`;
@@ -245,9 +257,8 @@ class StreamAuditor {
     if (!this.started && !this.terminal && this.eventCount > 0) this._diagnostic('error', 'missing_start', this.eventCount);
     if (!this.terminal && !this.boundExceeded) this._diagnostic('error', 'missing_terminal', this.eventCount);
 
-    const hasErrors = this.diagnostics.some(({ severity }) => severity === 'error');
     let outcome;
-    if (this.boundExceeded || hasErrors && this.terminal && this.terminal.kind === 'completed') outcome = 'invalid';
+    if (this.boundExceeded || this.hasErrors && this.terminal && this.terminal.kind === 'completed') outcome = 'invalid';
     else if (this.terminal) outcome = this.terminal.kind === 'completed' && this.dialect === 'anthropic-messages' && this.stopReason === 'tool_use'
       ? 'tool_use'
       : this.terminal.kind === 'completed' && this.dialect === 'anthropic-messages' && this.stopReason === 'pause_turn'