@nexart/ai-execution 0.10.0 → 0.12.0

package/README.md

@@ -1,4 +1,4 @@
-# @nexart/ai-execution v0.10.0
+# @nexart/ai-execution v0.12.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.10.0 |
+| SDK | 0.12.0 |
 | Protocol | 1.2.0 |
 
 ## Why Not Just Store Logs?
@@ -22,6 +22,7 @@ This package creates integrity records for AI executions. Every time you call an
 - What you got back (output)
 - The exact parameters used (temperature, model, etc.)
 - SHA-256 hashes of everything for tamper detection
+- Optionally: upstream context signals from other systems, sealed into the same certificate hash (v0.10.0+)
 
 These records can be verified offline to detect any post-hoc modification and prove integrity of the recorded execution.
 
@@ -168,6 +169,13 @@ Auto-generated fields (set by `createSnapshot`, do not set manually): `type`, `p
   "createdAt": "2026-02-12T00:00:00.000Z",
   "version": "0.1",
   "snapshot": { "..." : "..." },
+  "context": {
+    "signals": [
+      { "type": "approval", "source": "github-actions", "step": 0,
+        "timestamp": "2026-02-12T00:00:00.000Z", "actor": "alice",
+        "status": "ok", "payload": { "pr": 42 } }
+    ]
+  },
   "meta": { "source": "my-app", "tags": ["production"] },
   "declaration": {
     "stabilitySchemeId": "nexart-cer-v1",
@@ -178,9 +186,13 @@ Auto-generated fields (set by `createSnapshot`, do not set manually): `type`, `p
 }
 ```
 
+`context` is **optional** and only appears when signals are supplied. Bundles without `context` are structurally identical to all prior versions.
+
 ### Certificate Hash Computation
 
-The `certificateHash` is SHA-256 of the UTF-8 bytes of the canonical JSON of exactly: `{ bundleType, version, createdAt, snapshot }`. `meta` and `declaration` are excluded. Key-ordering is recursive. This computation is identical across all SDK versions.
+The `certificateHash` is SHA-256 of the UTF-8 bytes of the canonical JSON of exactly: `{ bundleType, version, createdAt, snapshot }` — or, when context signals are present: `{ bundleType, version, createdAt, snapshot, context }`. `meta` and `declaration` are always excluded. Key-ordering is recursive. This computation is identical across all SDK versions.
+
+**Context and backward compatibility:** when no signals are provided (or an empty array is passed), `context` is omitted from the hash payload entirely. The resulting `certificateHash` is byte-for-byte identical to a pre-v0.10.0 bundle with the same snapshot. Passing signals is strictly additive — it can only extend the hash, never break it for existing callers.
 
 ### Declaration Block (v0.7.0+)
 
@@ -201,6 +213,78 @@ const bundle = sealCer(snapshot, {
 // verifyCer(bundle).ok === true — declaration does not affect the result
 ```
 
+## CER Packages (v0.12.0+)
+
+A **CER package** is a transport/export envelope that wraps a sealed `cer.ai.execution.v1` bundle with optional receipt, signature, and attestation metadata.
+
+```
+{
+  "cer": { ...sealed cer.ai.execution.v1 bundle... },
+  "receipt":  { ...optional attestation receipt... },
+  "signature": "base64url...",
+  "attestation": { ...optional attestation summary... },
+  "verificationEnvelope": { ...optional envelope metadata... },
+  "verificationEnvelopeSignature": "base64url..."
+}
+```
+
+**When to use package helpers vs raw bundle helpers**
+
+| Use case | Recommended API |
+|---|---|
+| Creating, verifying, or archiving a CER locally | `certifyDecision`, `verifyCer`, `exportCer` / `importCer` (raw bundle) |
+| Wrapping a CER for transport or external storage with optional metadata | `createCerPackage`, `exportCerPackage`, `importCerPackage` |
+| Detecting whether an object is a package or a raw bundle | `isCerPackage` |
+| Extracting the CER from a received package | `getCerFromPackage` |
+| Verifying integrity of a received package's inner CER | `verifyCerPackage` |
+
+The `cer` field inside a package is authoritative. Package helpers never mutate it, never re-hash it, and never inject package-level fields into the CER.
+
+### Creating and exporting a package
+
+```typescript
+import { certifyDecision, createCerPackage, exportCerPackage } from '@nexart/ai-execution';
+
+const cer = certifyDecision({
+  provider: 'openai',
+  model: 'gpt-4o',
+  prompt: 'Summarize.',
+  input: userQuery,
+  output: llmResponse,
+  parameters: { temperature: 0.7, maxTokens: 1024, topP: null, seed: null },
+});
+
+const pkg = createCerPackage({
+  cer,
+  receipt: myAttestationReceipt, // optional
+  signature: 'base64url...',     // optional
+});
+
+const json = exportCerPackage(pkg); // stable canonical JSON
+```
+
+### Importing and verifying a package
+
+```typescript
+import { importCerPackage, verifyCerPackage, getCerFromPackage } from '@nexart/ai-execution';
+
+// importCerPackage parses + validates shape + verifies inner CER hash
+const pkg = importCerPackage(receivedJsonString); // throws CerVerificationError on failure
+
+// Alternatively: parse yourself then verify
+const result = verifyCerPackage(parsedObj);
+if (!result.ok) throw new Error(result.errors.join('; '));
+
+const cer = getCerFromPackage(parsedObj); // throws if not a valid package
+```
+
+**Design constraints of package helpers:**
+- Additive only — no changes to CER hashing, canonicalization, or `verifyCer()` semantics
+- `verifyCerPackage` only verifies the inner `cer` bundle; receipt/signature/envelope fields are opaque transport metadata not verified here
+- All existing raw bundle flows (`importCer`, `exportCer`, `verifyCer`) are unchanged
+
+---
+
 ## Attestation
 
 Endpoint: `POST {nodeUrl}/api/attest`
