@nexart/ai-execution 0.2.0 → 0.4.0

package/README.md

@@ -1,7 +1,11 @@
-# @nexart/ai-execution v0.2.0
+# @nexart/ai-execution v0.4.0
 
 Tamper-evident records and Certified Execution Records (CER) for AI operations.
 
+## Why Not Just Store Logs?
+
+Logs tell you what happened. CERs prove it. A log entry can be edited, truncated, or fabricated after the fact with no way to detect it. A CER bundle is cryptographically sealed: any modification — to the input, output, parameters, or ordering — invalidates the certificate hash. If you need to demonstrate to an auditor, regulator, or downstream system that a specific AI model produced a specific output for a specific input with specific parameters, logs are insufficient. CERs provide the tamper-evident chain of custody that logs cannot.
+
 ## What This Does
 
 This package creates integrity records for AI executions. Every time you call an AI model, it captures:
@@ -11,16 +15,16 @@ This package creates integrity records for AI executions. Every time you call an
 - 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.
+These records can be verified offline 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.
 
 ## Compatibility Guarantees
 
-- **v0.1.0 bundles verify forever.** Any CER bundle produced by v0.1.0 will pass `verifyCer()` in v0.2.0 and all future versions.
+- **v0.1.0, v0.2.0, and v0.3.0 bundles verify forever.** Any CER bundle produced by any prior version will pass `verify()` in v0.4.0 and all future versions.
 - **Hashing rules are frozen for `cer.ai.execution.v1`.** The canonicalization, SHA-256 computation, and certificate hash inputs (bundleType, version, createdAt, snapshot) are unchanged.
 - **New optional snapshot fields** (runId, stepId, stepIndex, etc.) default to undefined and are excluded from legacy snapshots. They participate in the certificate hash only when present.
-- **If stricter canonicalization is needed in the future**, it will ship as a new bundle type (e.g. `cer.ai.execution.v2`), not as a change to v1.
+- **Canonicalization is frozen for v1.** Number-to-string conversion uses `JSON.stringify()`, which is consistent across JavaScript engines but does not implement RFC 8785 (JCS) for edge cases like `-0`. If stricter canonicalization is required, it will ship as a new bundle type (`cer.ai.execution.v2`), never as a modification to v1.
 
 ## Installation
 
@@ -46,30 +50,24 @@ const cer = certifyDecision({
 console.log(cer.certificateHash); // "sha256:..."
 ```
 
-### Manual Snapshot + Seal (v0.1.0 style, still supported)
+### Manual Snapshot + Seal
 
 ```typescript
-import { createSnapshot, verifySnapshot, sealCer, verifyCer } from '@nexart/ai-execution';
+import { createSnapshot, sealCer, verify } from '@nexart/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.',
 });
 
-const result = verifySnapshot(snapshot);
-console.log(result.ok); // true
-
 const bundle = sealCer(snapshot);
-console.log(bundle.certificateHash); // "sha256:..."
-
-const cerResult = verifyCer(bundle);
-console.log(cerResult.ok); // true
+const result = verify(bundle);
+console.log(result.ok); // true
 ```
 
 ### Agentic Multi-Step Workflow
@@ -79,28 +77,24 @@ import { RunBuilder } from '@nexart/ai-execution';
 
 const run = new RunBuilder({ runId: 'analysis-run', workflowId: 'data-pipeline' });
 
-const step0 = run.step({
-  provider: 'openai',
-  model: 'gpt-4o',
+run.step({
+  provider: 'openai', model: 'gpt-4o',
   prompt: 'Plan the analysis.',
   input: 'Analyze Q1 sales data.',
   output: 'I will: 1) load data, 2) compute totals, 3) summarize.',
   parameters: { temperature: 0.3, maxTokens: 512, topP: null, seed: null },
 });
-// step0.snapshot.stepIndex === 0, prevStepHash === null
 
-const step1 = run.step({
-  provider: 'openai',
-  model: 'gpt-4o',
+run.step({
+  provider: 'openai', model: 'gpt-4o',
   prompt: 'Execute step 1.',
   input: 'Load and total Q1 data.',
   output: 'Total revenue: $1.2M.',
   parameters: { temperature: 0.3, maxTokens: 512, topP: null, seed: null },
 });
-// step1.snapshot.stepIndex === 1, prevStepHash === step0.certificateHash
 
 const summary = run.finalize();
-// { runId, stepCount: 2, steps: [...], finalStepHash: step1.certificateHash }
+// { runId, stepCount: 2, steps: [...], finalStepHash: "sha256:..." }
 ```
 
 ### Attest to Canonical Node
