@nexart/ai-execution 0.7.0 → 0.9.0

package/README.md

@@ -1,4 +1,4 @@
-# @nexart/ai-execution v0.7.0
+# @nexart/ai-execution v0.8.0
 
 Tamper-evident records and Certified Execution Records (CER) for AI operations.
 
@@ -7,7 +7,7 @@ Tamper-evident records and Certified Execution Records (CER) for AI operations.
 | Component | Version |
 |---|---|
 | Service | — |
-| SDK | 0.7.0 |
+| SDK | 0.8.0 |
 | Protocol | 1.2.0 |
 
 ## Why Not Just Store Logs?
@@ -147,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.7.0"` |
+| `sdkVersion` | Optional | `string \| null` | Defaults to `"0.8.0"` |
 | `appId` | Optional | `string \| null` | Defaults to `null` |
 | `runId` | Optional | `string \| null` | Workflow run ID |
 | `stepId` | Optional | `string \| null` | Step identifier within a run |
@@ -442,6 +442,49 @@ const result = validateProfile(bundle, 'AIEF_L4');
 // { ok: boolean, errors: string[] }
 ```
 
+## Opinionated Run Helper
+
+`certifyAndAttestRun(steps, options?)` combines RunBuilder step creation, optional per-step attestation, and finalization into a single call. It does not change `RunBuilder` semantics — it creates an internal RunBuilder and returns all artifacts together.
+
+```typescript
+import { certifyAndAttestRun, verifyRunSummary, attest } from '@nexart/ai-execution';
+
+const { runSummary, stepBundles, receipts, finalStepHash } =
+  await certifyAndAttestRun(
+    [step0Params, step1Params, step2Params],
+    {
+      runId: 'analysis-run',
+      workflowId: 'data-pipeline',
+      // Optional: attest each step immediately after sealing
+      attestStep: (bundle) => attest(bundle, { nodeUrl, apiKey }),
+    },
+  );
+
+verifyRunSummary(runSummary, stepBundles); // { ok: true }
+```
+
+**Return shape:**
+
+| Field | Type | Description |
+|---|---|---|
+| `runSummary` | `RunSummary` | From `RunBuilder.finalize()` — stepCount, steps, finalStepHash |
+| `stepBundles` | `CerAiExecutionBundle[]` | Sealed bundles in step order (index 0 = step 0) |
+| `receipts` | `(AttestationReceipt \| null)[]` | Attestation receipts in step order; `null` if `attestStep` was not provided |
+| `finalStepHash` | `string \| null` | Alias for `runSummary.finalStepHash` |
+
+**Testing without network:** inject a mock `attestStep` to test the full flow without hitting a node:
+
+```typescript
+const { runSummary, stepBundles, receipts } = await certifyAndAttestRun(steps, {
+  attestStep: async (bundle) => ({
+    attestationId: 'mock-' + bundle.certificateHash.slice(7, 15),
+    certificateHash: bundle.certificateHash,
+    nodeRuntimeHash: 'sha256:' + 'a'.repeat(64),
+    protocolVersion: '1.2.0',
+  }),
+});
+```
+
 ## Redaction Semantics (v0.7.0+)
 
 ### Pre-seal verifiable redaction
@@ -467,11 +510,43 @@ Each redacted field becomes `{ _redacted: true, hash: "sha256:..." }` where `has
 | `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
+### Verifiable redacted export (post-seal, new bundle)
 
-`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()`.
+`exportVerifiableRedacted(bundle, policy, options?)` is the right choice when you already have a sealed bundle and want to share a sanitized version that is still independently verifiable. It:
+
+1. Applies `redactBeforeSeal()` to the original snapshot
+2. Re-seals the redacted snapshot into a **new** bundle with a **new** `certificateHash`
+3. Stores the original `certificateHash` in `meta.provenance.originalCertificateHash` as an informational cross-reference
+
+```typescript
+import { certifyDecision, exportVerifiableRedacted, verify } from '@nexart/ai-execution';
+
+const original = certifyDecision({ ... });
+
+const { bundle, originalCertificateHash } = exportVerifiableRedacted(
+  original,
+  { paths: ['input', 'output'] },
+);
+
+verify(bundle).ok;                                    // true — new bundle verifies
+bundle.certificateHash !== original.certificateHash;  // true — different hash
+bundle.meta.provenance.originalCertificateHash;       // 'sha256:...' — reference only
+bundle.snapshot.input;                                // { _redacted: true, hash: 'sha256:...' }
+```
+
+**Provenance semantics:** `meta.provenance.originalCertificateHash` is reference metadata only. It is not part of the new `certificateHash` computation. Recipients of the new bundle cannot verify the original bundle's integrity from it — they can only confirm what hash the original had. If you need to prove the original's integrity, keep the original bundle available alongside the redacted one.
+
+**Rule of thumb for choosing a redaction approach:**
+
+| Approach | `verify()` passes | Original hash preserved | Notes |
+|---|---|---|---|
+| `redactBeforeSeal(snapshot, policy)` + `sealCer()` | ✅ | N/A — no original exists yet | Use when building a redacted bundle from scratch |
+| `exportVerifiableRedacted(bundle, policy)` | ✅ | Reference only in `meta.provenance` | Use when you have a sealed bundle and need a shareable sanitized copy |
+| `sanitizeForStorage(bundle, options)` | ❌ | N/A — hash broken by design | Use only for storage; do not pass result to `verify()` |
+
+### Post-hoc redaction breaks integrity — by design
 
-**Rule of thumb:** redact before sealing if you need `verify()` to pass; use `sanitizeForStorage` only for data you do not need to verify later.
+`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, use `exportVerifiableRedacted` instead.
 
 ## Canonical JSON Constraints
 
