@nexart/ai-execution 0.5.0 → 0.7.0

package/README.md

@@ -1,10 +1,18 @@
-# @nexart/ai-execution v0.5.0
+# @nexart/ai-execution v0.7.0
 
 Tamper-evident records and Certified Execution Records (CER) for AI operations.
 
+## Version Information
+
+| Component | Version |
+|---|---|
+| Service | — |
+| SDK | 0.7.0 |
+| Protocol | 1.2.0 |
+
 ## Why Not Just Store Logs?
 
-Logs tell you what happened. CERs prove integrity. 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 recorded execution has not been modified post-hoc, logs are insufficient. CERs provide the tamper-evident chain of custody that logs cannot. **CERs certify records, not model determinism or provider execution.**
+Logs tell you what happened. CERs prove integrity. 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 hashed fields — including input, output, parameters, and any recorded chain/tool evidence — invalidates the certificate hash. If you need to demonstrate to an auditor, regulator, or downstream system that a recorded execution has not been modified post-hoc, logs are insufficient. CERs provide the tamper-evident chain of custody that logs cannot. **CERs certify records, not model determinism or provider execution.**
 
 ## What This Does
 
@@ -97,7 +105,7 @@ const summary = run.finalize();
 // { runId, stepCount: 2, steps: [...], finalStepHash: "sha256:..." }
 ```
 
-### Attest to Canonical Node
+### Attest to NexArt Attestation Node (optional)
 
 ```typescript
 import { certifyDecision, attest } from '@nexart/ai-execution';
