@nexart/ai-execution 0.10.0 → 0.11.0

package/README.md

@@ -1,4 +1,4 @@
-# @nexart/ai-execution v0.10.0
+# @nexart/ai-execution v0.11.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.11.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+)
 
@@ -582,7 +594,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
 
@@ -674,7 +686,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.11.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 +759,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 +848,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 +956,8 @@ 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 |
 | v1.0.0 | Planned: API stabilization, freeze public API surface |
 
 ## Releasing

package/dist/index.cjs

@@ -339,14 +339,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 +363,9 @@ function sealCer(snapshot, options) {
     version: "0.1",
     snapshot
   };
+  if (context) {
+    bundle.context = context;
+  }
   if (options?.meta) {
     bundle.meta = options.meta;
   }
@@ -403,6 +414,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 +478,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 +2707,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) {