@nexart/ai-execution 0.3.0 → 0.4.1

package/README.md

@@ -1,10 +1,10 @@
-# @nexart/ai-execution v0.3.0
+# @nexart/ai-execution v0.4.1
 
 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.
+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.**
 
 ## What This Does
 
@@ -15,13 +15,13 @@ 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 offline to prove the execution happened as recorded.
+These records can be verified offline to detect any post-hoc modification and prove integrity of the recorded execution.
 
-**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.
+**Important:** This does NOT promise that an AI model will produce the same output twice, and it does not verify provider or model identity. LLMs are not deterministic. This package provides **integrity and auditability** — proof that the recorded input, output, and parameters have not been modified, and chain-of-custody for the execution record.
 
 ## Compatibility Guarantees
 
-- **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.
+- **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.1 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.
 - **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.
@@ -139,7 +139,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.3.0"` |
+| `sdkVersion` | Optional | `string \| null` | Defaults to `"0.4.1"` |
 | `appId` | Optional | `string \| null` | Defaults to `null` |
 | `runId` | Optional | `string \| null` | Workflow run ID |
 | `stepId` | Optional | `string \| null` | Step identifier within a run |
@@ -172,7 +172,7 @@ The `certificateHash` is SHA-256 of the UTF-8 bytes of the canonical JSON of exa
 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`
 - Default timeout: 10 seconds (configurable via `timeoutMs`)
 - Validates: response `certificateHash` matches submitted bundle; all hashes in `sha256:<64hex>` format
@@ -180,6 +180,17 @@ Endpoint: `POST {nodeUrl}/api/attest`
 
 Attestation verifies internal integrity only. It does not re-run the model or validate the correctness of the AI output.
 
+### Sanitization and Redaction
+
+`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
+
+**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.
+
+**Skip re-attestation:** use `hasAttestation(bundle)` to check if a bundle already includes attestation fields before calling `attest()` again.
+
 ## Canonical JSON Constraints
 
 1. Object keys sorted lexicographically (Unicode codepoint order) at every nesting level.
@@ -226,10 +237,32 @@ Fixtures at `fixtures/vectors/` and `fixtures/golden/`. Cross-language implement
 
 | Function | Description |
 |---|---|
-| `attest(bundle, options)` | Post CER to canonical node |
+| `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 |
 
+### Reason Codes
+
+`CerVerifyCode` — stable string-union constant exported from the package root:
+
+| Code | When set |
+|---|---|
+| `OK` | Verification passed |
+| `CERTIFICATE_HASH_MISMATCH` | `certificateHash` doesn't match recomputed hash |
+| `INPUT_HASH_MISMATCH` | `inputHash` doesn't match recomputed hash |
+| `OUTPUT_HASH_MISMATCH` | `outputHash` doesn't match recomputed hash |
+| `SNAPSHOT_HASH_MISMATCH` | Both `inputHash` and `outputHash` are wrong |
+| `INVALID_SHA256_FORMAT` | A hash field doesn't start with `sha256:` |
+| `SCHEMA_ERROR` | Wrong bundleType/version, missing snapshot, non-finite parameters, etc. |
+| `CANONICALIZATION_ERROR` | `toCanonicalJson` threw during verification |
+| `UNKNOWN_ERROR` | Catch-all for unclassified failures |
+
+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`.
+
+**These codes are stable across all future versions.** New codes may be added but existing codes will not be renamed or removed.
+
 ### Providers (sub-exports)
 
 | Function | Export path |
@@ -244,7 +277,9 @@ Fixtures at `fixtures/vectors/` and `fixtures/golden/`. Cross-language implement
 |---|---|
 | 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.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` |
+| **v0.4.1** | Verification reason codes (`CerVerifyCode`), `code` + `details` on `VerificationResult`, README provenance wording tightened |
 | v1.0.0 | Planned: API stabilization, freeze public API surface |
 
 ## Releasing