@@ -110,7 +118,7 @@ const proof = await attest(cer, {
 console.log(proof.attestationId);
 ```
 
-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.
+Attestation verifies internal integrity only. It does not re-run the model. The node confirms the bundle's hashes are consistent and returns an independently verifiable signed receipt (when the node is configured for signing).
 
 ### Archive (Export / Import)
 
@@ -139,7 +147,7 @@ const restored = importCer(json);     // parse + verify (throws on tamper)
 | `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 `"0.4.2"` |
+| `sdkVersion` | Optional | `string \| null` | Defaults to `"0.7.0"` |
 | `appId` | Optional | `string \| null` | Defaults to `null` |
 | `runId` | Optional | `string \| null` | Workflow run ID |
 | `stepId` | Optional | `string \| null` | Step identifier within a run |
@@ -147,6 +155,7 @@ const restored = importCer(json);     // parse + verify (throws on tamper)
 | `workflowId` | Optional | `string \| null` | Workflow template ID |
 | `conversationId` | Optional | `string \| null` | Conversation/session ID |
 | `prevStepHash` | Optional | `string \| null` | certificateHash of previous step |
+| `toolCalls` | Optional | `ToolEvent[]` | v0.7.0+ tool/dependency evidence records. **Included in `certificateHash` when present.** See Level 4 section. |
 
 Auto-generated fields (set by `createSnapshot`, do not set manually): `type`, `protocolVersion`, `executionSurface`, `inputHash`, `outputHash`.
 
@@ -158,14 +167,39 @@ Auto-generated fields (set by `createSnapshot`, do not set manually): `type`, `p
   "certificateHash": "sha256:...",
   "createdAt": "2026-02-12T00:00:00.000Z",
   "version": "0.1",
-  "snapshot": { ... },
-  "meta": { "source": "my-app", "tags": ["production"] }
+  "snapshot": { "..." : "..." },
+  "meta": { "source": "my-app", "tags": ["production"] },
+  "declaration": {
+    "stabilitySchemeId": "nexart-cer-v1",
+    "protectedSetId": "ai.execution.v1.full",
+    "protectedFields": ["snapshot", "bundleType", "version", "createdAt"],
+    "notes": "optional free text"
+  }
 }
 ```
 
 ### Certificate Hash Computation
 
-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.
+The `certificateHash` is SHA-256 of the UTF-8 bytes of the canonical JSON of exactly: `{ bundleType, version, createdAt, snapshot }`. `meta` and `declaration` are excluded. Key-ordering is recursive. This computation is identical across all SDK versions.
+
+### Declaration Block (v0.7.0+)
+
+The optional `declaration` field is a self-describing metadata block for AIEF-02 conformance. It carries `stabilitySchemeId`, `protectedSetId`, and `protectedFields` so that verifiers can confirm which fields are covered by the certificate hash without side-channel knowledge.
+
+**`declaration` is excluded from `certificateHash` by design.** It is purely informational — mutating it does not invalidate the bundle. Pass it via `sealCer(snapshot, { declaration: { ... } })`.
+
+Verifiers MUST treat `declaration` as advisory. For `cer.ai.execution.v1`, the protected set is defined by the bundleType semantics: `{ bundleType, version, createdAt, snapshot }` is what is hashed.
+
+```typescript
+const bundle = sealCer(snapshot, {
+  declaration: {
+    stabilitySchemeId: 'nexart-cer-v1',
+    protectedSetId: 'ai.execution.v1.full',
+    protectedFields: ['snapshot', 'bundleType', 'version', 'createdAt'],
+  },
+});
+// verifyCer(bundle).ok === true — declaration does not affect the result
+```
 
 ## Attestation
 
@@ -277,6 +311,168 @@ const result = await verifyNodeReceiptSignature({
 
 **Skip re-attestation:** use `hasAttestation(bundle)` to check if a bundle already includes attestation fields before calling `attest()` again.
 
+## AIEF Interop (v0.7.0+)
+
+`verifyAief(bundle)` is an adapter over the existing `verifyCer()` / `verify()`. It returns the exact output shape required by AIEF §9.1 for cross-vendor verifier interoperability. The internal `verify()` return value is unchanged — `verifyAief` is purely additive.
+
+```typescript
+import { verifyAief } from '@nexart/ai-execution';
+
+const result = verifyAief(bundle);
+// {
+//   result: 'PASS' | 'FAIL',
+//   reason: string | null,           // null on PASS; AIEF §9.2 reason string on FAIL
+//   checks: {
+//     schemaSupported: boolean,       // false if SCHEMA_ERROR or CANONICALIZATION_ERROR
+//     integrityValid: boolean,        // false if any hash mismatch
+//     protectedSetValid: boolean,     // false if any hash mismatch (mirrors integrityValid for v1)
+//     chainValid: boolean,            // false only if CHAIN_BREAK_DETECTED
+//   },
+//   notes?: string[],                 // failure detail strings when available
+// }
+```
+
+**What we map / what we don't rename:**
+
+| NexArt `CerVerifyCode` | AIEF `reason` |
+|---|---|
+| `OK` | `ok` (reason is `null`) |
+| `CERTIFICATE_HASH_MISMATCH` | `integrityProofMismatch` |
+| `INPUT_HASH_MISMATCH` | `integrityProofMismatch` |
+| `OUTPUT_HASH_MISMATCH` | `integrityProofMismatch` |
+| `TOOL_OUTPUT_HASH_MISMATCH` | `integrityProofMismatch` |
+| `SCHEMA_ERROR` | `unsupportedSchema` |
+| `CANONICALIZATION_ERROR` | `malformedArtifact` |
+| `INVALID_SHA256_FORMAT` | `malformedArtifact` |
+| `UNKNOWN_ERROR` | `malformedArtifact` |
+| `INCOMPLETE_ARTIFACT` | `incompleteArtifact` |
+| `TOOL_EVIDENCE_MISSING` | `incompleteArtifact` |
+| `CHAIN_BREAK_DETECTED` | `chainBreakDetected` |
+| `VERIFICATION_MATERIAL_UNAVAILABLE` | `verificationMaterialUnavailable` |
+| `ATTESTATION_MISSING` | `verificationMaterialUnavailable` |
+| `ATTESTATION_KEY_NOT_FOUND` | `verificationMaterialUnavailable` |
+| `ATTESTATION_KEY_FORMAT_UNSUPPORTED` | `verificationMaterialUnavailable` |
+| `ATTESTATION_INVALID_SIGNATURE` | `signatureInvalid` |
+
+The AIEF reason strings are not renamed or mapped to NexArt-specific vocabulary — they are passed through verbatim for AIEF conformance. Per AIEF §9.0 rule #7, `chainValid` is `true` when chain fields are absent from the snapshot.
+
+`mapToAiefReason(code: string): string` is also exported if you need to convert a `CerVerifyCode` to an AIEF reason string directly. Unknown codes fall back to `"malformedArtifact"`.
+
+## Level 4 (Optional): Chain + Tool Evidence (v0.7.0+)
+
+> **If you do nothing, nothing changes.** All Level 4 features are additive and opt-in. Existing bundles without `toolCalls` verify identically.
+
+### Tool Calls
+
+Add a `toolCalls` array to the snapshot to record evidence of external tool or dependency invocations. When present, `toolCalls` is included in the `certificateHash` computation — tool evidence is part of the sealed record.
+
+`toolCalls` provide tamper-evident evidence of what was recorded about a tool/dependency call. They do not prove the external tool actually executed unless the tool itself provides independent verifiable proof (e.g., its own signed receipt).
+
+```typescript
+import { makeToolEvent, createSnapshot, sealCer } from '@nexart/ai-execution';
+
+const webResult = await fetch('https://api.example.com/data');
+const data = await webResult.json();
+
+const toolEvent = makeToolEvent({
+  toolId: 'web-search',
+  output: data,           // hashed automatically
+  input: { query: 'Q1 revenue' },  // optional; hashed if provided
+  evidenceRef: 'https://api.example.com/data',  // optional URL/ID
+});
+
+const snapshot = createSnapshot({
+  // ...
+  toolCalls: [toolEvent],
+});
+const bundle = sealCer(snapshot);
+```
+
+`ToolEvent` shape:
+
+| Field | Required | Description |
+|---|---|---|
+| `toolId` | **Yes** | Identifier of the tool/dependency called |
+| `at` | **Yes** | ISO 8601 timestamp (defaults to `new Date()` in `makeToolEvent`) |
+| `outputHash` | **Yes** | `sha256:<64hex>` of the tool output |
+| `inputHash` | No | `sha256:<64hex>` of the tool input (optional) |
+| `evidenceRef` | No | URL or external ID pointing to the raw evidence |
+| `error` | No | Error message if the tool call failed |
+
+`hashToolOutput(value)` hashes a tool output value: strings → SHA-256 of UTF-8 bytes; anything else → SHA-256 of canonical JSON bytes.
+
+### Chain Verification
+
+`verifyRunSummary(summary, bundles, opts?)` validates that a `RunBuilder` multi-step run forms an unbroken cryptographic chain. It detects insertion, deletion, and reordering of steps.
+
+```typescript
+import { RunBuilder, verifyRunSummary } from '@nexart/ai-execution';
+
+const run = new RunBuilder({ runId: 'my-run' });
+run.step({ /* step 0 */ });
+run.step({ /* step 1 */ });
+
+const summary = run.finalize();
+const bundles = run.getBundles(); // or retrieve from storage
+
+const result = verifyRunSummary(summary, bundles);
+// { ok: boolean, code: CerVerifyCode, errors: string[], breakAt?: number }
+```
+
+`verifyRunSummary` returns `RunSummaryVerifyResult`:
+- `ok: true` — full chain is valid
+- `ok: false` with `INCOMPLETE_ARTIFACT` — step count mismatch
+- `ok: false` with `CHAIN_BREAK_DETECTED` — stepIndex/prevStepHash/certificateHash mismatch; `breakAt` is the index of the first broken link
+
+### Profiles (Opt-in Strictness)
+
+`validateProfile(target, profile)` applies extra field-presence checks at creation time. It never affects `certificateHash` or `verifyCer()`.
+
+| Profile | What it enforces |
+|---|---|
+| `'flexible'` | No extra validation (default SDK behaviour) |
+| `'AIEF_L2'` | AIEF-01 required fields: `executionId`, `timestamp`, `provider`, `model`, `input`, `output`, `inputHash`, `outputHash` |
+| `'AIEF_L3'` | Same as `AIEF_L2` |
+| `'AIEF_L4'` | AIEF_L3 + validates each `ToolEvent` in `toolCalls`; requires `prevStepHash` when `stepIndex > 0` |
+
+```typescript
+import { validateProfile } from '@nexart/ai-execution';
+
+const result = validateProfile(bundle, 'AIEF_L4');
+// { ok: boolean, errors: string[] }
+```
+
+## Redaction Semantics (v0.7.0+)
+
+### Pre-seal verifiable redaction
+
+`redactBeforeSeal(snapshot, policy)` replaces sensitive snapshot fields with stable envelopes **before** sealing. Because the `certificateHash` is computed over the already-redacted snapshot, the resulting bundle passes `verifyCer()` unchanged.
+
+```typescript
+import { redactBeforeSeal, sealCer, verify } from '@nexart/ai-execution';
+
+const redacted = redactBeforeSeal(snapshot, { paths: ['input', 'output'] });
+const bundle = sealCer(redacted);
+verify(bundle).ok; // true — hash matches the redacted snapshot
+```
+
+Each redacted field becomes `{ _redacted: true, hash: "sha256:..." }` where `hash` is the SHA-256 of the original value. This lets authorized reviewers confirm what was there without accessing the raw content.
+
+**Supported fields for pre-seal redaction:**
+
+| Field | Supported | Notes |
+|---|---|---|
+| `input` | **Yes** | `inputHash` is recomputed from the envelope |
+| `output` | **Yes** | `outputHash` is recomputed from the envelope |
+| `toolCalls[n].output` *(via `ToolEvent.outputHash`)* | **Yes** | The `outputHash` already stores only the hash — the raw tool output need not be in the bundle at all |
+| `prompt` and other schema-validated strings | **No** | `verifySnapshot` validates these as non-empty strings. Replacing with an object envelope causes `verifyCer()` to return `SCHEMA_ERROR`. |
+
+### Post-hoc redaction breaks integrity — by design
+
+`sanitizeForStorage(bundle, options)` can replace arbitrary paths with a string placeholder, but it does **not** recompute any content hashes. This means `verifyCer()` will return `CERTIFICATE_HASH_MISMATCH` on the result. This is intentional: post-hoc redaction is a lossy, storage-only operation. If you need a verifiable record after storage-side redaction, you must re-seal with `sealCer()`.
+
+**Rule of thumb:** redact before sealing if you need `verify()` to pass; use `sanitizeForStorage` only for data you do not need to verify later.
+
 ## Canonical JSON Constraints
 
 1. Object keys sorted lexicographically (Unicode codepoint order) at every nesting level.
@@ -318,6 +514,18 @@ Fixtures at `fixtures/vectors/` and `fixtures/golden/`. Cross-language implement
 | Export | Description |
 |---|---|
 | `RunBuilder` | Multi-step workflow builder with prevStepHash chaining |
+| `verifyRunSummary(summary, bundles, opts?)` | Verify that a RunSummary + step bundles form an unbroken cryptographic chain (v0.7.0+) |
+
+### AIEF Interop (v0.7.0+)
+
+| Function | Description |
+|---|---|
+| `verifyAief(bundle)` | Verify a CER bundle and return the exact AIEF §9.1 output shape |
+| `mapToAiefReason(code)` | Convert a `CerVerifyCode` string to an AIEF §9.2 reason string |
+| `hashToolOutput(value)` | Hash a tool output value: string → UTF-8 SHA-256; other → canonical JSON SHA-256 |
+| `makeToolEvent(params)` | Build a `ToolEvent` record for inclusion in `snapshot.toolCalls` |
+| `redactBeforeSeal(snapshot, policy)` | Pre-seal redaction: replace `input`/`output` with verifiable envelopes before sealing |
+| `validateProfile(target, profile)` | Validate a snapshot or bundle against an AIEF strictness profile (does not affect hashing) |
 
 ### Attestation & Archive
 
@@ -332,10 +540,24 @@ Fixtures at `fixtures/vectors/` and `fixtures/golden/`. Cross-language implement
 | `selectNodeKey(doc, kid?)` | Select a key from a `NodeKeysDocument` by kid or activeKid (v0.5.0+) |
 | `verifyBundleAttestation(bundle, options)` | One-call offline attestation verification (v0.5.0+) |
 | `sanitizeForAttestation(bundle)` | Remove `undefined` keys, reject BigInt/functions/symbols |
+| `sanitizeForStorage(bundle, options?)` | Sanitize for DB storage with optional path-based redaction; does not recompute hashes (v0.6.0+) |
+| `sanitizeForStamp(bundle)` | Extract attestable core (no meta); does not recompute hashes (v0.6.0+) |
 | `hasAttestation(bundle)` | Check if bundle already has attestation fields |
 | `exportCer(bundle)` | Serialize to canonical JSON string |
 | `importCer(json)` | Parse + verify from JSON string |
 
+### Provider Drop-in (v0.6.0+)
+
+| Function | Description |
+|---|---|
+| `certifyDecisionFromProviderCall(params)` | One-function wrapper: extracts prompt/input/output/params from raw provider request+response and returns `{ ok, bundle }` or `{ ok: false, code: 'SCHEMA_ERROR', reason }`. Supports OpenAI, Anthropic, Gemini, Mistral, Bedrock, and generic shapes. |
+
+### Opinionated Client (v0.6.0+)
+
+| Export | Description |
+|---|---|
+| `createClient(defaults)` | Returns a `NexArtClient` with bound defaults (`appId`, `workflowId`, `nodeUrl`, `apiKey`, `tags`, `source`). Methods: `certifyDecision`, `certifyAndAttestDecision`, `verify`, `verifyBundleAttestation`. Defaults do not affect bundle hashing. |
+
 ### Reason Codes
 
 `CerVerifyCode` — stable string-union constant exported from the package root:
@@ -355,6 +577,11 @@ Fixtures at `fixtures/vectors/` and `fixtures/golden/`. Cross-language implement
 | `ATTESTATION_KEY_NOT_FOUND` | kid not found in node keys document (v0.5.0+) |
 | `ATTESTATION_INVALID_SIGNATURE` | Ed25519 signature did not verify (v0.5.0+) |
 | `ATTESTATION_KEY_FORMAT_UNSUPPORTED` | Key cannot be decoded (v0.5.0+) |
+| `CHAIN_BREAK_DETECTED` | `verifyRunSummary` detected a broken prevStepHash link or reordered step (v0.7.0+) |
+| `INCOMPLETE_ARTIFACT` | Step count mismatch between RunSummary and provided bundles (v0.7.0+) |
+| `VERIFICATION_MATERIAL_UNAVAILABLE` | Required verification material (keys, receipt) is absent (v0.7.0+) |
+| `TOOL_EVIDENCE_MISSING` | Required tool call evidence absent in an AIEF_L4 context (v0.7.0+) |
+| `TOOL_OUTPUT_HASH_MISMATCH` | A recorded `outputHash` in `toolCalls` does not match the provided tool output (v0.7.0+) |
 
 Priority when multiple failures exist: `CANONICALIZATION_ERROR` > `SCHEMA_ERROR` > `INVALID_SHA256_FORMAT` > `CERTIFICATE_HASH_MISMATCH` > `INPUT_HASH_MISMATCH` > `OUTPUT_HASH_MISMATCH` > `SNAPSHOT_HASH_MISMATCH` > `UNKNOWN_ERROR`.
 
@@ -378,7 +605,9 @@ Priority when multiple failures exist: `CANONICALIZATION_ERROR` > `SCHEMA_ERROR`
 | v0.4.0 | Dual ESM/CJS build, `sanitizeForAttestation`, `hasAttestation`, auto-sanitize in `attest()`, fixed `ERR_PACKAGE_PATH_NOT_EXPORTED` |
 | v0.4.1 | Verification reason codes (`CerVerifyCode`), `code` + `details` on `VerificationResult`, README provenance wording tightened |
 | v0.4.2 | `AttestationReceipt`, `getAttestationReceipt`, `certifyAndAttestDecision`, `attestIfNeeded` |
-| **v0.5.0** | Ed25519 signed receipt verification: `verifyNodeReceiptSignature`, `verifyBundleAttestation`, `fetchNodeKeys`, `selectNodeKey`; new attestation `CerVerifyCode` entries; `SPEC.md`; `NodeKeysDocument`, `SignedAttestationReceipt`, `NodeReceiptVerifyResult` types |
+| v0.5.0 | Ed25519 signed receipt verification: `verifyNodeReceiptSignature`, `verifyBundleAttestation`, `fetchNodeKeys`, `selectNodeKey`; new attestation `CerVerifyCode` entries; `SPEC.md`; `NodeKeysDocument`, `SignedAttestationReceipt`, `NodeReceiptVerifyResult` types |
+| v0.6.0 | Frictionless integration: `certifyDecisionFromProviderCall` (OpenAI/Anthropic/Gemini/Mistral/Bedrock drop-in); `sanitizeForStorage` + `sanitizeForStamp` redaction helpers; `createClient(defaults)` factory; regression fixture suite; all backward-compatible, no hash changes |
+| **v0.7.0** | AIEF alignment: `verifyAief()` (AIEF §9.1 adapter); `verifyRunSummary()` chain verifier; `makeToolEvent()` + `hashToolOutput()` + `snapshot.toolCalls` (AIEF-06); `BundleDeclaration` block (`stabilitySchemeId`, `protectedSetId`, `protectedFields`) excluded from `certificateHash`; `redactBeforeSeal()` pre-seal verifiable redaction; `validateProfile()` (flexible/AIEF_L2/L3/L4); 5 new `CerVerifyCode` entries; backward-compatible, no hash changes |
 | v1.0.0 | Planned: API stabilization, freeze public API surface |
 
 ## Releasing