@@ -113,110 +107,20 @@ const proof = await attest(cer, {
   nodeUrl: 'https://node.nexart.io',
   apiKey: process.env.NEXART_API_KEY!,
 });
-console.log(proof.attestationId); // ledger proof reference
-```
-
-### Archive (Export / Import)
-
-```typescript
-import { exportCer, importCer, sealCer, createSnapshot } from '@nexart/ai-execution';
-
-const bundle = sealCer(createSnapshot({ /* ... */ }));
-
-// Export as canonical JSON string (deterministic, archive-safe)
-const json = exportCer(bundle);
-await fs.writeFile('audit/cer-001.json', json);
-
-// Import and verify in one step (throws CerVerificationError if invalid)
-const restored = importCer(await fs.readFile('audit/cer-001.json', 'utf-8'));
-```
-
-### 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 },
-});
+console.log(proof.attestationId);
 ```
 
-### 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.
-
-```typescript
-import { runOpenAIChatExecution } from '@nexart/ai-execution/providers/openai';
+Attestation verifies internal integrity only. It does not re-run the model. The node confirms the bundle's hashes are consistent and records it in the proof ledger.
 
-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.
-
-### Anthropic Provider (Optional)
+### Archive (Export / Import)
 
 ```typescript
-import { runAnthropicExecution } from '@nexart/ai-execution/providers/anthropic';
+import { exportCer, importCer } from '@nexart/ai-execution';
 
-const result = await runAnthropicExecution({
-  prompt: 'You are a helpful assistant.',
-  input: 'Explain quantum computing briefly.',
-  model: 'claude-sonnet-4-20250514',
-  parameters: { temperature: 0.5, maxTokens: 512 },
-});
+const json = exportCer(bundle);       // canonical JSON string
+const restored = importCer(json);     // parse + verify (throws on tamper)
 ```
 
-Requires `ANTHROPIC_API_KEY` environment variable or `apiKey` parameter.
-
-### Generic Provider Wrapper
-
-```typescript
-import { wrapProvider } from '@nexart/ai-execution/providers/wrap';
-
-const myProvider = wrapProvider({
-  provider: 'my-llm',
-  callFn: async (input) => await myLlmClient.chat(input),
-  extractOutput: (raw) => raw.message,
-  extractModelVersion: (raw) => raw.modelVersion,
-});
-
-const result = await myProvider.execute({
-  providerInput: { messages: [{ role: 'user', content: 'Hello' }] },
-  prompt: 'System prompt',
-  input: 'Hello',
-  model: 'my-model-v2',
-  parameters: { temperature: 0.7, maxTokens: 1024, topP: null, seed: null },
-});
-```
-
-## v0.2.0 Additions
-
-| Feature | Description |
-|---|---|
-| `certifyDecision()` | One-call convenience: createSnapshot + sealCer combined |
-| `RunBuilder` | Agentic workflow support with step chaining and prevStepHash |
-| `attest()` | Post CER bundle to canonical node for ledger attestation |
-| `exportCer()` / `importCer()` | Archive-safe canonical JSON serialization with verification |
-| `wrapProvider()` | Generic provider wrapper factory |
-| Anthropic adapter | `@nexart/ai-execution/providers/anthropic` |
-| Typed errors | `CerVerificationError`, `CerAttestationError` |
-| Workflow fields | `runId`, `stepId`, `stepIndex`, `workflowId`, `conversationId`, `prevStepHash` |
-
 ## Snapshot Format (ai.execution.v1)
 
 ### Required vs Optional Fields
@@ -235,24 +139,16 @@ const result = await myProvider.execute({
 | `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.2.0"`) |
+| `sdkVersion` | Optional | `string \| null` | Defaults to `"0.4.0"` |
 | `appId` | Optional | `string \| null` | Defaults to `null` |
-| `runId` | Optional | `string \| null` | Workflow run ID (v0.2.0+) |
-| `stepId` | Optional | `string \| null` | Step identifier within a run (v0.2.0+) |
-| `stepIndex` | Optional | `number \| null` | 0-based step position (v0.2.0+) |
-| `workflowId` | Optional | `string \| null` | Workflow template ID (v0.2.0+) |
-| `conversationId` | Optional | `string \| null` | Conversation/session ID (v0.2.0+) |
-| `prevStepHash` | Optional | `string \| null` | certificateHash of previous step (v0.2.0+) |
+| `runId` | Optional | `string \| null` | Workflow run ID |
+| `stepId` | Optional | `string \| null` | Step identifier within a run |
+| `stepIndex` | Optional | `number \| null` | 0-based step position |
+| `workflowId` | Optional | `string \| null` | Workflow template ID |
+| `conversationId` | Optional | `string \| null` | Conversation/session ID |
+| `prevStepHash` | Optional | `string \| null` | certificateHash of previous step |
 
