@nexart/ai-execution 0.7.0 → 0.8.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

@@ -37,6 +37,7 @@ __export(src_exports, {
   attest: () => attest,
   attestIfNeeded: () => attestIfNeeded,
   certifyAndAttestDecision: () => certifyAndAttestDecision,
+  certifyAndAttestRun: () => certifyAndAttestRun,
   certifyDecision: () => certifyDecision,
   certifyDecisionFromProviderCall: () => certifyDecisionFromProviderCall,
   computeInputHash: () => computeInputHash,
@@ -44,6 +45,7 @@ __export(src_exports, {
   createClient: () => createClient,
   createSnapshot: () => createSnapshot,
   exportCer: () => exportCer,
+  exportVerifiableRedacted: () => exportVerifiableRedacted,
   fetchNodeKeys: () => fetchNodeKeys,
   getAttestationReceipt: () => getAttestationReceipt,
   hasAttestation: () => hasAttestation,
@@ -189,7 +191,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)) {
@@ -2485,6 +2487,59 @@ 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
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CerAttestationError,
@@ -2494,6 +2549,7 @@ function validateProfile(target, profile) {
   attest,
   attestIfNeeded,
   certifyAndAttestDecision,
+  certifyAndAttestRun,
   certifyDecision,
   certifyDecisionFromProviderCall,
   computeInputHash,
@@ -2501,6 +2557,7 @@ function validateProfile(target, profile) {
   createClient,
   createSnapshot,
   exportCer,
+  exportVerifiableRedacted,
   fetchNodeKeys,
   getAttestationReceipt,
   hasAttestation,