@nexart/ai-execution 0.1.0

package/README.md

@@ -0,0 +1,353 @@
+# @nexart/ai-execution v0.1.0
+
+Tamper-evident records and Certified Execution Records (CER) for AI operations.
+
+## What This Does
+
+This package creates integrity records for AI executions. Every time you call an AI model, it captures:
+
+- What you sent (input + prompt)
+- What you got back (output)
+- The exact parameters used (temperature, model, etc.)
+- SHA-256 hashes of everything for tamper detection
+
+These records can be verified later to prove the execution happened as recorded.
+
+**Important:** This does NOT promise that an AI model will produce the same output twice. LLMs are not deterministic. This package provides **integrity and auditability** — proof that a specific input produced a specific output at a specific time with specific parameters.
+
+## Installation
+
+```bash
+npm install @nexart/ai-execution
+```
+
+## Quick Start
+
+### Create a Snapshot Manually
+
+```typescript
+import { createSnapshot, verifySnapshot, sealCer, verifyCer } from '@nexart/ai-execution';
+
+// Create a snapshot of an AI execution
+const snapshot = createSnapshot({
+  executionId: 'exec-001',
+  provider: 'openai',
+  model: 'gpt-4o',
+  modelVersion: '2026-01-01',
+  prompt: 'You are a helpful assistant.',
+  input: 'What is 2+2?',
+  parameters: {
+    temperature: 0.7,
+    maxTokens: 1024,
+    topP: null,
+    seed: null,
+  },
+  output: 'The answer is 4.',
+});
+
+// Verify the snapshot hashes are correct
+const result = verifySnapshot(snapshot);
+console.log(result.ok); // true
+
+// Seal into a Certified Execution Record
+const bundle = sealCer(snapshot);
+console.log(bundle.certificateHash); // "sha256:..."
+
+// Verify the entire bundle
+const cerResult = verifyCer(bundle);
+console.log(cerResult.ok); // true
+```
+
+### With JSON Input/Output
+
+```typescript
+const snapshot = createSnapshot({
+  executionId: 'exec-002',
+  provider: 'openai',
+  model: 'gpt-4o',
+  prompt: 'Extract entities',
+  input: { text: 'John lives in Paris', lang: 'en' },
+  parameters: {
+    temperature: 0,
+    maxTokens: 512,
+    topP: null,
+    seed: 42,
+  },
+  output: { entities: ['John', 'Paris'], count: 2 },
+});
+```
+
+### OpenAI Provider (Optional)
+
+Convenience adapter only; the core value of this package is the snapshot + hashing format.
+The OpenAI adapter wraps a single `chat/completions` call and returns a sealed CER bundle.
+**Provider determinism is not guaranteed** — identical inputs may produce different outputs across calls.
+
+If you have an OpenAI API key, the package includes a convenience adapter:
+
+```typescript
+import { runOpenAIChatExecution } from '@nexart/ai-execution/providers/openai';
+
+const result = await runOpenAIChatExecution({
+  prompt: 'You are a helpful assistant.',
+  input: 'What is the capital of France?',
+  model: 'gpt-4o',
+  parameters: {
+    temperature: 0.7,
+    maxTokens: 256,
+  },
+});
+
+console.log(result.output);           // "The capital of France is Paris."
+console.log(result.snapshot.inputHash);  // "sha256:..."
+console.log(result.bundle.certificateHash); // "sha256:..."
+```
+
+Requires `OPENAI_API_KEY` environment variable or `apiKey` parameter.
+
+## Snapshot Format (ai.execution.v1)
+
+### Required vs Optional Fields
+
+| Field | Required | Type | Notes |
+|---|---|---|---|
+| `executionId` | **Yes** | `string` | Caller-supplied unique ID |
+| `provider` | **Yes** | `string` | e.g. `"openai"`, `"anthropic"` |
+| `model` | **Yes** | `string` | e.g. `"gpt-4o"` |
+| `prompt` | **Yes** | `string` | System prompt |
+| `input` | **Yes** | `string \| object` | User input (text or structured) |
+| `output` | **Yes** | `string \| object` | Model output (text or structured) |
+| `parameters.temperature` | **Yes** | `number` | Must be finite |
+| `parameters.maxTokens` | **Yes** | `number` | Must be finite |
+| `timestamp` | Optional | `string` | ISO 8601; defaults to `new Date().toISOString()` |
+| `modelVersion` | Optional | `string \| null` | Defaults to `null` |
+| `parameters.topP` | Optional | `number \| null` | Defaults to `null` |
+| `parameters.seed` | Optional | `number \| null` | Defaults to `null` |
+| `sdkVersion` | Optional | `string \| null` | Defaults to package version (`"0.1.0"`) |
+| `appId` | Optional | `string \| null` | Defaults to `null` |
+
+The following fields are **auto-generated** by `createSnapshot` and must not be set manually:
+
+| Field | Value |
+|---|---|
+| `type` | `"ai.execution.v1"` |
+| `protocolVersion` | `"1.2.0"` |
+| `executionSurface` | `"ai"` |
+| `inputHash` | SHA-256 of input |
+| `outputHash` | SHA-256 of output |
+
+### Example Snapshot
+
+```json
+{
+  "type": "ai.execution.v1",
+  "protocolVersion": "1.2.0",
+  "executionSurface": "ai",
+  "executionId": "exec-001",
+  "timestamp": "2026-02-12T00:00:00.000Z",
+  "provider": "openai",
+  "model": "gpt-4o",
+  "modelVersion": "2026-01-01",
+  "prompt": "You are a helpful assistant.",
+  "input": "What is 2+2?",
+  "inputHash": "sha256:...",
+  "parameters": {
+    "temperature": 0.7,
+    "maxTokens": 1024,
+    "topP": null,
+    "seed": null
+  },
+  "output": "The answer is 4.",
+  "outputHash": "sha256:...",
+  "sdkVersion": "0.1.0",
+  "appId": null
+}
+```
+
+## CER Bundle Format
+
+```json
+{
+  "bundleType": "cer.ai.execution.v1",
+  "certificateHash": "sha256:...",
+  "createdAt": "2026-02-12T00:00:00.000Z",
+  "version": "0.1",
+  "snapshot": { ... },
+  "meta": {
+    "source": "my-app",
+    "tags": ["production"]
+  }
+}
+```
+
+### Certificate Hash Computation
+
+The `certificateHash` is SHA-256 of the UTF-8 bytes of the canonical JSON of **exactly these four fields**:
+
+```
+{ bundleType, version, createdAt, snapshot }
+```
+
+- `meta` is **excluded** from the certificate hash. It is an informational envelope field that does not affect integrity verification.
+- Key-ordering rules apply **recursively** — every nested object within `snapshot` is also sorted lexicographically by key.
+- The bytes being hashed are the UTF-8 encoding of the canonical JSON string (no BOM, no trailing newline).
+
+## Hashing Rules
+
+- **String values**: SHA-256 of UTF-8 bytes of the raw string
+- **Object/Array values**: SHA-256 of UTF-8 bytes of canonical JSON (sorted keys, no whitespace, stable array order)
+- All hashes use the format `sha256:<hex>` (lowercase hex, 64 characters)
+
+## Canonical JSON Constraints
+
+Canonical JSON is a deterministic subset of JSON. The following rules apply:
+
+1. **Object keys** are sorted lexicographically (Unicode codepoint order) at every nesting level.
+2. **No whitespace** — no spaces, tabs, or newlines between tokens.
+3. **Array order is preserved** — arrays are never re-sorted.
+4. **`null`** is valid and serialized as `null`.
+5. **Numbers** must be finite. `NaN`, `Infinity`, and `-Infinity` are **rejected** (throw).
+6. **`undefined`** values in object properties are **omitted** (the key is dropped).
+7. **`BigInt`**, **functions**, and **`Symbol`** are **not valid** JSON types and are **rejected** (throw).
+8. Strings are JSON-escaped (e.g. `"` → `\"`).
+
+These constraints ensure that the same logical value always produces the same byte sequence, which is essential for hash stability across implementations and languages.
+
+## Interoperability (Test Vectors)
+
+Cross-language implementations **must** match the test vectors exactly to be considered compatible. Vectors are committed as JSON fixtures at:
+
+```
+packages/ai-execution/fixtures/vectors/
+```
+
+### Vector 001
+
+**Input snapshot** (`vector-001.snapshot.json`):
+
+```json
+{
+  "type": "ai.execution.v1",
+  "protocolVersion": "1.2.0",
+  "executionSurface": "ai",
+  "executionId": "vec-001",
+  "timestamp": "2026-02-12T00:00:00.000Z",
+  "provider": "openai",
+  "model": "gpt-4o",
+  "modelVersion": "2026-01-01",
+  "prompt": "You are a helpful assistant.",
+  "input": "What is 2+2?",
+  "inputHash": "sha256:52cb6b5e4a038af1756708f98afb718a08c75b87b2f03dbee4dd9c8139c15c5e",
+  "parameters": {
+    "temperature": 0.7,
+    "maxTokens": 1024,
+    "topP": null,
+    "seed": null
+  },
+  "output": "The answer is 4.",
+  "outputHash": "sha256:ae758477f843049bd252ceb5498aa33f190326589ee92cbe5a1ab563f54bc05b",
+  "sdkVersion": "0.1.0",
+  "appId": "vector-test"
+}
+```
+
+**Expected hashes** (`vector-001.expected.json`):
+
+| Hash | Value |
+|---|---|
+| `inputHash` | `sha256:52cb6b5e4a038af1756708f98afb718a08c75b87b2f03dbee4dd9c8139c15c5e` |
+| `outputHash` | `sha256:ae758477f843049bd252ceb5498aa33f190326589ee92cbe5a1ab563f54bc05b` |
+| `certificateHash` | `sha256:86275d60d088483eefaf0bd31d79629b11342315816f3a1da26980e4a05352f4` |
+
+The `certificateHash` is computed with `cerCreatedAt: "2026-02-12T00:00:00.000Z"`.
+
+**Canonicalization rules for verification:**
+1. Object keys sorted lexicographically at every level.
+2. No whitespace between tokens.
+3. Arrays preserve insertion order.
+4. Hashes are SHA-256 of the UTF-8 bytes of the resulting string.
+
+To verify compatibility, a cross-language implementation should:
+1. Load `vector-001.snapshot.json`.
+2. Recompute `inputHash` from `snapshot.input` and assert it matches `expected.inputHash`.
+3. Recompute `outputHash` from `snapshot.output` and assert it matches `expected.outputHash`.
+4. Construct a CER payload `{ bundleType: "cer.ai.execution.v1", version: "0.1", createdAt: "2026-02-12T00:00:00.000Z", snapshot }`, canonicalize it, hash it, and assert it matches `expected.certificateHash`.
+
+## Threat Model
+
+This package provides **integrity and auditability** for AI execution records. It is an auditing tool, not a security boundary.
+
+### What it prevents
+
+- **Output tampering** — any modification to the recorded output invalidates the `outputHash` and `certificateHash`.
+- **Parameter laundering** — changing temperature, model, seed, or other parameters after the fact is detectable because they are included in the certificate hash.
+- **Silent record edits** — any modification to a sealed CER bundle is detectable via `verifyCer()`.
+
+### What it does NOT prevent
+
+- **Provider lying** — if the AI provider returns fabricated output, this package faithfully records it. The record proves what the provider returned, not that the provider was honest.
+- **Model drift** — models change over time. The same input may produce different output with the same model name on different dates. `modelVersion` helps track this but cannot prevent it.
+- **Correctness of the answer** — this package records what was said, not whether it was right.
+
+## Verification Best Practice
+
+**Recommended flow:**
+
+1. Call `createSnapshot(...)` immediately after receiving the AI response.
+2. Call `sealCer(snapshot)` to produce the CER bundle.
+3. Call `verifyCer(bundle)` **before** storing or transmitting the bundle — this catches any in-memory corruption.
+4. Store the full bundle as an audit artifact. Treat it as immutable.
+5. On retrieval, call `verifyCer(bundle)` again to confirm integrity.
+
+```typescript
+const snapshot = createSnapshot({ ... });
+const bundle = sealCer(snapshot);
+
+const check = verifyCer(bundle);
+if (!check.ok) {
+  throw new Error(`CER integrity failure: ${check.errors.join('; ')}`);
+}
+
+await store(bundle); // persist as audit artifact
+```
+
+## Privacy & Data Handling
+
+Snapshots include **raw prompt, input, and output by default**. This means:
+
+- If the input contains PII, medical data, or other sensitive information, the snapshot will contain it verbatim.
+- If the output contains sensitive content, it will be stored in full.
+
+**Recommendations:**
+
+- For sensitive workloads, consider redacting input/output before calling `createSnapshot()`, then verify the redacted versions.
+- A hash-only mode (where only hashes are stored, not raw content) is **not implemented in v0.1.0**. It is planned for a future release.
+- Treat CER bundles with the same access controls as the underlying data they contain.
+
+## API Reference
+
+| Function | Description |
+|----------|-------------|
+| `createSnapshot(params)` | Create an AI execution snapshot with computed hashes |
+| `verifySnapshot(snapshot)` | Verify snapshot hashes and structure |
+| `sealCer(snapshot, options?)` | Seal a snapshot into a CER bundle |
+| `verifyCer(bundle)` | Verify a CER bundle (snapshot + certificate hash) |
+| `computeInputHash(input)` | Compute hash for input (string or object) |
+| `computeOutputHash(output)` | Compute hash for output (string or object) |
+| `toCanonicalJson(value)` | Deterministic JSON serialization |
+| `sha256Hex(data)` | Raw SHA-256 hex digest |
+| `hashUtf8(value)` | Hash a UTF-8 string |
+| `hashCanonicalJson(value)` | Hash canonical JSON of a value |
+
+## How to Publish
+
+```bash
+cd packages/ai-execution
+npm run build
+npm run test
+npm publish --access public
+```
+
+## License
+
+MIT