-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 |
+Auto-generated fields (set by `createSnapshot`, do not set manually): `type`, `protocolVersion`, `executionSurface`, `inputHash`, `outputHash`.
 
 ## CER Bundle Format
 
@@ -263,249 +159,123 @@ The following fields are **auto-generated** by `createSnapshot` and must not be
   "createdAt": "2026-02-12T00:00:00.000Z",
   "version": "0.1",
   "snapshot": { ... },
-  "meta": {
-    "source": "my-app",
-    "tags": ["production"]
-  }
+  "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).
-- **This computation is identical in v0.1.0 and v0.2.0.** New optional snapshot fields (runId, stepIndex, etc.) participate in the hash only when present in the snapshot object.
-
-## 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.
-
-**Note on number formatting:** v1 bundles use `JSON.stringify()` for number-to-string conversion, which is consistent across JavaScript engines but does not implement RFC 8785 (JCS) number formatting for edge cases like `-0`. If stricter canonicalization is required in the future, it will be introduced via a new bundle type (`cer.ai.execution.v2`), not by modifying v1 behavior.
-
-## RunBuilder: Agentic Workflow Chaining
-
-The `RunBuilder` class enables multi-step AI workflows with cryptographic chaining:
-
-- **Auto-incrementing `stepIndex`**: starts at 0, increments with each `.step()` call.
-- **`prevStepHash` chaining**: each step's `prevStepHash` is set to the `certificateHash` of the previous step (null for step 0).
-- **`executionId` generation**: automatically set to `{runId}-step-{stepIndex}`.
-- Each step produces a full, independently verifiable CER bundle.
-- Call `.finalize()` to get a `RunSummary` with all step hashes and chain metadata.
+The `certificateHash` is SHA-256 of the UTF-8 bytes of the canonical JSON of exactly: `{ bundleType, version, createdAt, snapshot }`. `meta` is excluded. Key-ordering is recursive. This computation is identical across all SDK versions.
 
 ## Attestation
 
-The `attest()` function posts a sealed CER bundle to a NexArt canonical node:
-
-```typescript
-const proof = await attest(bundle, {
-  nodeUrl: 'https://node.nexart.io',
-  apiKey: 'your-api-key',
-});
-```
+Endpoint: `POST {nodeUrl}/api/attest`
 
-- Endpoint: `POST {nodeUrl}/api/attest`
 - Authorization: `Bearer {apiKey}`
-- Body: the full CER bundle as JSON
+- Body: the full CER bundle as JSON (auto-sanitized via `sanitizeForAttestation` in v0.4.0+)
 - Returns: `AttestationResult` with `attestationId`, `nodeRuntimeHash`, `certificateHash`, `protocolVersion`
-- Throws: `CerAttestationError` on network or HTTP errors
-
-## Error Types
-
-| Error | When thrown |
-|---|---|
-| `CerVerificationError` | `importCer()` receives invalid or tampered JSON |
-| `CerAttestationError` | `attest()` fails (network error, HTTP error, invalid response) |
-
-Both extend `Error` and include structured data:
-- `CerVerificationError.errors`: `string[]` of specific verification failures
-- `CerAttestationError.statusCode`: HTTP status code (if available)
-- `CerAttestationError.responseBody`: raw response body (if available)
-
-## Interoperability (Test Vectors)
-
-Cross-language implementations **must** match the test vectors exactly. Vectors are committed as JSON fixtures at:
-
-```
-packages/ai-execution/fixtures/vectors/
-```
-
-### Vector 001 (single decision)
-
-See `vector-001.snapshot.json` and `vector-001.expected.json` for a single text-in/text-out CER with committed hash values.
-
-### Vector 002 (3-step agentic chain)
-
-See `vector-002.chain.json` for a 3-step workflow chain with:
-- Step 0: `prevStepHash: null`, `stepIndex: 0`
-- Step 1: `prevStepHash: step0.certificateHash`, `stepIndex: 1`
-- Step 2: `prevStepHash: step1.certificateHash`, `stepIndex: 2`
-
-Each entry includes `snapshot`, `expectedCertificateHash`, and `cerCreatedAt` for deterministic verification.
-
-### Golden Fixtures (backward compatibility)
-
-5 CER bundles produced with v0.1.0 semantics are committed at:
-
-```
-packages/ai-execution/fixtures/golden/
-```
+- Default timeout: 10 seconds (configurable via `timeoutMs`)
+- Validates: response `certificateHash` matches submitted bundle; all hashes in `sha256:<64hex>` format
+- Throws: `CerAttestationError` on mismatch, network error, timeout, or HTTP error
 
