@nexart/ai-execution 0.1.0 → 0.2.0

package/README.md

@@ -1,4 +1,4 @@
-# @nexart/ai-execution v0.1.0
+# @nexart/ai-execution v0.2.0
 
 Tamper-evident records and Certified Execution Records (CER) for AI operations.
 
@@ -15,6 +15,13 @@ 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.
 
+## 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.
+- **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.
+
 ## Installation
 
 ```bash
@@ -23,12 +30,27 @@ npm install @nexart/ai-execution
 
 ## Quick Start
 
-### Create a Snapshot Manually
+### Single Decision (3 lines)
+
+```typescript
+import { certifyDecision } from '@nexart/ai-execution';
+
+const cer = certifyDecision({
+  provider: 'openai',
+  model: 'gpt-4o',
+  prompt: 'Summarize.',
+  input: userQuery,
+  output: llmResponse,
+  parameters: { temperature: 0.7, maxTokens: 1024, topP: null, seed: null },
+});
+console.log(cer.certificateHash); // "sha256:..."
+```
+
+### Manual Snapshot + Seal (v0.1.0 style, still supported)
 
 ```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',
@@ -36,28 +58,79 @@ const snapshot = createSnapshot({
   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,
-  },
+  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
 ```
 
+### Agentic Multi-Step Workflow
+
+```typescript
+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',
+  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',
+  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 }
+```
+
+### Attest to Canonical Node
+
+```typescript
+import { certifyDecision, attest } from '@nexart/ai-execution';
+
+const cer = certifyDecision({ /* ... */ });
+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
@@ -67,12 +140,7 @@ const snapshot = createSnapshot({
   model: 'gpt-4o',
   prompt: 'Extract entities',
   input: { text: 'John lives in Paris', lang: 'en' },
-  parameters: {
-    temperature: 0,
-    maxTokens: 512,
-    topP: null,
-    seed: 42,
-  },
+  parameters: { temperature: 0, maxTokens: 512, topP: null, seed: 42 },
   output: { entities: ['John', 'Paris'], count: 2 },
 });
 ```
@@ -83,8 +151,6 @@ Convenience adapter only; the core value of this package is the snapshot + hashi
 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';
 
@@ -92,19 +158,65 @@ 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,
-  },
+  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.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
+
+```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
@@ -123,8 +235,14 @@ Requires `OPENAI_API_KEY` environment variable or `apiKey` parameter.
 | `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"`) |
+| `sdkVersion` | Optional | `string \| null` | Defaults to package version (`"0.2.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:
 
@@ -136,34 +254,6 @@ The following fields are **auto-generated** by `createSnapshot` and must not be
 | `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
@@ -191,6 +281,7 @@ The `certificateHash` is SHA-256 of the UTF-8 bytes of the canonical JSON of **e
 - `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
 
@@ -213,102 +304,117 @@ Canonical JSON is a deterministic subset of JSON. The following rules apply:
 
 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.
+
+## 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`
+- 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 to be considered compatible. Vectors are committed as JSON fixtures at:
+Cross-language implementations **must** match the test vectors exactly. Vectors are committed as JSON fixtures at:
 
 ```
 packages/ai-execution/fixtures/vectors/
 ```
 
-### Vector 001
+### Vector 001 (single decision)
 
-**Input snapshot** (`vector-001.snapshot.json`):
+See `vector-001.snapshot.json` and `vector-001.expected.json` for a single text-in/text-out CER with committed hash values.
 
-```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"
-}
-```
+### Vector 002 (3-step agentic chain)
 
-**Expected hashes** (`vector-001.expected.json`):
+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`
 
-| Hash | Value |
-|---|---|
-| `inputHash` | `sha256:52cb6b5e4a038af1756708f98afb718a08c75b87b2f03dbee4dd9c8139c15c5e` |
-| `outputHash` | `sha256:ae758477f843049bd252ceb5498aa33f190326589ee92cbe5a1ab563f54bc05b` |
-| `certificateHash` | `sha256:86275d60d088483eefaf0bd31d79629b11342315816f3a1da26980e4a05352f4` |
+Each entry includes `snapshot`, `expectedCertificateHash`, and `cerCreatedAt` for deterministic verification.
+
+### Golden Fixtures (backward compatibility)
 
-The `certificateHash` is computed with `cerCreatedAt: "2026-02-12T00:00:00.000Z"`.
+5 CER bundles produced with v0.1.0 semantics are committed at:
 
-**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.
+```
+packages/ai-execution/fixtures/golden/
+```
 
-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`.
+These bundles must verify with every future version of the library.
 
 ## Threat Model
 
-This package provides **integrity and auditability** for AI execution records. It is an auditing tool, not a security boundary.
+This package provides **integrity and auditability** for AI execution records.
 
 ### 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.
+- **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. 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.
+- **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 `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.
+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 snapshot = createSnapshot({ ... });
-const bundle = sealCer(snapshot);
+const bundle = certifyDecision({ ... });
 
 const check = verifyCer(bundle);
 if (!check.ok) {
   throw new Error(`CER integrity failure: ${check.errors.join('; ')}`);
 }
 
-await store(bundle); // persist as audit artifact
+await store(bundle);
+
+// Optional: attest to canonical node
+const proof = await attest(bundle, { nodeUrl, apiKey });
 ```
 
 ## Privacy & Data Handling
@@ -321,17 +427,46 @@ Snapshots include **raw prompt, input, and output by default**. This means:
 **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.
+- 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.
 
 ## API Reference
 
+### Core
+
 | 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) |
+| `certifyDecision(params)` | One-call: createSnapshot + sealCer combined **(v0.2.0)** |
+
+### 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 |
@@ -339,6 +474,29 @@ Snapshots include **raw prompt, input, and output by default**. This means:
 | `hashUtf8(value)` | Hash a UTF-8 string |
 | `hashCanonicalJson(value)` | Hash canonical JSON of a value |
 
+### Providers
+
+| 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)** |
+
+### Errors
+
+| Class | Description |
+|----------|-------------|
+| `CerVerificationError` | Thrown by `importCer()` on invalid/tampered data **(v0.2.0)** |
+| `CerAttestationError` | Thrown by `attest()` on failure **(v0.2.0)** |
+
+## Version Plan
+
+| 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. |
+
 ## How to Publish
 
 ```bash

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

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

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

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