@nexart/ai-execution 0.8.0 → 0.10.0

package/README.md

@@ -1,4 +1,4 @@
-# @nexart/ai-execution v0.8.0
+# @nexart/ai-execution v0.10.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.8.0 |
+| SDK | 0.10.0 |
 | Protocol | 1.2.0 |
 
 ## Why Not Just Store Logs?
@@ -672,6 +672,168 @@ Priority when multiple failures exist: `CANONICALIZATION_ERROR` > `SCHEMA_ERROR`
 | `runAnthropicExecution` | `@nexart/ai-execution/providers/anthropic` |
 | `wrapProvider` | `@nexart/ai-execution/providers/wrap` |
 
+## LangChain Integration
+
+`@nexart/ai-execution` v0.10.0 includes a minimal LangChain helper surface. Certify the final input and output of any LangChain chain, agent, or runnable as a tamper-evident CER — no LangChain package dependency required.
+
+`certifyLangChainRun` operates in two modes depending on whether `nodeUrl` and `apiKey` are supplied:
+
+| Mode | How to call | Returns |
+|---|---|---|
+| **Local** (default) | No `nodeUrl` / `apiKey` | `LangChainCerResult` (sync) |
+| **Node-attested** | `nodeUrl` + `apiKey` on input | `Promise<LangChainAttestedResult>` |
+
+### Mode 1 — Local CER creation (synchronous, no network)
+
+`createLangChainCer` is always local. `certifyLangChainRun` without `nodeUrl`/`apiKey` is identical.
+
+```ts
+import { createLangChainCer, certifyLangChainRun } from '@nexart/ai-execution';
+// or: import { ... } from '@nexart/ai-execution/langchain';
+
+// Using createLangChainCer — always explicit about local-only behaviour
+const { bundle, certificateHash, executionId } = createLangChainCer({
+  executionId: 'run-001',           // optional — UUID generated if omitted
+  provider: 'openai',
+  model: 'gpt-4o-mini',
+  input: { messages: [{ role: 'user', content: 'What is the capital of France?' }] },
+  output: { text: 'Paris.' },
+  metadata: { appId: 'my-app', projectId: 'docs-bot' },
+  parameters: { temperature: 0, maxTokens: 200, topP: null, seed: null },
+  createdAt: new Date().toISOString(),  // pin for deterministic hash
+});
+
+console.log(certificateHash); // sha256:...
+
+// certifyLangChainRun without nodeUrl/apiKey: identical, sync
+const { bundle: b2 } = certifyLangChainRun({
+  provider: 'openai', model: 'gpt-4o-mini',
+  input: { messages: [{ role: 'user', content: 'Summarise this.' }] },
+  output: { text: 'Summary...' },
+});
+```
+
+### Mode 2 — Node-attested certification (async)
+
+Add `nodeUrl` and `apiKey` to the same input to route through the existing `certifyAndAttestDecision()` path. The function returns a `Promise<LangChainAttestedResult>` with the `receipt` from the NexArt node.
+
+```ts
+import { certifyLangChainRun } from '@nexart/ai-execution';
+
+const result = await certifyLangChainRun({
+  executionId: 'run-001',
+  provider: 'openai',
+  model: 'gpt-4o-mini',
+  input: { messages: [{ role: 'user', content: 'What is the capital of France?' }] },
+  output: { text: 'Paris.' },
+  metadata: { appId: 'my-app', projectId: 'docs-bot' },
+  createdAt: new Date().toISOString(),
+  nodeUrl: 'https://node.nexart.io',   // ← triggers attested mode
+  apiKey: process.env.NEXART_API_KEY!, // ← required with nodeUrl
+});
+
+console.log(result.certificateHash);   // sha256:... (same semantics as local)
+console.log(result.attested);          // true
+console.log(result.receipt);
+// {
+//   attestationId:   "nxa_attest_...",
+//   certificateHash: "sha256:...",
+//   nodeRuntimeHash: "sha256:...",
+//   protocolVersion: "1.2.0"
+// }
+```
+
+`result.bundle` passes `verifyCer()` identically to local mode — the `certificateHash` covers only the CER content, not the receipt fields.
+
+### Three helpers
+
+| Helper | Returns | Network |
+|---|---|---|
+| `createLangChainCer(input)` | `LangChainCerResult` (sync) | Never |
+| `certifyLangChainRun(input)` without `nodeUrl`/`apiKey` | `LangChainCerResult` (sync) | Never |
+| `certifyLangChainRun({ ...input, nodeUrl, apiKey })` | `Promise<LangChainAttestedResult>` | Yes — NexArt node |
+
+### Result types
+
+```ts
+interface LangChainCerResult {
+  bundle:          CerAiExecutionBundle;
+  certificateHash: string;
+  executionId:     string;
+}
+
+interface LangChainAttestedResult extends LangChainCerResult {
+  receipt:  AttestationReceipt;
+  attested: true;
+}
+```
+
+### Input normalization
+
+| Input shape | Stored in CER as |
+|---|---|
+| `string` | `string` (pass-through) |
+| Plain object `{}` | `Record<string, unknown>` (pass-through) |
+| Array `[]` | `{ items: [...] }` |
+| Anything else | `String(value)` |
+
+### Prompt extraction
+
+Resolved in this order: `metadata.prompt` → `input.messages[0].content` → `input.prompt` → `input.text` → `"[LangChain run]"`.
+
+### Metadata mapping
+
+| Metadata key | Mapped to |
+|---|---|
+| `appId` | `snapshot.appId` |
+| `runId` | `snapshot.runId` |
+| `workflowId` | `snapshot.workflowId` |
+| `conversationId` | `snapshot.conversationId` |
+| `prompt` | Used as the CER `prompt` field |
+| All other keys | `bundle.meta.tags` (as `"key:value"` strings) |
+
+### Verification
+
+Bundles from all three helpers are fully protocol-aligned:
+
+```ts
+import { verifyCer, verifyAiCerBundleDetailed } from '@nexart/ai-execution';
+
+const basic    = verifyCer(bundle);
+// { ok: true, code: 'OK' }
+
+const detailed = verifyAiCerBundleDetailed(bundle);
+// { status: 'VERIFIED', checks: { bundleIntegrity: 'PASS', nodeSignature: 'SKIPPED' }, ... }
+```
+
+### Testing the attested path without a network
+
+Use the injectable `_attestFn` test option (same pattern as `certifyAndAttestRun`'s `attestStep`):
+
+```ts
+import type { AttestDecisionFn } from '@nexart/ai-execution';
+
+const mockAttest: AttestDecisionFn = async (params, _opts) => {
+  const { certifyDecision } = await import('@nexart/ai-execution');
+  const bundle = certifyDecision(params);
+  return { bundle, receipt: { attestationId: 'mock-123', certificateHash: bundle.certificateHash,
+    nodeRuntimeHash: 'sha256:' + 'beef'.repeat(16), protocolVersion: '1.2.0' } };
+};
+
+const result = await certifyLangChainRun(
+  { ...input, nodeUrl: 'https://node.nexart.io', apiKey: 'nxa_test' },
+  { _attestFn: mockAttest },
+);
+```
+
+### V3 roadmap (not yet implemented)
+
+- `BaseCallbackHandler` integration for automatic mid-chain CER capture at `onLLMEnd`
+- LangSmith trace correlation via `metadata.runId` → `snapshot.conversationId`
+- Separate `@nexart/langchain` package once the callback surface is proven in production
+
+---
+
 ## Version History
 
 | Version | Description |
@@ -685,7 +847,9 @@ Priority when multiple failures exist: `CANONICALIZATION_ERROR` > `SCHEMA_ERROR`
 | 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.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 |
+| 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; all v0.1–v0.7 bundles verify identically |
+| v0.9.0 | CER Protocol types: `CerVerificationResult`, `ReasonCode`, `CheckStatus`; `verifyAiCerBundleDetailed()`; `CertifyDecisionParams.createdAt` wired through; determinism bug fix |
+| **v0.10.0** | LangChain integration: `createLangChainCer()` (sync/local); `certifyLangChainRun()` dual-mode — local (sync) or node-attested (`Promise<LangChainAttestedResult>` when `nodeUrl`+`apiKey` supplied); `LangChainAttestedResult`, `AttestDecisionFn`; injectable `_attestFn` for test mocking; `@nexart/ai-execution/langchain` subpath; 47 tests (was 34); all prior bundles verify identically |
 | v1.0.0 | Planned: API stabilization, freeze public API surface |
 
 ## Releasing

package/dist/index.cjs

@@ -33,6 +33,7 @@ __export(src_exports, {
   CerAttestationError: () => CerAttestationError,
   CerVerificationError: () => CerVerificationError,
   CerVerifyCode: () => CerVerifyCode,
+  ReasonCode: () => ReasonCode,
   RunBuilder: () => RunBuilder,
   attest: () => attest,
   attestIfNeeded: () => attestIfNeeded,
@@ -40,9 +41,11 @@ __export(src_exports, {
   certifyAndAttestRun: () => certifyAndAttestRun,
   certifyDecision: () => certifyDecision,
   certifyDecisionFromProviderCall: () => certifyDecisionFromProviderCall,
+  certifyLangChainRun: () => certifyLangChainRun,
   computeInputHash: () => computeInputHash,
   computeOutputHash: () => computeOutputHash,
   createClient: () => createClient,
+  createLangChainCer: () => createLangChainCer,
   createSnapshot: () => createSnapshot,
   exportCer: () => exportCer,
   exportVerifiableRedacted: () => exportVerifiableRedacted,
@@ -65,6 +68,7 @@ __export(src_exports, {
   toCanonicalJson: () => toCanonicalJson,
   validateProfile: () => validateProfile,
   verify: () => verifyCer,
+  verifyAiCerBundleDetailed: () => verifyAiCerBundleDetailed,
   verifyAief: () => verifyAief,
   verifyBundleAttestation: () => verifyBundleAttestation,
   verifyCer: () => verifyCer,
@@ -459,7 +463,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
@@ -2540,11 +2544,185 @@ async function certifyAndAttestRun(steps, options) {
     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
+  };
+}
+
+// src/langchain.ts
+var crypto6 = __toESM(require("crypto"), 1);
+function normalizeCerValue(value) {
+  if (typeof value === "string") return value;
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    return value;
+  }
+  if (Array.isArray(value)) return { items: value };
+  return String(value);
+}
+function extractPrompt(input, metadata) {
+  if (typeof metadata?.prompt === "string" && metadata.prompt.length > 0) {
+    return metadata.prompt;
+  }
+  if (input !== null && typeof input === "object" && !Array.isArray(input)) {
+    const obj = input;
+    if (Array.isArray(obj.messages) && obj.messages.length > 0) {
+      const first = obj.messages[0];
+      if (typeof first?.content === "string" && first.content.length > 0) {
+        return first.content;
+      }
+    }
+    if (typeof obj.prompt === "string" && obj.prompt.length > 0) return obj.prompt;
+    if (typeof obj.text === "string" && obj.text.length > 0) return obj.text;
+  }
+  if (typeof input === "string" && input.length > 0) return input;
+  return "[LangChain run]";
+}
+function buildMeta(metadata) {
+  if (!metadata || Object.keys(metadata).length === 0) return void 0;
+  const reserved = /* @__PURE__ */ new Set(["prompt", "appId", "runId", "workflowId", "conversationId"]);
+  const extraTags = [];
+  for (const [k, v] of Object.entries(metadata)) {
+    if (!reserved.has(k)) {
+      extraTags.push(typeof v === "string" ? `${k}:${v}` : `${k}:${JSON.stringify(v)}`);
+    }
+  }
+  return extraTags.length > 0 ? { tags: extraTags } : void 0;
+}
+function resolveParameters(params) {
+  return {
+    temperature: params?.temperature ?? 0,
+    maxTokens: params?.maxTokens ?? 0,
+    topP: params?.topP ?? null,
+    seed: params?.seed ?? null
+  };
+}
+function buildCertifyParams(input, executionId) {
+  return {
+    executionId,
+    timestamp: input.timestamp,
+    createdAt: input.createdAt,
+    provider: input.provider,
+    model: input.model,
+    modelVersion: input.modelVersion ?? null,
+    prompt: extractPrompt(input.input, input.metadata),
+    input: normalizeCerValue(input.input),
+    output: normalizeCerValue(input.output),
+    parameters: resolveParameters(input.parameters),
+    appId: typeof input.metadata?.appId === "string" ? input.metadata.appId : null,
+    runId: typeof input.metadata?.runId === "string" ? input.metadata.runId : void 0,
+    workflowId: typeof input.metadata?.workflowId === "string" ? input.metadata.workflowId : void 0,
+    conversationId: typeof input.metadata?.conversationId === "string" ? input.metadata.conversationId : void 0,
+    meta: buildMeta(input.metadata)
+  };
+}
+function createLangChainCer(input) {
+  const executionId = input.executionId ?? crypto6.randomUUID();
+  const bundle = certifyDecision(buildCertifyParams(input, executionId));
+  return {
+    bundle,
+    certificateHash: bundle.certificateHash,
+    executionId: bundle.snapshot.executionId
+  };
+}
+function certifyLangChainRun(input, _options) {
+  if (input.nodeUrl && input.apiKey) {
+    const executionId = input.executionId ?? crypto6.randomUUID();
+    const certifyParams = buildCertifyParams({ ...input, executionId }, executionId);
+    const attestFn = _options?._attestFn ?? certifyAndAttestDecision;
+    return attestFn(certifyParams, { nodeUrl: input.nodeUrl, apiKey: input.apiKey }).then(
+      ({ bundle, receipt }) => ({
+        bundle,
+        receipt,
+        certificateHash: bundle.certificateHash,
+        executionId: bundle.snapshot.executionId,
+        attested: true
+      })
+    );
+  }
+  return createLangChainCer(input);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CerAttestationError,
   CerVerificationError,
   CerVerifyCode,
+  ReasonCode,
   RunBuilder,
   attest,
   attestIfNeeded,
@@ -2552,9 +2730,11 @@ async function certifyAndAttestRun(steps, options) {
   certifyAndAttestRun,
   certifyDecision,
   certifyDecisionFromProviderCall,
+  certifyLangChainRun,
   computeInputHash,
   computeOutputHash,
   createClient,
+  createLangChainCer,
   createSnapshot,
   exportCer,
   exportVerifiableRedacted,
@@ -2577,6 +2757,7 @@ async function certifyAndAttestRun(steps, options) {
   toCanonicalJson,
   validateProfile,
   verify,
+  verifyAiCerBundleDetailed,
   verifyAief,
   verifyBundleAttestation,
   verifyCer,