-These bundles must verify with every future version of the library.
+Attestation verifies internal integrity only. It does not re-run the model or validate the correctness of the AI output.
 
-## Threat Model
+### Sanitization and Redaction
 
-This package provides **integrity and auditability** for AI execution records.
+`sanitizeForAttestation(bundle)` returns a JSON-safe deep clone:
+- Removes keys with `undefined` values at all nesting levels
+- Rejects `BigInt`, functions, and symbols (throws)
+- Safe to serialize with `JSON.stringify` or canonical JSON
 
-### What it prevents
+**Recommended redaction pattern:** delete keys or set them to `null` — never set to `undefined`, which is not valid JSON. Call `sanitizeForAttestation` before archiving or attesting if your bundle may contain `undefined` values.
 
-- **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.
-- **Silent record edits** — any modification to a sealed CER bundle is detectable via `verifyCer()`.
-- **Chain forgery** — in multi-step workflows, `prevStepHash` links each step to the previous, making it impossible to insert, remove, or reorder steps without detection.
+**Skip re-attestation:** use `hasAttestation(bundle)` to check if a bundle already includes attestation fields before calling `attest()` again.
 
-### What it does NOT prevent
-
-- **Provider lying** — if the AI provider returns fabricated output, this package faithfully records it.
-- **Model drift** — models change over time. `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 `certifyDecision(...)` (or `createSnapshot` + `sealCer`).
-2. Call `verifyCer(bundle)` **before** storing — catches any in-memory corruption.
-3. Store the full bundle as an immutable audit artifact.
-4. Optionally call `attest(bundle, ...)` to register on the canonical node ledger.
-5. On retrieval, call `verifyCer(bundle)` again to confirm integrity.
-
-```typescript
-const bundle = certifyDecision({ ... });
-
-const check = verifyCer(bundle);
-if (!check.ok) {
-  throw new Error(`CER integrity failure: ${check.errors.join('; ')}`);
-}
-
-await store(bundle);
+## Canonical JSON Constraints
 
-// Optional: attest to canonical node
-const proof = await attest(bundle, { nodeUrl, apiKey });
-```
+1. Object keys sorted lexicographically (Unicode codepoint order) at every nesting level.
+2. No whitespace between tokens.
+3. Array order preserved.
+4. `null` serialized as `null`.
+5. Numbers must be finite. `NaN`, `Infinity`, `-Infinity` rejected (throw).
+6. `undefined` values in object properties omitted (key dropped).
+7. `BigInt`, functions, `Symbol` rejected (throw).
+8. Strings JSON-escaped.
 
-## Privacy & Data Handling
+**Canonicalization is frozen for v1.** Number formatting uses `JSON.stringify()` (V8-consistent). This does not normalize `-0` to `0` and does not implement RFC 8785 exponential notation rules. These are documented known behaviors, not bugs. Any future stricter canonicalization will ship under a new bundle type.
 
-Snapshots include **raw prompt, input, and output by default**. This means:
+## Error Types
 
-- 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.
+| Error | When thrown | Structured data |
+|---|---|---|
+| `CerVerificationError` | `importCer()` on invalid/tampered data | `.errors: string[]` |
+| `CerAttestationError` | `attest()` on failure | `.statusCode`, `.responseBody`, `.details: string[]` |
 
-**Recommendations:**
+## Interoperability (Test Vectors)
 
-- For sensitive workloads, consider redacting input/output before calling `createSnapshot()`, then verify the redacted versions.
-- A dedicated redacted bundle type (`cer.ai.execution.redacted.v1`) is planned for a future release.
-- Treat CER bundles with the same access controls as the underlying data they contain.
+Fixtures at `fixtures/vectors/` and `fixtures/golden/`. Cross-language implementations must match committed hash values exactly. Golden fixtures (v0.1.0 semantics) must verify with every future version.
 
 ## API Reference
 
 ### Core
 
 | Function | Description |
-|----------|-------------|
-| `createSnapshot(params)` | Create an AI execution snapshot with computed hashes |
+|---|---|
+| `createSnapshot(params)` | Create 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) |
-| `certifyDecision(params)` | One-call: createSnapshot + sealCer combined **(v0.2.0)** |
+| `sealCer(snapshot, options?)` | Seal snapshot into CER bundle |
+| `verify(bundle)` / `verifyCer(bundle)` | Verify CER bundle |
+| `certifyDecision(params)` | One-call: createSnapshot + sealCer |
 
 ### Workflow
 
-| Function/Class | Description |
-|----------|-------------|
-| `RunBuilder` | Multi-step workflow builder with step chaining **(v0.2.0)** |
-| `RunBuilder.step(params)` | Add a step, returns sealed CER bundle |
-| `RunBuilder.finalize()` | Returns RunSummary with all step hashes |
-
-### Attestation
-
-| Function | Description |
-|----------|-------------|
-| `attest(bundle, options)` | Post CER bundle to canonical node **(v0.2.0)** |
-
-### Archive
-
-| Function | Description |
-|----------|-------------|
-| `exportCer(bundle)` | Serialize bundle to canonical JSON string **(v0.2.0)** |
-| `importCer(json)` | Parse + verify bundle from JSON string **(v0.2.0)** |
-
-### Hashing
-
-| Function | Description |
-|----------|-------------|
-| `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 |
+| Export | Description |
+|---|---|
+| `RunBuilder` | Multi-step workflow builder with prevStepHash chaining |
 