@@ -582,7 +666,7 @@ Fixtures at `fixtures/vectors/` and `fixtures/golden/`. Cross-language implement
 | `verifySnapshot(snapshot)` | Verify snapshot hashes and structure |
 | `sealCer(snapshot, options?)` | Seal snapshot into CER bundle |
 | `verify(bundle)` / `verifyCer(bundle)` | Verify CER bundle |
-| `certifyDecision(params)` | One-call: createSnapshot + sealCer |
+| `certifyDecision(params)` | One-call: createSnapshot + sealCer. Accepts optional `signals?: CerContextSignal[]` — included in `certificateHash` when present (v0.10.0+) |
 
 ### Workflow
 
@@ -623,6 +707,19 @@ Fixtures at `fixtures/vectors/` and `fixtures/golden/`. Cross-language implement
 | `exportCer(bundle)` | Serialize to canonical JSON string |
 | `importCer(json)` | Parse + verify from JSON string |
 
+### CER Package Helpers (v0.12.0+)
+
+| Function | Description |
+|---|---|
+| `isCerPackage(value)` | Type guard: returns `true` if `value` is a CER package shape (`{ cer: { bundleType: 'cer.ai.execution.v1', ... }, ... }`). Structural check only — does not verify the inner CER hash. |
+| `createCerPackage(params)` | Assemble a CER package from a sealed CER and optional transport fields (`receipt`, `signature`, `attestation`, `verificationEnvelope`, `verificationEnvelopeSignature`). Assembly only — does not re-hash or re-sign. |
+| `getCerFromPackage(pkg)` | Extract and return the inner CER bundle. Throws `CerVerificationError` if `pkg` is not a valid package shape. |
+| `exportCerPackage(pkg)` | Serialize a CER package to a stable canonical JSON string. |
+| `importCerPackage(json)` | Parse a CER package JSON string, validate its shape, and verify the inner CER with `verifyCer()`. Throws `CerVerificationError` on any failure. |
+| `verifyCerPackage(pkg)` | Verify the inner CER of a package using `verifyCer()`. Returns a `VerificationResult`. Conservative: only verifies the inner `cer` — does not verify receipt/signature/envelope. |
+
+**Exported types:** `AiCerPackage`, `CreateCerPackageParams`
+
 ### Provider Drop-in (v0.6.0+)
 
 | Function | Description |
@@ -674,7 +771,7 @@ Priority when multiple failures exist: `CANONICALIZATION_ERROR` > `SCHEMA_ERROR`
 
 ## 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.
+`@nexart/ai-execution` includes a minimal LangChain helper surface (introduced v0.10.0, current v0.12.0). 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:
 
@@ -747,6 +844,8 @@ console.log(result.receipt);
 
 ### Three helpers
 
+All three helpers accept an optional `signals?: CerContextSignal[]` field on their input. When provided, signals are sealed into `bundle.context` and included in `certificateHash`. Omitting signals produces a hash identical to a bundle without signals.
+
 | Helper | Returns | Network |
 |---|---|---|
 | `createLangChainCer(input)` | `LangChainCerResult` (sync) | Never |