@@ -515,6 +590,7 @@ Fixtures at `fixtures/vectors/` and `fixtures/golden/`. Cross-language implement
 |---|---|
 | `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+) |
+| `certifyAndAttestRun(steps, options?)` | One-call: create RunBuilder internally, certify all steps, optionally attest each bundle, return `{ runSummary, stepBundles, receipts, finalStepHash }`. Injectable `attestStep` for mocking. |
 
 ### AIEF Interop (v0.7.0+)
 
@@ -525,6 +601,7 @@ Fixtures at `fixtures/vectors/` and `fixtures/golden/`. Cross-language implement
 | `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 |
+| `exportVerifiableRedacted(bundle, policy, options?)` | Post-seal: produce a new sealed bundle with redacted snapshot + `meta.provenance.originalCertificateHash`. `verify()` passes on the new bundle. Original is unchanged. |
 | `validateProfile(target, profile)` | Validate a snapshot or bundle against an AIEF strictness profile (does not affect hashing) |
 
 ### Attestation & Archive
@@ -607,7 +684,8 @@ Priority when multiple failures exist: `CANONICALIZATION_ERROR` > `SCHEMA_ERROR`
 | 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.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 |
+| 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 |
+| **v0.8.0** | Helper APIs: `exportVerifiableRedacted()` (post-seal re-seal with redacted snapshot + provenance metadata); `certifyAndAttestRun()` (one-call multi-step certify + optional per-step attestation with injectable mock); test determinism fix (no time-dependent first-run failures); all v0.1–v0.7 bundles verify identically, no hashing or canonicalization changes |
 | v1.0.0 | Planned: API stabilization, freeze public API surface |
 
 ## Releasing

package/dist/index.cjs