-### Providers
+### Attestation & Archive
 
 | Function | Description |
-|----------|-------------|
-| `runOpenAIChatExecution(params)` | OpenAI chat wrapper (sub-export) |
-| `runAnthropicExecution(params)` | Anthropic Messages wrapper **(v0.2.0)** |
-| `wrapProvider(config)` | Generic provider wrapper factory **(v0.2.0)** |
+|---|---|
+| `attest(bundle, options)` | Post CER to canonical node (auto-sanitizes) |
+| `sanitizeForAttestation(bundle)` | Remove `undefined` keys, reject BigInt/functions/symbols |
+| `hasAttestation(bundle)` | Check if bundle already has attestation fields |
+| `exportCer(bundle)` | Serialize to canonical JSON string |
+| `importCer(json)` | Parse + verify from JSON string |
 
-### Errors
+### Providers (sub-exports)
 
-| Class | Description |
-|----------|-------------|
-| `CerVerificationError` | Thrown by `importCer()` on invalid/tampered data **(v0.2.0)** |
-| `CerAttestationError` | Thrown by `attest()` on failure **(v0.2.0)** |
+| Function | Export path |
+|---|---|
+| `runOpenAIChatExecution` | `@nexart/ai-execution/providers/openai` |
+| `runAnthropicExecution` | `@nexart/ai-execution/providers/anthropic` |
+| `wrapProvider` | `@nexart/ai-execution/providers/wrap` |
 
-## Version Plan
+## Version History
 
-| Version | Status | Description |
-|---------|--------|-------------|
-| v0.1.0 | Released | Core snapshot + CER + verify + OpenAI adapter |
-| **v0.2.0** | **Current** | certifyDecision, RunBuilder, attest, archive, Anthropic, wrapProvider, typed errors, workflow fields |
-| v1.0.0 | Planned | API stabilization. Rename `sealCer`→`seal`, `verifyCer`→`verify` (old names kept as deprecated aliases). Freeze public API surface. |
+| Version | Description |
+|---|---|
+| v0.1.0 | Core snapshot + CER + verify + OpenAI adapter |
+| v0.2.0 | certifyDecision, RunBuilder, attest, archive, Anthropic, wrapProvider, typed errors, workflow fields |
+| v0.3.0 | Attestation hardening (hash validation, timeout), `verify` alias, `CerAttestationError.details`, release hygiene |
+| **v0.4.0** | Dual ESM/CJS build, `sanitizeForAttestation`, `hasAttestation`, auto-sanitize in `attest()`, fixed `ERR_PACKAGE_PATH_NOT_EXPORTED` |
+| v1.0.0 | Planned: API stabilization, freeze public API surface |
 
-## How to Publish
+## Releasing
 
 ```bash
 cd packages/ai-execution
 npm run build
-npm run test
+npm test
 npm publish --access public
 ```
 
+The `release` script automates build, test, version bump, and publish:
+
+```bash
+npm run release
+```
+
 ## License
 
 MIT