@nexart/ai-execution 0.2.0 → 0.3.0

package/README.md

@@ -1,7 +1,11 @@
-# @nexart/ai-execution v0.2.0
+# @nexart/ai-execution v0.3.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 and v0.2.0 bundles verify forever.** Any CER bundle produced by any prior version will pass `verify()` in v0.3.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
+console.log(proof.attestationId);
 ```
 
-### 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 },
-});
-```
-
-### 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';
-
-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 },
-});
+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.
 
-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)
-
-```typescript
-import { runAnthropicExecution } from '@nexart/ai-execution/providers/anthropic';
-
-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 },
-});
-```
-
-Requires `ANTHROPIC_API_KEY` environment variable or `apiKey` parameter.
-
-### Generic Provider Wrapper
+### Archive (Export / Import)
 
 ```typescript
-import { wrapProvider } from '@nexart/ai-execution/providers/wrap';
+import { exportCer, importCer } from '@nexart/ai-execution';
 
-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 },
-});
+const json = exportCer(bundle);       // canonical JSON string
+const restored = importCer(json);     // parse + verify (throws on tamper)
 ```
 
-## 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.3.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+) |
-
-The following fields are **auto-generated** by `createSnapshot` and must not be set manually:
+| `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 |
 
-| 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,109 @@ 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
 - 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/
-```
-
-These bundles must verify with every future version of the library.
-
-## Threat Model
-
-This package provides **integrity and auditability** for AI execution records.
+- 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
 
-### What it prevents
+Attestation verifies internal integrity only. It does not re-run the model or validate the correctness of the AI output.
 
-- **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.
-
-### 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 |
+| `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 |
+| 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

package/dist/attest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attest.d.ts","sourceRoot":"","sources":["../src/attest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGzF,wBAAsB,MAAM,CAC1B,MAAM,EAAE,oBAAoB,EAC5B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,iBAAiB,CAAC,CAmD5B"}
+{"version":3,"file":"attest.d.ts","sourceRoot":"","sources":["../src/attest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAczF,wBAAsB,MAAM,CAC1B,MAAM,EAAE,oBAAoB,EAC5B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,iBAAiB,CAAC,CA0F5B"}

package/dist/attest.js

@@ -1,6 +1,19 @@
 import { CerAttestationError } from './errors.js';
+const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const DEFAULT_TIMEOUT_MS = 10_000;
+function validateHashFormat(value, fieldName) {
+    if (typeof value !== 'string')
+        return null;
+    if (!SHA256_PATTERN.test(value)) {
+        return `${fieldName} is not in sha256:<64hex> format: "${value}"`;
+    }
+    return null;
+}
 export async function attest(bundle, options) {
     const url = `${options.nodeUrl.replace(/\/+$/, '')}/api/attest`;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
     let response;
     try {
         response = await fetch(url, {
@@ -10,10 +23,19 @@ export async function attest(bundle, options) {
                 'Authorization': `Bearer ${options.apiKey}`,
             },
             body: JSON.stringify(bundle),
+            signal: controller.signal,
         });
     }
     catch (err) {
-        throw new CerAttestationError(`Network error contacting attestation node: ${err.message}`);
+        clearTimeout(timer);
+        const error = err;
+        if (error.name === 'AbortError') {
+            throw new CerAttestationError(`Attestation request timed out after ${timeoutMs}ms`);
+        }
+        throw new CerAttestationError(`Network error contacting attestation node: ${error.message}`);
+    }
+    finally {
+        clearTimeout(timer);
     }
     let body;
     try {
@@ -24,12 +46,27 @@ export async function attest(bundle, options) {
         throw new CerAttestationError(`Attestation node returned non-JSON response (${response.status}): ${text}`, response.status);
     }
     if (!response.ok) {
-        const msg = typeof body === 'object' && body !== null && 'error' in body
-            ? body.error
+        const result = body;
+        const msg = typeof result.error === 'string'
+            ? result.error
             : `HTTP ${response.status}`;
-        throw new CerAttestationError(`Attestation failed: ${msg}`, response.status, body);
+        const details = Array.isArray(result.details) ? result.details : undefined;
+        throw new CerAttestationError(`Attestation failed: ${msg}`, response.status, body, details);
     }
     const result = body;
+    const errors = [];
+    if (typeof result.certificateHash === 'string' && result.certificateHash !== bundle.certificateHash) {
+        errors.push(`Node returned certificateHash "${result.certificateHash}" but bundle has "${bundle.certificateHash}"`);
+    }
+    const certHashErr = validateHashFormat(result.certificateHash, 'response.certificateHash');
+    if (certHashErr)
+        errors.push(certHashErr);
+    const runtimeHashErr = validateHashFormat(result.nodeRuntimeHash, 'response.nodeRuntimeHash');
+    if (runtimeHashErr)
+        errors.push(runtimeHashErr);
+    if (errors.length > 0) {
+        throw new CerAttestationError(`Attestation response validation failed: ${errors.join('; ')}`, response.status, body, errors);
+    }
     return {
         ok: true,
         attestationId: typeof result.attestationId === 'string' ? result.attestationId : undefined,

package/dist/attest.js.map

@@ -1 +1 @@
-{"version":3,"file":"attest.js","sourceRoot":"","sources":["../src/attest.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD,MAAM,CAAC,KAAK,UAAU,MAAM,CAC1B,MAA4B,EAC5B,OAAsB;IAEtB,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,aAAa,CAAC;IAEhE,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAC1B,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,eAAe,EAAE,UAAU,OAAO,CAAC,MAAM,EAAE;aAC5C;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;SAC7B,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,mBAAmB,CAC3B,8CAA+C,GAAa,CAAC,OAAO,EAAE,CACvE,CAAC;IACJ,CAAC;IAED,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;QACnD,MAAM,IAAI,mBAAmB,CAC3B,gDAAgD,QAAQ,CAAC,MAAM,MAAM,IAAI,EAAE,EAC3E,QAAQ,CAAC,MAAM,CAChB,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,GAAG,GAAG,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,IAAI;YACtE,CAAC,CAAE,IAA0B,CAAC,KAAK;YACnC,CAAC,CAAC,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC9B,MAAM,IAAI,mBAAmB,CAC3B,uBAAuB,GAAG,EAAE,EAC5B,QAAQ,CAAC,MAAM,EACf,IAAI,CACL,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,IAA+B,CAAC;IAE/C,OAAO;QACL,EAAE,EAAE,IAAI;QACR,aAAa,EAAE,OAAO,MAAM,CAAC,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS;QAC1F,eAAe,EAAE,OAAO,MAAM,CAAC,eAAe,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS;QAChG,eAAe,EAAE,OAAO,MAAM,CAAC,eAAe,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS;QAChG,eAAe,EAAE,OAAO,MAAM,CAAC,eAAe,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS;QAChG,GAAG,EAAE,IAAI;KACV,CAAC;AACJ,CAAC"}
+{"version":3,"file":"attest.js","sourceRoot":"","sources":["../src/attest.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -5,6 +5,7 @@ export declare class CerVerificationError extends Error {
 export declare class CerAttestationError extends Error {
     readonly statusCode?: number;
     readonly responseBody?: unknown;
-    constructor(message: string, statusCode?: number, responseBody?: unknown);
+    readonly details?: string[];
+    constructor(message: string, statusCode?: number, responseBody?: unknown, details?: string[]);
 }
 //# sourceMappingURL=errors.d.ts.map