package/dist/__tests__/fixtures.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fixtures.test.d.ts.map

package/dist/__tests__/fixtures.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/fixtures.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/fixtures.test.js

@@ -0,0 +1,37 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { verifySnapshot } from '../snapshot.js';
+import { sealCer, verifyCer } from '../cer.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const fixturesDir = join(__dirname, '..', '..', 'fixtures', 'vectors');
+function loadJson(filename) {
+    return JSON.parse(readFileSync(join(fixturesDir, filename), 'utf-8'));
+}
+describe('fixture: vector-001', () => {
+    const snapshot = loadJson('vector-001.snapshot.json');
+    const expected = loadJson('vector-001.expected.json');
+    it('snapshot inputHash matches expected', () => {
+        assert.equal(snapshot.inputHash, expected.inputHash);
+    });
+    it('snapshot outputHash matches expected', () => {
+        assert.equal(snapshot.outputHash, expected.outputHash);
+    });
+    it('snapshot passes verification', () => {
+        const result = verifySnapshot(snapshot);
+        assert.equal(result.ok, true, `verification errors: ${result.errors.join('; ')}`);
+    });
+    it('CER certificateHash matches expected', () => {
+        const bundle = sealCer(snapshot, { createdAt: expected.cerCreatedAt });
+        assert.equal(bundle.certificateHash, expected.certificateHash);
+    });
+    it('CER bundle passes verification', () => {
+        const bundle = sealCer(snapshot, { createdAt: expected.cerCreatedAt });
+        const result = verifyCer(bundle);
+        assert.equal(result.ok, true, `verification errors: ${result.errors.join('; ')}`);
+    });
+});
+//# sourceMappingURL=fixtures.test.js.map