@@ -834,6 +933,99 @@ const result = await certifyLangChainRun(
 
 ---
 
+## Context Signals (v0.10.0+)
+
+CERs can optionally include **context signals** — structured, protocol-agnostic records of upstream events that were present when the AI execution ran. Signals are evidence-only: they have no effect on how the AI call is made, what parameters are used, or how the output is processed. Their only role is to be bound into the `certificateHash` alongside the execution record so that any post-hoc modification to either the signals or the snapshot is detectable.
+
+**What signals are:**
+- Records of things that happened before or alongside the AI call (approvals, deploys, audits, tool invocations, review outcomes, etc.)
+- Protocol-agnostic — `type`, `source`, `actor`, and `payload` are all free-form strings and objects
+- Included in `certificateHash` only when present — omitting signals produces a hash identical to pre-v0.10.0
+
+**What signals are not:**
+- Governance enforcement — NexArt does not interpret signal content or enforce policy based on it
+- Execution dependencies — signals do not gate or modify the AI call in any way
+- A replacement for `toolCalls` — `toolCalls` records tool invocations *within* a run; signals record upstream context *around* a run
+
+### Quick example
+
+```ts
+import { createSignalCollector } from '@nexart/signals';
+import { certifyDecision, verifyCer } from '@nexart/ai-execution';
+
+// 1. Collect upstream signals during your pipeline run
+const collector = createSignalCollector({ defaultSource: 'github-actions' });
+collector.add({ type: 'approval', actor: 'alice', status: 'ok', payload: { pr: 42 } });
+collector.add({ type: 'deploy',   actor: 'ci-bot', status: 'ok', payload: { env: 'prod' } });
+const { signals } = collector.export();
+
+// 2. Certify the AI execution with signals bound as context evidence
+const bundle = certifyDecision({
+  provider: 'openai',
+  model: 'gpt-4o-mini',
+  prompt: 'Summarise.',
+  input: userQuery,
+  output: llmResponse,
+  parameters: { temperature: 0, maxTokens: 512, topP: null, seed: null },
+  signals,  // ← included in certificateHash; omit to get identical hash as before
+});
+
+verifyCer(bundle).ok;               // true
+console.log(bundle.context?.signals.length); // 2 — signals are sealed in the bundle
+```
+
+`NexArtSignal[]` from `@nexart/signals` is structurally identical to `CerContextSignal[]` — no casting or conversion needed. `@nexart/ai-execution` has no hard dependency on `@nexart/signals`; any object matching the `CerContextSignal` shape works.
+
+### Signals also work on the LangChain path
+
+```ts
+import { certifyLangChainRun } from '@nexart/ai-execution';
+
+const { bundle } = certifyLangChainRun({
+  provider: 'openai',
+  model: 'gpt-4o-mini',
+  input: { messages: [...] },
+  output: { text: '...' },
+  signals,  // ← same field, same semantics
+});
+```
+
+### CerContextSignal shape
+
+Every `CerContextSignal` has the following fields. All are always present in the stored bundle — no undefined values:
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `type` | `string` | required | Signal category — free-form (e.g. `"approval"`, `"deploy"`, `"audit"`) |
+| `source` | `string` | required | Upstream system — free-form (e.g. `"github-actions"`, `"linear"`) |
+| `step` | `number` | `0` | Position in sequence — used for ordering within the `context.signals` array |
+| `timestamp` | `string` | current time | ISO 8601 |
+| `actor` | `string` | `"unknown"` | Who produced the signal — free-form |
+| `status` | `string` | `"ok"` | Outcome — free-form (e.g. `"ok"`, `"error"`, `"pending"`) |
+| `payload` | `Record<string, unknown>` | `{}` | Opaque upstream data — NexArt does not interpret this |
+
+Signal ordering within the array is part of the sealed hash. Reordering signals produces a different `certificateHash`.
+
+### Tamper detection
+
+`verifyCer()` always reconstructs `context` from the stored `bundle.context.signals` when recomputing the hash. Any mutation — changing a signal field, adding or removing signals, or injecting a `context` block into a no-signals bundle — produces a `CERTIFICATE_HASH_MISMATCH` result:
+
+```ts
+const tampered = { ...bundle, context: { signals: [...altered] } };
+verifyCer(tampered).ok;   // false
+verifyCer(tampered).code; // 'CERTIFICATE_HASH_MISMATCH'
+```
+
+### Exported types
+
+```ts
+import type { CerContextSignal, CerContext } from '@nexart/ai-execution';
+```
+
+`CerContext` is the shape of `bundle.context` — `{ signals: CerContextSignal[] }`. Both are exported from the package root.
+
+---
+
 ## Version History
 
 | Version | Description |
@@ -849,7 +1041,9 @@ const result = await certifyLangChainRun(
 | 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; 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 |
+| 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. **Context signals:** optional `signals?: CerContextSignal[]` on `certifyDecision`, `certifyLangChainRun`, and `createLangChainCer` — sealed into `bundle.context` and included in `certificateHash` when non-empty; absent or empty = hash unchanged from pre-v0.10.0. New types: `CerContextSignal`, `CerContext`. New example: `examples/signals-cer.ts`. 413 total tests; all prior bundles verify identically |
+| v0.11.0 | Version release. Ships all v0.10.0 features (LangChain integration + context signals) as the published package version. `cerSignals.test.js` added to the `npm test` script. No API, hash, or canonicalization changes |
+| **v0.12.0** | CER package helpers: `isCerPackage`, `createCerPackage`, `getCerFromPackage`, `exportCerPackage`, `importCerPackage`, `verifyCerPackage`. New types: `AiCerPackage`, `CreateCerPackageParams`. Additive only — no changes to CER hashing, canonicalization, or verification semantics. 466 total tests; all prior bundles verify identically |
 | v1.0.0 | Planned: API stabilization, freeze public API surface |
 
 ## Releasing

package/dist/index.cjs

@@ -44,18 +44,23 @@ __export(src_exports, {
   certifyLangChainRun: () => certifyLangChainRun,
   computeInputHash: () => computeInputHash,
   computeOutputHash: () => computeOutputHash,
+  createCerPackage: () => createCerPackage,
   createClient: () => createClient,
   createLangChainCer: () => createLangChainCer,
   createSnapshot: () => createSnapshot,
   exportCer: () => exportCer,
+  exportCerPackage: () => exportCerPackage,
   exportVerifiableRedacted: () => exportVerifiableRedacted,
   fetchNodeKeys: () => fetchNodeKeys,
   getAttestationReceipt: () => getAttestationReceipt,
+  getCerFromPackage: () => getCerFromPackage,
   hasAttestation: () => hasAttestation,
   hashCanonicalJson: () => hashCanonicalJson,
   hashToolOutput: () => hashToolOutput,
   hashUtf8: () => hashUtf8,
   importCer: () => importCer,
+  importCerPackage: () => importCerPackage,
+  isCerPackage: () => isCerPackage,
   makeToolEvent: () => makeToolEvent,
   mapToAiefReason: () => mapToAiefReason,
   redactBeforeSeal: () => redactBeforeSeal,
@@ -72,6 +77,7 @@ __export(src_exports, {
   verifyAief: () => verifyAief,
   verifyBundleAttestation: () => verifyBundleAttestation,
   verifyCer: () => verifyCer,
+  verifyCerPackage: () => verifyCerPackage,
   verifyNodeReceiptSignature: () => verifyNodeReceiptSignature,
   verifyRunSummary: () => verifyRunSummary,
   verifySnapshot: () => verifySnapshot,
@@ -339,14 +345,22 @@ function computeCertificateHash(payload) {
   const canonical = toCanonicalJson(payload);
   return `sha256:${sha256Hex(canonical)}`;
 }
+function buildContext(signals) {
+  if (!signals || signals.length === 0) return void 0;
+  return { signals };
+}
 function sealCer(snapshot, options) {
   const createdAt = options?.createdAt ?? (/* @__PURE__ */ new Date()).toISOString();
+  const context = buildContext(options?.signals);
   const payload = {
     bundleType: "cer.ai.execution.v1",
     createdAt,
     snapshot,
     version: "0.1"
   };
+  if (context) {
+    payload.context = context;
+  }
   const certificateHash = computeCertificateHash(payload);
   const bundle = {
     bundleType: "cer.ai.execution.v1",
@@ -355,6 +369,9 @@ function sealCer(snapshot, options) {
     version: "0.1",
     snapshot
   };
+  if (context) {
+    bundle.context = context;
+  }
   if (options?.meta) {
     bundle.meta = options.meta;
   }
@@ -403,6 +420,10 @@ function verifyCer(bundle) {
       snapshot: bundle.snapshot,
       version: "0.1"
     };
+    const verifyContext = buildContext(bundle.context?.signals);
+    if (verifyContext) {
+      payload.context = verifyContext;
+    }
     const expectedHash = computeCertificateHash(payload);
     if (bundle.certificateHash !== expectedHash) {
       certHashErrors.push(`certificateHash mismatch: expected ${expectedHash}, got ${bundle.certificateHash}`);
@@ -463,7 +484,11 @@ function certifyDecision(params) {
     conversationId: params.conversationId,
     prevStepHash: params.prevStepHash
   });
-  return sealCer(snapshot, { createdAt: params.createdAt, meta: params.meta });
+  return sealCer(snapshot, {
+    createdAt: params.createdAt,
+    meta: params.meta,
+    signals: params.signals
+  });
 }
 
 // src/run.ts
@@ -2688,7 +2713,8 @@ function buildCertifyParams(input, executionId) {
     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)
+    meta: buildMeta(input.metadata),
+    signals: input.signals
   };
 }
 function createLangChainCer(input) {
@@ -2717,6 +2743,67 @@ function certifyLangChainRun(input, _options) {
   }
   return createLangChainCer(input);
 }
+
+// src/package.ts
+function isCerPackage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const pkg = value;
+  if (typeof pkg["cer"] !== "object" || pkg["cer"] === null) return false;
+  const cer = pkg["cer"];
+  return cer["bundleType"] === "cer.ai.execution.v1";
+}
+function createCerPackage(params) {
+  const pkg = { cer: params.cer };
+  if (params.receipt !== void 0) pkg.receipt = params.receipt;
+  if (params.signature !== void 0) pkg.signature = params.signature;
+  if (params.attestation !== void 0) pkg.attestation = params.attestation;
+  if (params.verificationEnvelope !== void 0) pkg.verificationEnvelope = params.verificationEnvelope;
+  if (params.verificationEnvelopeSignature !== void 0) pkg.verificationEnvelopeSignature = params.verificationEnvelopeSignature;
+  return pkg;
+}
+function getCerFromPackage(pkg) {
+  if (!isCerPackage(pkg)) {
+    throw new CerVerificationError([
+      "getCerFromPackage: value is not a valid CER package (missing or invalid cer field)"
+    ]);
+  }
+  return pkg.cer;
+}
+function exportCerPackage(pkg) {
+  return toCanonicalJson(pkg);
+}
+function importCerPackage(json) {
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch (err2) {
+    throw new CerVerificationError([
+      `importCerPackage: invalid JSON: ${err2.message}`
+    ]);
+  }
+  if (!isCerPackage(parsed)) {
+    throw new CerVerificationError([
+      "importCerPackage: parsed value is not a CER package (missing or invalid cer field)"
+    ]);
+  }
+  const result = verifyCer(parsed.cer);
+  if (!result.ok) {
+    throw new CerVerificationError([
+      `importCerPackage: inner CER failed verification: ${result.errors.join("; ")}`
+    ]);
+  }
+  return parsed;
+}
+function verifyCerPackage(pkg) {
+  if (!isCerPackage(pkg)) {
+    return {
+      ok: false,
+      errors: ["verifyCerPackage: value is not a CER package (missing or invalid cer field)"],
+      code: CerVerifyCode.SCHEMA_ERROR
+    };
+  }
+  return verifyCer(pkg.cer);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CerAttestationError,
@@ -2733,18 +2820,23 @@ function certifyLangChainRun(input, _options) {
   certifyLangChainRun,
   computeInputHash,
   computeOutputHash,
+  createCerPackage,
   createClient,
   createLangChainCer,
   createSnapshot,
   exportCer,
+  exportCerPackage,
   exportVerifiableRedacted,
   fetchNodeKeys,
   getAttestationReceipt,
+  getCerFromPackage,
   hasAttestation,
   hashCanonicalJson,
   hashToolOutput,
   hashUtf8,
   importCer,
+  importCerPackage,
+  isCerPackage,
   makeToolEvent,
   mapToAiefReason,
   redactBeforeSeal,
@@ -2761,6 +2853,7 @@ function certifyLangChainRun(input, _options) {
   verifyAief,
   verifyBundleAttestation,
   verifyCer,
+  verifyCerPackage,
   verifyNodeReceiptSignature,
   verifyRunSummary,
   verifySnapshot,