@@ -33,10 +33,12 @@ __export(src_exports, {
   CerAttestationError: () => CerAttestationError,
   CerVerificationError: () => CerVerificationError,
   CerVerifyCode: () => CerVerifyCode,
+  ReasonCode: () => ReasonCode,
   RunBuilder: () => RunBuilder,
   attest: () => attest,
   attestIfNeeded: () => attestIfNeeded,
   certifyAndAttestDecision: () => certifyAndAttestDecision,
+  certifyAndAttestRun: () => certifyAndAttestRun,
   certifyDecision: () => certifyDecision,
   certifyDecisionFromProviderCall: () => certifyDecisionFromProviderCall,
   computeInputHash: () => computeInputHash,
@@ -44,6 +46,7 @@ __export(src_exports, {
   createClient: () => createClient,
   createSnapshot: () => createSnapshot,
   exportCer: () => exportCer,
+  exportVerifiableRedacted: () => exportVerifiableRedacted,
   fetchNodeKeys: () => fetchNodeKeys,
   getAttestationReceipt: () => getAttestationReceipt,
   hasAttestation: () => hasAttestation,
@@ -63,6 +66,7 @@ __export(src_exports, {
   toCanonicalJson: () => toCanonicalJson,
   validateProfile: () => validateProfile,
   verify: () => verifyCer,
+  verifyAiCerBundleDetailed: () => verifyAiCerBundleDetailed,
   verifyAief: () => verifyAief,
   verifyBundleAttestation: () => verifyBundleAttestation,
   verifyCer: () => verifyCer,
@@ -189,7 +193,7 @@ function computeOutputHash(output) {
 }
 
 // src/snapshot.ts
-var PACKAGE_VERSION = "0.7.0";
+var PACKAGE_VERSION = "0.8.0";
 function validateParameters(params) {
   const errors = [];
   if (typeof params.temperature !== "number" || !Number.isFinite(params.temperature)) {
@@ -457,7 +461,7 @@ function certifyDecision(params) {
     conversationId: params.conversationId,
     prevStepHash: params.prevStepHash
   });
-  return sealCer(snapshot, { meta: params.meta });
+  return sealCer(snapshot, { createdAt: params.createdAt, meta: params.meta });
 }
 
 // src/run.ts
@@ -2485,15 +2489,150 @@ function validateProfile(target, profile) {
   }
   return { ok: errors.length === 0, errors };
 }
+
+// src/exportRedacted.ts
+function exportVerifiableRedacted(bundle, policy, options) {
+  const createdAt = options?.createdAt ?? (/* @__PURE__ */ new Date()).toISOString();
+  const redactedSnapshot = redactBeforeSeal(bundle.snapshot, policy);
+  const provenance = {
+    originalCertificateHash: bundle.certificateHash,
+    redactionPolicy: { paths: [...policy.paths] },
+    redactedAt: createdAt
+  };
+  const mergedMeta = {
+    ...bundle.meta,
+    provenance
+  };
+  const newBundle = sealCer(redactedSnapshot, {
+    createdAt,
+    meta: mergedMeta,
+    declaration: bundle.declaration
+  });
+  return {
+    bundle: newBundle,
+    originalCertificateHash: bundle.certificateHash
+  };
+}
+
+// src/runHelper.ts
+async function certifyAndAttestRun(steps, options) {
+  const run = new RunBuilder({
+    runId: options?.runId,
+    workflowId: options?.workflowId,
+    conversationId: options?.conversationId,
+    appId: options?.appId
+  });
+  const stepBundles = [];
+  const receipts = [];
+  for (const stepParams of steps) {
+    const bundle = run.step(stepParams);
+    stepBundles.push(bundle);
+    if (options?.attestStep) {
+      const receipt = await options.attestStep(bundle);
+      receipts.push(receipt);
+    } else {
+      receipts.push(null);
+    }
+  }
+  const runSummary = run.finalize();
+  return {
+    runSummary,
+    stepBundles,
+    receipts,
+    finalStepHash: runSummary.finalStepHash
+  };
+}
+
+// src/cerProtocol.ts
+var ReasonCode = {
+  BUNDLE_HASH_MISMATCH: "BUNDLE_HASH_MISMATCH",
+  NODE_SIGNATURE_INVALID: "NODE_SIGNATURE_INVALID",
+  NODE_SIGNATURE_MISSING: "NODE_SIGNATURE_MISSING",
+  RECEIPT_HASH_MISMATCH: "RECEIPT_HASH_MISMATCH",
+  SCHEMA_VERSION_UNSUPPORTED: "SCHEMA_VERSION_UNSUPPORTED",
+  RECORD_NOT_FOUND: "RECORD_NOT_FOUND",
+  BUNDLE_CORRUPTED: "BUNDLE_CORRUPTED"
+};
+
+// src/verifyDetailed.ts
+function mapCerCodeToReasonCodes(cerCode) {
+  switch (cerCode) {
+    case CerVerifyCode.CERTIFICATE_HASH_MISMATCH:
+    case CerVerifyCode.SNAPSHOT_HASH_MISMATCH:
+    case CerVerifyCode.INPUT_HASH_MISMATCH:
+    case CerVerifyCode.OUTPUT_HASH_MISMATCH:
+      return [ReasonCode.BUNDLE_HASH_MISMATCH];
+    case CerVerifyCode.SCHEMA_ERROR:
+      return [ReasonCode.SCHEMA_VERSION_UNSUPPORTED];
+    case CerVerifyCode.CANONICALIZATION_ERROR:
+    case CerVerifyCode.UNKNOWN_ERROR:
+    case CerVerifyCode.INVALID_SHA256_FORMAT:
+      return [ReasonCode.BUNDLE_CORRUPTED];
+    case CerVerifyCode.ATTESTATION_INVALID_SIGNATURE:
+    case CerVerifyCode.ATTESTATION_KEY_FORMAT_UNSUPPORTED:
+    case CerVerifyCode.ATTESTATION_KEY_NOT_FOUND:
+      return [ReasonCode.NODE_SIGNATURE_INVALID];
+    case CerVerifyCode.ATTESTATION_MISSING:
+      return [ReasonCode.NODE_SIGNATURE_MISSING];
+    default:
+      return [];
+  }
+}
+function verifyAiCerBundleDetailed(bundle) {
+  const verifiedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const verifier = "@nexart/ai-execution";
+  if (!bundle || typeof bundle !== "object" || Array.isArray(bundle)) {
+    return {
+      status: "FAILED",
+      checks: { bundleIntegrity: "FAIL", nodeSignature: "SKIPPED", receiptConsistency: "SKIPPED" },
+      reasonCodes: [ReasonCode.BUNDLE_CORRUPTED],
+      certificateHash: "",
+      bundleType: "",
+      verifiedAt,
+      verifier
+    };
+  }
+  const b = bundle;
+  const bundleType = typeof b["bundleType"] === "string" ? b["bundleType"] : "";
+  const certificateHash = typeof b["certificateHash"] === "string" ? b["certificateHash"] : "";
+  if (bundleType !== "cer.ai.execution.v1") {
+    return {
+      status: "FAILED",
+      checks: { bundleIntegrity: "FAIL", nodeSignature: "SKIPPED", receiptConsistency: "SKIPPED" },
+      reasonCodes: [ReasonCode.SCHEMA_VERSION_UNSUPPORTED],
+      certificateHash,
+      bundleType,
+      verifiedAt,
+      verifier
+    };
+  }
+  const cerResult = verifyCer(bundle);
+  const bundleIntegrity = cerResult.ok ? "PASS" : "FAIL";
+  const attestationPresent = hasAttestation(bundle);
+  const nodeSignature = attestationPresent ? "PASS" : "SKIPPED";
+  const receiptConsistency = attestationPresent ? "PASS" : "SKIPPED";
+  const reasonCodes = cerResult.ok ? [] : mapCerCodeToReasonCodes(cerResult.code);
+  return {
+    status: cerResult.ok ? "VERIFIED" : "FAILED",
+    checks: { bundleIntegrity, nodeSignature, receiptConsistency },
+    reasonCodes,
+    certificateHash,
+    bundleType,
+    verifiedAt,
+    verifier
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CerAttestationError,
   CerVerificationError,
   CerVerifyCode,
+  ReasonCode,
   RunBuilder,
   attest,
   attestIfNeeded,
   certifyAndAttestDecision,
+  certifyAndAttestRun,
   certifyDecision,
   certifyDecisionFromProviderCall,
   computeInputHash,
@@ -2501,6 +2640,7 @@ function validateProfile(target, profile) {
   createClient,
   createSnapshot,
   exportCer,
+  exportVerifiableRedacted,
   fetchNodeKeys,
   getAttestationReceipt,
   hasAttestation,
@@ -2520,6 +2660,7 @@ function validateProfile(target, profile) {
   toCanonicalJson,
   validateProfile,
   verify,
+  verifyAiCerBundleDetailed,
   verifyAief,
   verifyBundleAttestation,
   verifyCer,