package/dist/__tests__/fixtures.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.test.js","sourceRoot":"","sources":["../../src/__tests__/fixtures.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAG/C,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AACtC,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;AAEvE,SAAS,QAAQ,CAAC,QAAgB;IAChC,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;AACxE,CAAC;AAED,QAAQ,CAAC,qBAAqB,EAAE,GAAG,EAAE;IACnC,MAAM,QAAQ,GAAG,QAAQ,CAAC,0BAA0B,CAA0B,CAAC;IAC/E,MAAM,QAAQ,GAAG,QAAQ,CAAC,0BAA0B,CAKnD,CAAC;IAEF,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;QAC7C,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IACvD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACtC,MAAM,MAAM,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;QACxC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,wBAAwB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpF,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC;QACvE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,eAAe,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;IACjE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gCAAgC,EAAE,GAAG,EAAE;QACxC,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC;QACvE,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;QACjC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,wBAAwB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpF,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/vectors.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=vectors.test.d.ts.map

package/dist/__tests__/vectors.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vectors.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/vectors.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/vectors.test.js

@@ -0,0 +1,261 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { toCanonicalJson } from '../canonicalJson.js';
+import { sha256Hex, hashUtf8, hashCanonicalJson, computeInputHash, computeOutputHash } from '../hash.js';
+import { createSnapshot, verifySnapshot } from '../snapshot.js';
+import { sealCer, verifyCer } from '../cer.js';
+const FIXED_TIMESTAMP = '2026-02-12T00:00:00.000Z';
+const FIXED_EXECUTION_ID = 'test-exec-001';
+describe('canonicalJson', () => {
+    it('sorts object keys lexicographically', () => {
+        const result = toCanonicalJson({ z: 1, a: 2, m: 3 });
+        assert.equal(result, '{"a":2,"m":3,"z":1}');
+    });
+    it('does not sort arrays', () => {
+        const result = toCanonicalJson([3, 1, 2]);
+        assert.equal(result, '[3,1,2]');
+    });
+    it('handles nested objects', () => {
+        const result = toCanonicalJson({ b: { d: 1, c: 2 }, a: 3 });
+        assert.equal(result, '{"a":3,"b":{"c":2,"d":1}}');
+    });
+    it('handles null', () => {
+        assert.equal(toCanonicalJson(null), 'null');
+    });
+    it('handles strings with escapes', () => {
+        assert.equal(toCanonicalJson('hello "world"'), '"hello \\"world\\""');
+    });
+    it('rejects NaN', () => {
+        assert.throws(() => toCanonicalJson(NaN), /Non-finite/);
+    });
+    it('rejects Infinity', () => {
+        assert.throws(() => toCanonicalJson(Infinity), /Non-finite/);
+    });
+    it('omits undefined values in objects', () => {
+        const result = toCanonicalJson({ a: 1, b: undefined, c: 3 });
+        assert.equal(result, '{"a":1,"c":3}');
+    });
+    it('produces no whitespace', () => {
+        const result = toCanonicalJson({ key: 'value', arr: [1, 2] });
+        assert.ok(!result.includes(' '));
+        assert.ok(!result.includes('\n'));
+    });
+});
+describe('hashing', () => {
+    it('sha256Hex produces correct hex for empty string', () => {
+        const result = sha256Hex('');
+        assert.equal(result, 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855');
+    });
+    it('hashUtf8 prefixes with sha256:', () => {
+        const result = hashUtf8('hello');
+        assert.ok(result.startsWith('sha256:'));
+        assert.equal(result, 'sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824');
+    });
+    it('hashCanonicalJson is stable for same object', () => {
+        const obj = { b: 2, a: 1 };
+        const h1 = hashCanonicalJson(obj);
+        const h2 = hashCanonicalJson({ a: 1, b: 2 });
+        assert.equal(h1, h2);
+    });
+    it('computeInputHash for string uses hashUtf8', () => {
+        const result = computeInputHash('test input');
+        assert.equal(result, hashUtf8('test input'));
+    });
+    it('computeInputHash for object uses hashCanonicalJson', () => {
+        const obj = { role: 'user', content: 'hello' };
+        const result = computeInputHash(obj);
+        assert.equal(result, hashCanonicalJson(obj));
+    });
+});
+describe('snapshot', () => {
+    const baseParams = {
+        executionId: FIXED_EXECUTION_ID,
+        timestamp: FIXED_TIMESTAMP,
+        provider: 'openai',
+        model: 'gpt-4o',
+        modelVersion: '2026-01-01',
+        prompt: 'You are a helpful assistant.',
+        input: 'What is 2+2?',
+        parameters: {
+            temperature: 0.7,
+            maxTokens: 1024,
+            topP: null,
+            seed: null,
+        },
+        output: 'The answer is 4.',
+        sdkVersion: '0.1.0',
+        appId: null,
+    };
+    it('creates snapshot with correct type fields', () => {
+        const snap = createSnapshot(baseParams);
+        assert.equal(snap.type, 'ai.execution.v1');
+        assert.equal(snap.protocolVersion, '1.2.0');
+        assert.equal(snap.executionSurface, 'ai');
+        assert.equal(snap.executionId, FIXED_EXECUTION_ID);
+        assert.equal(snap.timestamp, FIXED_TIMESTAMP);
+    });
+    it('computes correct inputHash for text input', () => {
+        const snap = createSnapshot(baseParams);
+        const expected = computeInputHash('What is 2+2?');
+        assert.equal(snap.inputHash, expected);
+    });
+    it('computes correct outputHash for text output', () => {
+        const snap = createSnapshot(baseParams);
+        const expected = computeOutputHash('The answer is 4.');
+        assert.equal(snap.outputHash, expected);
+    });
+    it('computes correct hashes for JSON input/output', () => {
+        const jsonParams = {
+            ...baseParams,
+            input: { messages: [{ role: 'user', content: 'hello' }] },
+            output: { result: 'world', confidence: 0.95 },
+        };
+        const snap = createSnapshot(jsonParams);
+        const expectedInput = computeInputHash(jsonParams.input);
+        const expectedOutput = computeOutputHash(jsonParams.output);
+        assert.equal(snap.inputHash, expectedInput);
+        assert.equal(snap.outputHash, expectedOutput);
+    });
+    it('verifySnapshot passes for valid snapshot', () => {
+        const snap = createSnapshot(baseParams);
+        const result = verifySnapshot(snap);
+        assert.equal(result.ok, true);
+        assert.equal(result.errors.length, 0);
+    });
+    it('verifySnapshot fails on tampered output', () => {
+        const snap = createSnapshot(baseParams);
+        snap.output = 'Tampered output!';
+        const result = verifySnapshot(snap);
+        assert.equal(result.ok, false);
+        assert.ok(result.errors.some(e => e.includes('outputHash mismatch')));
+    });
+    it('rejects non-finite temperature', () => {
+        assert.throws(() => createSnapshot({ ...baseParams, parameters: { ...baseParams.parameters, temperature: NaN } }), /temperature/);
+    });
+});
+describe('cer', () => {
+    const baseParams = {
+        executionId: FIXED_EXECUTION_ID,
+        timestamp: FIXED_TIMESTAMP,
+        provider: 'openai',
+        model: 'gpt-4o',
+        modelVersion: '2026-01-01',
+        prompt: 'You are a helpful assistant.',
+        input: 'What is 2+2?',
+        parameters: {
+            temperature: 0.7,
+            maxTokens: 1024,
+            topP: null,
+            seed: null,
+        },
+        output: 'The answer is 4.',
+        sdkVersion: '0.1.0',
+        appId: null,
+    };
+    it('seals a CER bundle with correct fields', () => {
+        const snap = createSnapshot(baseParams);
+        const bundle = sealCer(snap, { createdAt: FIXED_TIMESTAMP });
+        assert.equal(bundle.bundleType, 'cer.ai.execution.v1');
+        assert.equal(bundle.version, '0.1');
+        assert.equal(bundle.createdAt, FIXED_TIMESTAMP);
+        assert.ok(bundle.certificateHash.startsWith('sha256:'));
+        assert.deepStrictEqual(bundle.snapshot, snap);
+    });
+    it('certificateHash is stable for same snapshot + createdAt', () => {
+        const snap = createSnapshot(baseParams);
+        const b1 = sealCer(snap, { createdAt: FIXED_TIMESTAMP });
+        const b2 = sealCer(snap, { createdAt: FIXED_TIMESTAMP });
+        assert.equal(b1.certificateHash, b2.certificateHash);
+    });
+    it('certificateHash changes when createdAt changes', () => {
+        const snap = createSnapshot(baseParams);
+        const b1 = sealCer(snap, { createdAt: FIXED_TIMESTAMP });
+        const b2 = sealCer(snap, { createdAt: '2026-02-13T00:00:00.000Z' });
+        assert.notEqual(b1.certificateHash, b2.certificateHash);
+    });
+    it('verifyCer passes for valid bundle', () => {
+        const snap = createSnapshot(baseParams);
+        const bundle = sealCer(snap, { createdAt: FIXED_TIMESTAMP });
+        const result = verifyCer(bundle);
+        assert.equal(result.ok, true);
+        assert.equal(result.errors.length, 0);
+    });
+    it('verifyCer fails on tampered certificateHash', () => {
+        const snap = createSnapshot(baseParams);
+        const bundle = sealCer(snap, { createdAt: FIXED_TIMESTAMP });
+        bundle.certificateHash = 'sha256:0000000000000000000000000000000000000000000000000000000000000000';
+        const result = verifyCer(bundle);
+        assert.equal(result.ok, false);
+        assert.ok(result.errors.some(e => e.includes('certificateHash mismatch')));
+    });
+    it('verifyCer fails on tampered snapshot output', () => {
+        const snap = createSnapshot(baseParams);
+        const bundle = sealCer(snap, { createdAt: FIXED_TIMESTAMP });
+        bundle.snapshot.output = 'Tampered!';
+        const result = verifyCer(bundle);
+        assert.equal(result.ok, false);
+        assert.ok(result.errors.some(e => e.includes('outputHash mismatch')));
+    });
+    it('includes meta when provided', () => {
+        const snap = createSnapshot(baseParams);
+        const bundle = sealCer(snap, {
+            createdAt: FIXED_TIMESTAMP,
+            meta: { source: 'test', tags: ['unit-test'] },
+        });
+        assert.deepStrictEqual(bundle.meta, { source: 'test', tags: ['unit-test'] });
+    });
+});
+describe('deterministic test vectors', () => {
+    it('text input/text output vector', () => {
+        const snap = createSnapshot({
+            executionId: 'vec-text-001',
+            timestamp: '2026-01-01T00:00:00.000Z',
+            provider: 'openai',
+            model: 'gpt-4o',
+            modelVersion: null,
+            prompt: 'system prompt',
+            input: 'hello world',
+            parameters: { temperature: 0, maxTokens: 100, topP: null, seed: null },
+            output: 'goodbye world',
+            sdkVersion: '0.1.0',
+            appId: null,
+        });
+        assert.equal(snap.inputHash, 'sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9');
+        assert.equal(snap.outputHash, 'sha256:9150e02727e29ca8522c29ad4aa5a8343c21ccf909b40f73c41bf478df7e6fc3');
+        const bundle = sealCer(snap, { createdAt: '2026-01-01T00:00:00.000Z' });
+        assert.ok(bundle.certificateHash.startsWith('sha256:'));
+        const v1 = verifySnapshot(snap);
+        assert.equal(v1.ok, true);
+        const v2 = verifyCer(bundle);
+        assert.equal(v2.ok, true);
+    });
+    it('JSON input/JSON output vector', () => {
+        const snap = createSnapshot({
+            executionId: 'vec-json-001',
+            timestamp: '2026-01-01T00:00:00.000Z',
+            provider: 'openai',
+            model: 'gpt-4o',
+            modelVersion: '2026-01-01',
+            prompt: 'structured',
+            input: { query: 'test', context: [1, 2, 3] },
+            parameters: { temperature: 0.5, maxTokens: 256, topP: 0.9, seed: 42 },
+            output: { answer: 'result', score: 0.99 },
+            sdkVersion: '0.1.0',
+            appId: 'myapp',
+        });
+        const expectedInputCanonical = '{"context":[1,2,3],"query":"test"}';
+        const expectedOutputCanonical = '{"answer":"result","score":0.99}';
+        assert.equal(toCanonicalJson(snap.input), expectedInputCanonical);
+        assert.equal(toCanonicalJson(snap.output), expectedOutputCanonical);
+        assert.equal(snap.inputHash, computeInputHash({ query: 'test', context: [1, 2, 3] }));
+        assert.equal(snap.outputHash, computeOutputHash({ answer: 'result', score: 0.99 }));
+        const v1 = verifySnapshot(snap);
+        assert.equal(v1.ok, true);
+        const bundle = sealCer(snap, { createdAt: '2026-01-01T00:00:00.000Z' });
+        const v2 = verifyCer(bundle);
+        assert.equal(v2.ok, true);
+        const bundle2 = sealCer(snap, { createdAt: '2026-01-01T00:00:00.000Z' });
+        assert.equal(bundle.certificateHash, bundle2.certificateHash);
+    });
+});
+//# sourceMappingURL=vectors.test.js.map