@nexart/ai-execution 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -353,4 +353,152 @@ interface ProfileValidationResult {
  */
 declare function validateProfile(target: AiExecutionSnapshotV1 | CerAiExecutionBundle, profile: AiefProfile): ProfileValidationResult;
 
-export { AiExecutionSnapshotV1, AiefProfile, AiefVerifyResult, AttestOptions, AttestationReceipt, AttestationResult, BundleDeclaration, CerAiExecutionBundle, CerAttestationError, CerMeta, CerVerificationError, CerVerifyCode, CerVerifyCode as CerVerifyCodeType, CertifyDecisionParams, CreateSnapshotParams, type MakeToolEventParams, NodeKeysDocument, NodeReceiptVerifyResult, type ProfileValidationResult, type RedactBeforeSealPolicy, RunBuilder, RunBuilderOptions, RunSummary, RunSummaryVerifyResult, SanitizeStorageOptions, SignedAttestationReceipt, StepParams, ToolEvent, VerificationResult, type VerifyRunSummaryOptions, attest, attestIfNeeded, certifyAndAttestDecision, certifyDecision, certifyDecisionFromProviderCall, computeInputHash, computeOutputHash, createClient, createSnapshot, exportCer, 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 };
+/**
+ * @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

@@ -353,4 +353,152 @@ interface ProfileValidationResult {
  */
 declare function validateProfile(target: AiExecutionSnapshotV1 | CerAiExecutionBundle, profile: AiefProfile): ProfileValidationResult;
 
-export { AiExecutionSnapshotV1, AiefProfile, AiefVerifyResult, AttestOptions, AttestationReceipt, AttestationResult, BundleDeclaration, CerAiExecutionBundle, CerAttestationError, CerMeta, CerVerificationError, CerVerifyCode, CerVerifyCode as CerVerifyCodeType, CertifyDecisionParams, CreateSnapshotParams, type MakeToolEventParams, NodeKeysDocument, NodeReceiptVerifyResult, type ProfileValidationResult, type RedactBeforeSealPolicy, RunBuilder, RunBuilderOptions, RunSummary, RunSummaryVerifyResult, SanitizeStorageOptions, SignedAttestationReceipt, StepParams, ToolEvent, VerificationResult, type VerifyRunSummaryOptions, attest, attestIfNeeded, certifyAndAttestDecision, certifyDecision, certifyDecisionFromProviderCall, computeInputHash, computeOutputHash, createClient, createSnapshot, exportCer, 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 };
+/**
+ * @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.mjs

@@ -114,7 +114,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)) {
@@ -2410,6 +2410,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
+  };
+}
 export {
   CerAttestationError,
   CerVerificationError,
@@ -2418,6 +2471,7 @@ export {
   attest,
   attestIfNeeded,
   certifyAndAttestDecision,
+  certifyAndAttestRun,
   certifyDecision,
   certifyDecisionFromProviderCall,
   computeInputHash,
@@ -2425,6 +2479,7 @@ export {
   createClient,
   createSnapshot,
   exportCer,
+  exportVerifiableRedacted,
   fetchNodeKeys,
   getAttestationReceipt,
   hasAttestation,