@nexart/ai-execution 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { C as CreateSnapshotParams, A as AiExecutionSnapshotV1, V as VerificationResult, a as CerMeta, b as CerAiExecutionBundle, c as CertifyDecisionParams, R as RunBuilderOptions, S as StepParams, d as RunSummary, e as AttestOptions, f as AttestationResult, g as SanitizeStorageOptions, h as AttestationReceipt, N as NodeKeysDocument, i as NodeReceiptVerifyResult, j as SignedAttestationReceipt, k as CerVerifyCode } from './types-Cgb52dTx.cjs';
-export { l as AiExecutionParameters, m as AttestationReceiptResult, n as ClientDefaults, o as NexArtClient, P as ProviderCallParams, p as ProviderCallResult, q as ProviderConfig, W as WrappedExecutionParams, r as WrappedExecutionResult } from './types-Cgb52dTx.cjs';
+import { C as CreateSnapshotParams, A as AiExecutionSnapshotV1, V as VerificationResult, a as CerMeta, B as BundleDeclaration, b as CerAiExecutionBundle, c as CertifyDecisionParams, R as RunBuilderOptions, S as StepParams, d as RunSummary, e as AttestOptions, f as AttestationResult, g as SanitizeStorageOptions, h as AttestationReceipt, N as NodeKeysDocument, i as NodeReceiptVerifyResult, j as SignedAttestationReceipt, k as CerVerifyCode, l as AiefVerifyResult, T as ToolEvent, m as RunSummaryVerifyResult, n as AiefProfile } from './types-CcqCDPrD.cjs';
+export { o as AiExecutionParameters, p as AttestationReceiptResult, q as ClientDefaults, r as NexArtClient, P as ProviderCallParams, s as ProviderCallResult, t as ProviderConfig, u as RedactionEnvelope, W as WrappedExecutionParams, v as WrappedExecutionResult } from './types-CcqCDPrD.cjs';
 export { wrapProvider } from './providers/wrap.cjs';
 
 declare class CerVerificationError extends Error {
@@ -27,6 +27,7 @@ declare function verifySnapshot(snapshot: AiExecutionSnapshotV1): VerificationRe
 declare function sealCer(snapshot: AiExecutionSnapshotV1, options?: {
     createdAt?: string;
     meta?: CerMeta;
+    declaration?: BundleDeclaration;
 }): CerAiExecutionBundle;
 declare function verifyCer(bundle: CerAiExecutionBundle): VerificationResult;
 
@@ -201,4 +202,303 @@ interface NexArtClient {
  */
 declare function createClient(defaults?: ClientDefaults): NexArtClient;
 
-export { AiExecutionSnapshotV1, AttestOptions, AttestationReceipt, AttestationResult, CerAiExecutionBundle, CerAttestationError, CerMeta, CerVerificationError, CerVerifyCode, CerVerifyCode as CerVerifyCodeType, CertifyDecisionParams, CreateSnapshotParams, NodeKeysDocument, NodeReceiptVerifyResult, RunBuilder, RunBuilderOptions, RunSummary, SanitizeStorageOptions, SignedAttestationReceipt, StepParams, VerificationResult, attest, attestIfNeeded, certifyAndAttestDecision, certifyDecision, certifyDecisionFromProviderCall, computeInputHash, computeOutputHash, createClient, createSnapshot, exportCer, fetchNodeKeys, getAttestationReceipt, hasAttestation, hashCanonicalJson, hashUtf8, importCer, sanitizeForAttestation, sanitizeForStamp, sanitizeForStorage, sealCer, selectNodeKey, sha256Hex, toCanonicalJson, verifyCer as verify, verifyBundleAttestation, verifyCer, verifyNodeReceiptSignature, verifySnapshot };
+/**
+ * @nexart/ai-execution — AIEF §9 verifier adapter (v0.7.0)
+ *
+ * Provides verifyAief() which wraps the existing verifyCer() and returns the
+ * exact AIEF §9.1 output schema required for cross-vendor verifier interoperability.
+ *
+ * Existing verify() / verifyCer() output is unchanged — this is additive only.
+ */
+
+/**
+ * Map a NexArt CerVerifyCode to an AIEF §9.2 reason string.
+ * Unknown codes fall back to "malformedArtifact".
+ */
+declare function mapToAiefReason(code: string): string;
+/**
+ * Verify a CER bundle and return the exact AIEF §9.1 output shape.
+ *
+ * This wraps verifyCer() — hashing logic is not duplicated.
+ * The internal NexArt verify() output is unchanged; this is purely an adapter.
+ *
+ * Per AIEF §9.0 rule #7: if chain fields are absent, chainValid MUST be true.
+ */
+declare function verifyAief(bundle: CerAiExecutionBundle): AiefVerifyResult;
+
+/**
+ * @nexart/ai-execution — Level 4 tool/dependency evidence helpers (v0.7.0)
+ *
+ * Provides hashToolOutput() and makeToolEvent() for building AIEF-06 compliant
+ * tool call evidence records to include in AiExecutionSnapshotV1.toolCalls.
+ */
+
+/**
+ * Hash a tool output value for use as `outputHash` in a ToolEvent.
+ *
+ * - string  → SHA-256 of UTF-8 bytes
+ * - anything else → SHA-256 of stable canonical JSON bytes
+ *
+ * Returns "sha256:<64hex>" format.
+ */
+declare function hashToolOutput(value: unknown): string;
+interface MakeToolEventParams {
+    toolId: string;
+    output: unknown;
+    at?: string;
+    input?: unknown;
+    evidenceRef?: string;
+    error?: string;
+}
+/**
+ * Build a ToolEvent record for inclusion in snapshot.toolCalls.
+ *
+ * The outputHash is computed by hashToolOutput(output) so it is always consistent.
+ * Optionally computes inputHash if `input` is provided.
+ * If `at` is omitted, the current time is used.
+ */
+declare function makeToolEvent(params: MakeToolEventParams): ToolEvent;
+
+/**
+ * @nexart/ai-execution — Level 4 chain integrity verification (v0.7.0)
+ *
+ * Provides verifyRunSummary() for validating multi-step RunBuilder outputs against
+ * AIEF-07 requirements: detects insertion, deletion, and reordering of steps.
+ */
+
+interface VerifyRunSummaryOptions {
+    /** Skip per-bundle certificateHash verification (use only if already verified separately). */
+    skipBundleVerification?: boolean;
+}
+/**
+ * Verify that a RunSummary and its corresponding step bundles form a valid,
+ * unbroken cryptographic chain.
+ *
+ * Detects:
+ * - Missing steps  (INCOMPLETE_ARTIFACT)
+ * - Extra steps    (INCOMPLETE_ARTIFACT)
+ * - Reordered steps (CHAIN_BREAK_DETECTED via stepIndex or prevStepHash mismatch)
+ * - Inserted steps (CHAIN_BREAK_DETECTED)
+ * - Deleted steps  (CHAIN_BREAK_DETECTED)
+ * - Summary finalStepHash mismatch (CHAIN_BREAK_DETECTED)
+ *
+ * @param summary     RunSummary from RunBuilder.finalize()
+ * @param bundles     Step bundles in declared order (step 0 first)
+ * @param opts        Options for verification behaviour
+ */
+declare function verifyRunSummary(summary: RunSummary, bundles: CerAiExecutionBundle[], opts?: VerifyRunSummaryOptions): RunSummaryVerifyResult;
+
+/**
+ * @nexart/ai-execution — Pre-seal redaction helpers (v0.7.0)
+ *
+ * redactBeforeSeal() replaces sensitive snapshot fields with stable redaction
+ * envelopes { _redacted: true, hash: "sha256:..." } BEFORE the snapshot is
+ * sealed with sealCer(). The resulting bundle will verify correctly because
+ * the certificateHash was computed over the already-redacted snapshot.
+ *
+ * For `input` and `output` fields, the corresponding `inputHash`/`outputHash`
+ * are recomputed to reflect the envelope (the original value's hash is
+ * preserved inside the envelope itself).
+ *
+ * IMPORTANT: Post-hoc redaction via sanitizeForStorage() breaks certificateHash
+ * by design. Only pre-seal redaction produces verifiable bundles.
+ */
+
+interface RedactBeforeSealPolicy {
+    /** Dot-separated field paths to redact, e.g. ["input", "prompt"]. */
+    paths: string[];
+}
+/**
+ * Replace sensitive snapshot fields with stable redaction envelopes before sealing.
+ *
+ * - For `input`: replaces with envelope and recomputes inputHash from envelope
+ * - For `output`: replaces with envelope and recomputes outputHash from envelope
+ * - For other paths: replaces with envelope (nested paths supported via dot notation)
+ *
+ * The original value's hash is preserved inside the envelope at `envelope.hash`,
+ * providing a trail for authorized reviewers while keeping the raw value private.
+ *
+ * @example
+ * ```typescript
+ * const redactedSnap = redactBeforeSeal(snapshot, { paths: ['input', 'prompt'] });
+ * const bundle = sealCer(redactedSnap);
+ * // verifyCer(bundle) → { ok: true }
+ * ```
+ */
+declare function redactBeforeSeal(snapshot: AiExecutionSnapshotV1, policy: RedactBeforeSealPolicy): AiExecutionSnapshotV1;
+
+/**
+ * @nexart/ai-execution — AIEF profile validation (v0.7.0)
+ *
+ * Profiles add opt-in strictness at creation time — they enforce field
+ * presence and structure only. They NEVER change certificateHash computation.
+ *
+ * Available profiles:
+ *   "flexible"  — No extra validation (default SDK behaviour)
+ *   "AIEF_L2"   — Validates AIEF-01 required fields are present
+ *   "AIEF_L3"   — Same as AIEF_L2 (portability is structural, not field-level)
+ *   "AIEF_L4"   — AIEF_L3 + validates toolCalls fields, prevStepHash for step > 0
+ */
+
+interface ProfileValidationResult {
+    ok: boolean;
+    errors: string[];
+}
+/**
+ * Validate a snapshot or bundle against the given AIEF profile.
+ *
+ * Returns { ok: true, errors: [] } for "flexible".
+ * Does NOT throw — errors are returned in the result.
+ * Does NOT affect hashing or sealing.
+ */
+declare function validateProfile(target: AiExecutionSnapshotV1 | CerAiExecutionBundle, profile: AiefProfile): ProfileValidationResult;
+
+/**
+ * @nexart/ai-execution — Verifiable redacted export helper
+ *
+ * exportVerifiableRedacted() produces a NEW sealed bundle whose snapshot has
+ * sensitive fields replaced with redaction envelopes via redactBeforeSeal().
+ *
+ * The result is a fully independently verifiable bundle with a NEW certificateHash.
+ * The original certificateHash is preserved in meta.provenance as an informational
+ * cross-reference ONLY — it does not establish any cryptographic relationship
+ * between the two bundles.
+ *
+ * verify(newBundle) → { ok: true }   ✅ the new bundle verifies on its own
+ * verify(originalBundle) → { ok: true }  ✅ the original is unaffected
+ *
+ * IMPORTANT CONSTRAINTS:
+ * - Only `input` and `output` paths are safe to redact (their content hashes are
+ *   recomputed from the envelope). Schema-validated string fields like `prompt`
+ *   cannot be replaced with an object envelope — verify() will return SCHEMA_ERROR.
+ * - `meta.provenance.originalCertificateHash` is reference metadata only.
+ *   Anyone who receives only the new bundle cannot verify the original's integrity.
+ */
+
+interface ExportVerifiableRedactedOptions {
+    createdAt?: string;
+}
+interface ExportVerifiableRedactedProvenance {
+    originalCertificateHash: string;
+    redactionPolicy: {
+        paths: string[];
+    };
+    redactedAt: string;
+}
+interface ExportVerifiableRedactedResult {
+    bundle: CerAiExecutionBundle;
+    /**
+     * The original bundle's certificateHash. Convenience alias for
+     * `bundle.meta.provenance.originalCertificateHash`.
+     * Reference only — no cryptographic link to the new bundle.
+     */
+    originalCertificateHash: string;
+}
+/**
+ * Produce a new sealed bundle with redacted snapshot fields.
+ *
+ * @param bundle   The original sealed bundle to redact from.
+ * @param policy   Which snapshot paths to redact. Only 'input' and 'output'
+ *                 are safe for verifiable redaction (their content hashes are
+ *                 recomputed). Other schema-validated string fields will cause
+ *                 verify() to return SCHEMA_ERROR on the new bundle.
+ * @param options  Optional overrides (createdAt).
+ *
+ * @example
+ * ```typescript
+ * import { certifyDecision, verify, exportVerifiableRedacted } from '@nexart/ai-execution';
+ *
+ * const original = certifyDecision({ ... });
+ * const { bundle, originalCertificateHash } = exportVerifiableRedacted(
+ *   original,
+ *   { paths: ['input', 'output'] },
+ * );
+ *
+ * verify(bundle).ok;                                    // true
+ * bundle.meta.provenance.originalCertificateHash;       // 'sha256:...' — reference only
+ * bundle.snapshot.input;                                // { _redacted: true, hash: 'sha256:...' }
+ * ```
+ */
+declare function exportVerifiableRedacted(bundle: CerAiExecutionBundle, policy: RedactBeforeSealPolicy, options?: ExportVerifiableRedactedOptions): ExportVerifiableRedactedResult;
+
+/**
+ * @nexart/ai-execution — Opinionated run helper
+ *
+ * certifyAndAttestRun(): certify every step in a multi-step run via RunBuilder,
+ * optionally attest each sealed bundle, and return a consolidated result.
+ *
+ * Design principles:
+ * - Does NOT mutate or wrap any externally-owned RunBuilder. Creates its own.
+ * - RunBuilder semantics are unchanged: prevStepHash chaining is automatic.
+ * - attestStep is optional and injectable so callers can mock in tests without
+ *   hitting the network.
+ * - Network failures from attestStep bubble up — wrap in try/catch for partial
+ *   failure tolerance.
+ */
+
+interface CertifyAndAttestRunOptions {
+    runId?: string;
+    workflowId?: string | null;
+    conversationId?: string | null;
+    appId?: string | null;
+    /**
+     * Optional per-step attestation function. Receives each sealed step bundle
+     * immediately after it is created. Return an AttestationReceipt on success.
+     *
+     * If omitted, all receipts will be null (bundles are sealed but not attested).
+     *
+     * @example
+     * ```typescript
+     * import { attest } from '@nexart/ai-execution';
+     * certifyAndAttestRun(steps, {
+     *   attestStep: (bundle) => attest(bundle, { nodeUrl, apiKey }),
+     * });
+     * ```
+     */
+    attestStep?: (bundle: CerAiExecutionBundle) => Promise<AttestationReceipt>;
+}
+interface CertifyAndAttestRunResult {
+    runSummary: RunSummary;
+    stepBundles: CerAiExecutionBundle[];
+    /**
+     * Attestation receipts in step order. `null` at index i means the step
+     * was sealed but not attested (no `attestStep` option was provided).
+     */
+    receipts: (AttestationReceipt | null)[];
+    /** Alias for runSummary.finalStepHash — the last step's certificateHash. */
+    finalStepHash: string | null;
+}
+/**
+ * Certify every step in a multi-step run and optionally attest each bundle.
+ *
+ * Each step is sealed via RunBuilder, which automatically:
+ * - assigns stepIndex (0-based)
+ * - sets prevStepHash to the previous step's certificateHash
+ * - assigns a unique executionId and stepId per step
+ *
+ * The resulting runSummary + stepBundles can be validated offline with
+ * verifyRunSummary(runSummary, stepBundles).
+ *
+ * @param steps    Ordered list of step parameters (step 0 first).
+ * @param options  Run-level options and optional attestation hook.
+ *
+ * @example
+ * ```typescript
+ * import { certifyAndAttestRun, verifyRunSummary } from '@nexart/ai-execution';
+ *
+ * const { runSummary, stepBundles, receipts, finalStepHash } =
+ *   await certifyAndAttestRun(
+ *     [step0Params, step1Params, step2Params],
+ *     {
+ *       runId: 'analysis-run',
+ *       workflowId: 'data-pipeline',
+ *       attestStep: (bundle) => attest(bundle, { nodeUrl, apiKey }),
+ *     },
+ *   );
+ *
+ * verifyRunSummary(runSummary, stepBundles); // { ok: true }
+ * ```
+ */
+declare function certifyAndAttestRun(steps: StepParams[], options?: CertifyAndAttestRunOptions): Promise<CertifyAndAttestRunResult>;
+
+export { AiExecutionSnapshotV1, AiefProfile, AiefVerifyResult, AttestOptions, AttestationReceipt, AttestationResult, BundleDeclaration, CerAiExecutionBundle, CerAttestationError, CerMeta, CerVerificationError, CerVerifyCode, CerVerifyCode as CerVerifyCodeType, type CertifyAndAttestRunOptions, type CertifyAndAttestRunResult, CertifyDecisionParams, CreateSnapshotParams, type ExportVerifiableRedactedOptions, type ExportVerifiableRedactedProvenance, type ExportVerifiableRedactedResult, type MakeToolEventParams, NodeKeysDocument, NodeReceiptVerifyResult, type ProfileValidationResult, type RedactBeforeSealPolicy, RunBuilder, RunBuilderOptions, RunSummary, RunSummaryVerifyResult, SanitizeStorageOptions, SignedAttestationReceipt, StepParams, ToolEvent, VerificationResult, type VerifyRunSummaryOptions, attest, attestIfNeeded, certifyAndAttestDecision, certifyAndAttestRun, certifyDecision, certifyDecisionFromProviderCall, computeInputHash, computeOutputHash, createClient, createSnapshot, exportCer, exportVerifiableRedacted, fetchNodeKeys, getAttestationReceipt, hasAttestation, hashCanonicalJson, hashToolOutput, hashUtf8, importCer, makeToolEvent, mapToAiefReason, redactBeforeSeal, sanitizeForAttestation, sanitizeForStamp, sanitizeForStorage, sealCer, selectNodeKey, sha256Hex, toCanonicalJson, validateProfile, verifyCer as verify, verifyAief, verifyBundleAttestation, verifyCer, verifyNodeReceiptSignature, verifyRunSummary, verifySnapshot };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as CreateSnapshotParams, A as AiExecutionSnapshotV1, V as VerificationResult, a as CerMeta, b as CerAiExecutionBundle, c as CertifyDecisionParams, R as RunBuilderOptions, S as StepParams, d as RunSummary, e as AttestOptions, f as AttestationResult, g as SanitizeStorageOptions, h as AttestationReceipt, N as NodeKeysDocument, i as NodeReceiptVerifyResult, j as SignedAttestationReceipt, k as CerVerifyCode } from './types-Cgb52dTx.js';
-export { l as AiExecutionParameters, m as AttestationReceiptResult, n as ClientDefaults, o as NexArtClient, P as ProviderCallParams, p as ProviderCallResult, q as ProviderConfig, W as WrappedExecutionParams, r as WrappedExecutionResult } from './types-Cgb52dTx.js';
+import { C as CreateSnapshotParams, A as AiExecutionSnapshotV1, V as VerificationResult, a as CerMeta, B as BundleDeclaration, b as CerAiExecutionBundle, c as CertifyDecisionParams, R as RunBuilderOptions, S as StepParams, d as RunSummary, e as AttestOptions, f as AttestationResult, g as SanitizeStorageOptions, h as AttestationReceipt, N as NodeKeysDocument, i as NodeReceiptVerifyResult, j as SignedAttestationReceipt, k as CerVerifyCode, l as AiefVerifyResult, T as ToolEvent, m as RunSummaryVerifyResult, n as AiefProfile } from './types-CcqCDPrD.js';
+export { o as AiExecutionParameters, p as AttestationReceiptResult, q as ClientDefaults, r as NexArtClient, P as ProviderCallParams, s as ProviderCallResult, t as ProviderConfig, u as RedactionEnvelope, W as WrappedExecutionParams, v as WrappedExecutionResult } from './types-CcqCDPrD.js';
 export { wrapProvider } from './providers/wrap.js';
 
 declare class CerVerificationError extends Error {
@@ -27,6 +27,7 @@ declare function verifySnapshot(snapshot: AiExecutionSnapshotV1): VerificationRe
 declare function sealCer(snapshot: AiExecutionSnapshotV1, options?: {
     createdAt?: string;
     meta?: CerMeta;
+    declaration?: BundleDeclaration;
 }): CerAiExecutionBundle;
 declare function verifyCer(bundle: CerAiExecutionBundle): VerificationResult;
 
@@ -201,4 +202,303 @@ interface NexArtClient {
  */
 declare function createClient(defaults?: ClientDefaults): NexArtClient;
 
-export { AiExecutionSnapshotV1, AttestOptions, AttestationReceipt, AttestationResult, CerAiExecutionBundle, CerAttestationError, CerMeta, CerVerificationError, CerVerifyCode, CerVerifyCode as CerVerifyCodeType, CertifyDecisionParams, CreateSnapshotParams, NodeKeysDocument, NodeReceiptVerifyResult, RunBuilder, RunBuilderOptions, RunSummary, SanitizeStorageOptions, SignedAttestationReceipt, StepParams, VerificationResult, attest, attestIfNeeded, certifyAndAttestDecision, certifyDecision, certifyDecisionFromProviderCall, computeInputHash, computeOutputHash, createClient, createSnapshot, exportCer, fetchNodeKeys, getAttestationReceipt, hasAttestation, hashCanonicalJson, hashUtf8, importCer, sanitizeForAttestation, sanitizeForStamp, sanitizeForStorage, sealCer, selectNodeKey, sha256Hex, toCanonicalJson, verifyCer as verify, verifyBundleAttestation, verifyCer, verifyNodeReceiptSignature, verifySnapshot };
+/**
+ * @nexart/ai-execution — AIEF §9 verifier adapter (v0.7.0)
+ *
+ * Provides verifyAief() which wraps the existing verifyCer() and returns the
+ * exact AIEF §9.1 output schema required for cross-vendor verifier interoperability.
+ *
+ * Existing verify() / verifyCer() output is unchanged — this is additive only.
+ */
+
+/**
+ * Map a NexArt CerVerifyCode to an AIEF §9.2 reason string.
+ * Unknown codes fall back to "malformedArtifact".
+ */
+declare function mapToAiefReason(code: string): string;
+/**
+ * Verify a CER bundle and return the exact AIEF §9.1 output shape.
+ *
+ * This wraps verifyCer() — hashing logic is not duplicated.
+ * The internal NexArt verify() output is unchanged; this is purely an adapter.
+ *
+ * Per AIEF §9.0 rule #7: if chain fields are absent, chainValid MUST be true.
+ */
+declare function verifyAief(bundle: CerAiExecutionBundle): AiefVerifyResult;
+
+/**
+ * @nexart/ai-execution — Level 4 tool/dependency evidence helpers (v0.7.0)
+ *
+ * Provides hashToolOutput() and makeToolEvent() for building AIEF-06 compliant
+ * tool call evidence records to include in AiExecutionSnapshotV1.toolCalls.
+ */
+
+/**
+ * Hash a tool output value for use as `outputHash` in a ToolEvent.
+ *
+ * - string  → SHA-256 of UTF-8 bytes
+ * - anything else → SHA-256 of stable canonical JSON bytes
+ *
+ * Returns "sha256:<64hex>" format.
+ */
+declare function hashToolOutput(value: unknown): string;
+interface MakeToolEventParams {
+    toolId: string;
+    output: unknown;
+    at?: string;
+    input?: unknown;
+    evidenceRef?: string;
+    error?: string;
+}
+/**
+ * Build a ToolEvent record for inclusion in snapshot.toolCalls.
+ *
+ * The outputHash is computed by hashToolOutput(output) so it is always consistent.
+ * Optionally computes inputHash if `input` is provided.
+ * If `at` is omitted, the current time is used.
+ */
+declare function makeToolEvent(params: MakeToolEventParams): ToolEvent;
+
+/**
+ * @nexart/ai-execution — Level 4 chain integrity verification (v0.7.0)
+ *
+ * Provides verifyRunSummary() for validating multi-step RunBuilder outputs against
+ * AIEF-07 requirements: detects insertion, deletion, and reordering of steps.
+ */
+
+interface VerifyRunSummaryOptions {
+    /** Skip per-bundle certificateHash verification (use only if already verified separately). */
+    skipBundleVerification?: boolean;
+}
+/**
+ * Verify that a RunSummary and its corresponding step bundles form a valid,
+ * unbroken cryptographic chain.
+ *
+ * Detects:
+ * - Missing steps  (INCOMPLETE_ARTIFACT)
+ * - Extra steps    (INCOMPLETE_ARTIFACT)
+ * - Reordered steps (CHAIN_BREAK_DETECTED via stepIndex or prevStepHash mismatch)
+ * - Inserted steps (CHAIN_BREAK_DETECTED)
+ * - Deleted steps  (CHAIN_BREAK_DETECTED)
+ * - Summary finalStepHash mismatch (CHAIN_BREAK_DETECTED)
+ *
+ * @param summary     RunSummary from RunBuilder.finalize()
+ * @param bundles     Step bundles in declared order (step 0 first)
+ * @param opts        Options for verification behaviour
+ */
+declare function verifyRunSummary(summary: RunSummary, bundles: CerAiExecutionBundle[], opts?: VerifyRunSummaryOptions): RunSummaryVerifyResult;
+
+/**
+ * @nexart/ai-execution — Pre-seal redaction helpers (v0.7.0)
+ *
+ * redactBeforeSeal() replaces sensitive snapshot fields with stable redaction
+ * envelopes { _redacted: true, hash: "sha256:..." } BEFORE the snapshot is
+ * sealed with sealCer(). The resulting bundle will verify correctly because
+ * the certificateHash was computed over the already-redacted snapshot.
+ *
+ * For `input` and `output` fields, the corresponding `inputHash`/`outputHash`
+ * are recomputed to reflect the envelope (the original value's hash is
+ * preserved inside the envelope itself).
+ *
+ * IMPORTANT: Post-hoc redaction via sanitizeForStorage() breaks certificateHash
+ * by design. Only pre-seal redaction produces verifiable bundles.
+ */
+
+interface RedactBeforeSealPolicy {
+    /** Dot-separated field paths to redact, e.g. ["input", "prompt"]. */
+    paths: string[];
+}
+/**
+ * Replace sensitive snapshot fields with stable redaction envelopes before sealing.
+ *
+ * - For `input`: replaces with envelope and recomputes inputHash from envelope
+ * - For `output`: replaces with envelope and recomputes outputHash from envelope
+ * - For other paths: replaces with envelope (nested paths supported via dot notation)
+ *
+ * The original value's hash is preserved inside the envelope at `envelope.hash`,
+ * providing a trail for authorized reviewers while keeping the raw value private.
+ *
+ * @example
+ * ```typescript
+ * const redactedSnap = redactBeforeSeal(snapshot, { paths: ['input', 'prompt'] });
+ * const bundle = sealCer(redactedSnap);
+ * // verifyCer(bundle) → { ok: true }
+ * ```
+ */
+declare function redactBeforeSeal(snapshot: AiExecutionSnapshotV1, policy: RedactBeforeSealPolicy): AiExecutionSnapshotV1;
+
+/**
+ * @nexart/ai-execution — AIEF profile validation (v0.7.0)
+ *
+ * Profiles add opt-in strictness at creation time — they enforce field
+ * presence and structure only. They NEVER change certificateHash computation.
+ *
+ * Available profiles:
+ *   "flexible"  — No extra validation (default SDK behaviour)
+ *   "AIEF_L2"   — Validates AIEF-01 required fields are present
+ *   "AIEF_L3"   — Same as AIEF_L2 (portability is structural, not field-level)
+ *   "AIEF_L4"   — AIEF_L3 + validates toolCalls fields, prevStepHash for step > 0
+ */
+
+interface ProfileValidationResult {
+    ok: boolean;
+    errors: string[];
+}
+/**
+ * Validate a snapshot or bundle against the given AIEF profile.
+ *
+ * Returns { ok: true, errors: [] } for "flexible".
+ * Does NOT throw — errors are returned in the result.
+ * Does NOT affect hashing or sealing.
+ */
+declare function validateProfile(target: AiExecutionSnapshotV1 | CerAiExecutionBundle, profile: AiefProfile): ProfileValidationResult;
+
+/**
+ * @nexart/ai-execution — Verifiable redacted export helper
+ *
+ * exportVerifiableRedacted() produces a NEW sealed bundle whose snapshot has
+ * sensitive fields replaced with redaction envelopes via redactBeforeSeal().
+ *
+ * The result is a fully independently verifiable bundle with a NEW certificateHash.
+ * The original certificateHash is preserved in meta.provenance as an informational
+ * cross-reference ONLY — it does not establish any cryptographic relationship
+ * between the two bundles.
+ *
+ * verify(newBundle) → { ok: true }   ✅ the new bundle verifies on its own
+ * verify(originalBundle) → { ok: true }  ✅ the original is unaffected
+ *
+ * IMPORTANT CONSTRAINTS:
+ * - Only `input` and `output` paths are safe to redact (their content hashes are
+ *   recomputed from the envelope). Schema-validated string fields like `prompt`
+ *   cannot be replaced with an object envelope — verify() will return SCHEMA_ERROR.
+ * - `meta.provenance.originalCertificateHash` is reference metadata only.
+ *   Anyone who receives only the new bundle cannot verify the original's integrity.
+ */
+
+interface ExportVerifiableRedactedOptions {
+    createdAt?: string;
+}
+interface ExportVerifiableRedactedProvenance {
+    originalCertificateHash: string;
+    redactionPolicy: {
+        paths: string[];
+    };
+    redactedAt: string;
+}
+interface ExportVerifiableRedactedResult {
+    bundle: CerAiExecutionBundle;
+    /**
+     * The original bundle's certificateHash. Convenience alias for
+     * `bundle.meta.provenance.originalCertificateHash`.
+     * Reference only — no cryptographic link to the new bundle.
+     */
+    originalCertificateHash: string;
+}
+/**
+ * Produce a new sealed bundle with redacted snapshot fields.
+ *
+ * @param bundle   The original sealed bundle to redact from.
+ * @param policy   Which snapshot paths to redact. Only 'input' and 'output'
+ *                 are safe for verifiable redaction (their content hashes are
+ *                 recomputed). Other schema-validated string fields will cause
+ *                 verify() to return SCHEMA_ERROR on the new bundle.
+ * @param options  Optional overrides (createdAt).
+ *
+ * @example
+ * ```typescript
+ * import { certifyDecision, verify, exportVerifiableRedacted } from '@nexart/ai-execution';
+ *
+ * const original = certifyDecision({ ... });
+ * const { bundle, originalCertificateHash } = exportVerifiableRedacted(
+ *   original,
+ *   { paths: ['input', 'output'] },
+ * );
+ *
+ * verify(bundle).ok;                                    // true
+ * bundle.meta.provenance.originalCertificateHash;       // 'sha256:...' — reference only
+ * bundle.snapshot.input;                                // { _redacted: true, hash: 'sha256:...' }
+ * ```
+ */
+declare function exportVerifiableRedacted(bundle: CerAiExecutionBundle, policy: RedactBeforeSealPolicy, options?: ExportVerifiableRedactedOptions): ExportVerifiableRedactedResult;
+
+/**
+ * @nexart/ai-execution — Opinionated run helper
+ *
+ * certifyAndAttestRun(): certify every step in a multi-step run via RunBuilder,
+ * optionally attest each sealed bundle, and return a consolidated result.
+ *
+ * Design principles:
+ * - Does NOT mutate or wrap any externally-owned RunBuilder. Creates its own.
+ * - RunBuilder semantics are unchanged: prevStepHash chaining is automatic.
+ * - attestStep is optional and injectable so callers can mock in tests without
+ *   hitting the network.
+ * - Network failures from attestStep bubble up — wrap in try/catch for partial
+ *   failure tolerance.
+ */
+
+interface CertifyAndAttestRunOptions {
+    runId?: string;
+    workflowId?: string | null;
+    conversationId?: string | null;
+    appId?: string | null;
+    /**
+     * Optional per-step attestation function. Receives each sealed step bundle
+     * immediately after it is created. Return an AttestationReceipt on success.
+     *
+     * If omitted, all receipts will be null (bundles are sealed but not attested).
+     *
+     * @example
+     * ```typescript
+     * import { attest } from '@nexart/ai-execution';
+     * certifyAndAttestRun(steps, {
+     *   attestStep: (bundle) => attest(bundle, { nodeUrl, apiKey }),
+     * });
+     * ```
+     */
+    attestStep?: (bundle: CerAiExecutionBundle) => Promise<AttestationReceipt>;
+}
+interface CertifyAndAttestRunResult {
+    runSummary: RunSummary;
+    stepBundles: CerAiExecutionBundle[];
+    /**
+     * Attestation receipts in step order. `null` at index i means the step
+     * was sealed but not attested (no `attestStep` option was provided).
+     */
+    receipts: (AttestationReceipt | null)[];
+    /** Alias for runSummary.finalStepHash — the last step's certificateHash. */
+    finalStepHash: string | null;
+}
+/**
+ * Certify every step in a multi-step run and optionally attest each bundle.
+ *
+ * Each step is sealed via RunBuilder, which automatically:
+ * - assigns stepIndex (0-based)
+ * - sets prevStepHash to the previous step's certificateHash
+ * - assigns a unique executionId and stepId per step
+ *
+ * The resulting runSummary + stepBundles can be validated offline with
+ * verifyRunSummary(runSummary, stepBundles).
+ *
+ * @param steps    Ordered list of step parameters (step 0 first).
+ * @param options  Run-level options and optional attestation hook.
+ *
+ * @example
+ * ```typescript
+ * import { certifyAndAttestRun, verifyRunSummary } from '@nexart/ai-execution';
+ *
+ * const { runSummary, stepBundles, receipts, finalStepHash } =
+ *   await certifyAndAttestRun(
+ *     [step0Params, step1Params, step2Params],
+ *     {
+ *       runId: 'analysis-run',
+ *       workflowId: 'data-pipeline',
+ *       attestStep: (bundle) => attest(bundle, { nodeUrl, apiKey }),
+ *     },
+ *   );
+ *
+ * verifyRunSummary(runSummary, stepBundles); // { ok: true }
+ * ```
+ */
+declare function certifyAndAttestRun(steps: StepParams[], options?: CertifyAndAttestRunOptions): Promise<CertifyAndAttestRunResult>;
+
+export { AiExecutionSnapshotV1, AiefProfile, AiefVerifyResult, AttestOptions, AttestationReceipt, AttestationResult, BundleDeclaration, CerAiExecutionBundle, CerAttestationError, CerMeta, CerVerificationError, CerVerifyCode, CerVerifyCode as CerVerifyCodeType, type CertifyAndAttestRunOptions, type CertifyAndAttestRunResult, CertifyDecisionParams, CreateSnapshotParams, type ExportVerifiableRedactedOptions, type ExportVerifiableRedactedProvenance, type ExportVerifiableRedactedResult, type MakeToolEventParams, NodeKeysDocument, NodeReceiptVerifyResult, type ProfileValidationResult, type RedactBeforeSealPolicy, RunBuilder, RunBuilderOptions, RunSummary, RunSummaryVerifyResult, SanitizeStorageOptions, SignedAttestationReceipt, StepParams, ToolEvent, VerificationResult, type VerifyRunSummaryOptions, attest, attestIfNeeded, certifyAndAttestDecision, certifyAndAttestRun, certifyDecision, certifyDecisionFromProviderCall, computeInputHash, computeOutputHash, createClient, createSnapshot, exportCer, exportVerifiableRedacted, fetchNodeKeys, getAttestationReceipt, hasAttestation, hashCanonicalJson, hashToolOutput, hashUtf8, importCer, makeToolEvent, mapToAiefReason, redactBeforeSeal, sanitizeForAttestation, sanitizeForStamp, sanitizeForStorage, sealCer, selectNodeKey, sha256Hex, toCanonicalJson, validateProfile, verifyCer as verify, verifyAief, verifyBundleAttestation, verifyCer, verifyNodeReceiptSignature, verifyRunSummary, verifySnapshot };