Signals SDK

npm install @nexart/signals

import { createContext } from '@nexart/signals';

const ctx = createContext();

ctx.step('fetch', { url });
ctx.step('transform');
ctx.step('store');

await ctx.certify({
  provider: 'openai',
  model:    'gpt-4o-mini',
  input,
  output,
});

import { createSignal, createSignalCollector } from '@nexart/signals';

const collector = createSignalCollector({ defaultSource: 'my-pipeline' });

collector.add({ type: 'fetch',     payload: { url: '...' } });
collector.add({ type: 'transform', actor: 'etl-bot' });
collector.add({ type: 'store',     status: 'ok' });

const collection = collector.export();
// { signals: [...], count: 3, exportedAt: '2026-...' }

const collector = createSignalCollector({ deterministic: true });

collector.add({
  type: 'approval',
  source: 'ci',
  step: 0,                                  // required in deterministic mode
  timestamp: '2026-03-17T00:00:00.000Z',    // required in deterministic mode
});

collector.lock();
collector.add({ /* ... */ });   // throws: 'cannot add() after lock()'

collector.export();             // still works
collector.exportWithHash();     // still works
collector.validate();           // still works
collector.locked;               // true

import { hashSignals, validateSignals } from '@nexart/signals';

const contextHash = hashSignals(collection.signals);
// 'sha256:9f3c...' — stable across environments

const { ok, errors } = validateSignals(restoredSignals);
if (!ok) throw new Error(errors.join('; '));

// Or both at once:
const { signals, count, exportedAt, contextHash: h } = collector.exportWithHash();

collector.findByType('approval');
collector.findByStep(2);
collector.filter({ type: 'deploy', status: 'ok' });
collector.filter((s) => s.payload.severity === 'high');

import { diffSignals } from '@nexart/signals';

const { added, removed, changed } = diffSignals(before, after);
// added:   signals in 'b' whose step is not in 'a'
// removed: signals in 'a' whose step is not in 'b'
// changed: signals at the same step whose canonical content differs

import { createExecutionContext } from '@nexart/signals';

const ctx = createExecutionContext({ signals: collector.export().signals });

ctx.signals;        // sorted by step, frozen array
ctx.contextHash;    // 'sha256:...' — stable across runs and machines
ctx.createdAt;      // ISO 8601 of construction
ctx.validate();     // { ok, errors }
ctx.equals(other);  // hash-based equality
ctx.toJSON();       // canonical, portable snapshot

import { exportContext, importContext, compareContexts } from '@nexart/signals';

// Persist
const snapshot = exportContext(ctx);
fs.writeFileSync('ctx.json', JSON.stringify(snapshot));

// Replay (tamper-detection runs automatically)
const restored = importContext(fs.readFileSync('ctx.json', 'utf8'));
restored.equals(ctx);     // true

// Compare
const r = compareContexts(ctx, restored);
// { equal, hashEqual, diff: { added, removed, changed } }

import {
  assertContextDeterministic,
  freezeContext,
} from '@nexart/signals';

// Throws on validation errors or hash mismatch
assertContextDeterministic(ctx);

// Deep-freeze signals + payloads (recursive). Idempotent.
const frozen = freezeContext(ctx);

// Canonical signing payload — excludes createdAt
const payload = ctx.signaturePayload();

// Lightweight overview for UI surfaces
ctx.summary();
// { count, types: { approval: 1, deploy: 1 }, stepRange: { min, max } }

const ctx = createContext();

// Convenience form
ctx.step('approval', { actor: 'alice', approved: true });
ctx.step('deploy',   { env: 'prod' });
ctx.step('verify');

// Power-user form (full CreateSignalInput)
ctx.step({
  type:   'review',
  source: 'github',
  actor:  'bob',
  status: 'pending',
  payload: { pr: 42 },
});

ctx.signals     // current signal array, sorted by step
ctx.hash        // canonical contextHash
ctx.size        // count
ctx.locked      // boolean
ctx.lock()      // freeze the underlying collector
ctx.snapshot()  // → immutable ExecutionContext (v0.5)

const result = await ctx.wrap('llm_call', async () => {
  return await openai.chat(...);
});
// emits llm_call.start, then llm_call.end with { status, duration_ms }
// re-throws errors after emitting end with status='error'

// Manual span
const span = ctx.start('tool_call', { name: 'search' });
try {
  const results = await search(query);
  span.end({ status: 'ok', payload: { count: results.length } });
} catch (e) {
  span.end({ status: 'error' });
  throw e;
}

ctx.input({ q: 'who is the user' });
ctx.tool('search', { query: 'foo' });
ctx.decision('route', { selected: 'fraud-check' });
ctx.output({ answer: '...' });

const bundle = await ctx.certify({
  provider:   'openai',
  model:      'gpt-4o-mini',
  input,
  output,
  parameters: { temperature: 0, maxTokens: 1024, topP: null, seed: null },
});

// For tests or full decoupling, inject a custom certifier
await ctx.certify(
  { provider, model, input, output },
  { certifier: (params) => myCustomCertify(params) },
);

// Optional pre-freeze for tamper-evident handoff
await ctx.certify(decisionInput, { freeze: true });

const view = ctx.debug();
// {
//   count, hash, types: { fetch: 1, ... },
//   timeline: [{ step, type, timestamp, status, actor, source }, ...]
// }

ctx.print();
// ExecutionContext (3 signals)
//   hash: sha256:...
//   types: fetch=1, transform=1, store=1
//   timeline:
//     [  0] 2026-04-26T...  fetch      status=ok  actor=agent  source=agent

import {
  createSignalCollector,
  hashSignals,
  validateSignals,
  diffSignals,
} from '@nexart/signals';

// ── Capture ────────────────────────────────────────────────
const c = createSignalCollector({ deterministic: true });

c.add({ type: 'approval', source: 'gh', step: 0, timestamp: '2026-03-17T00:00:00.000Z', actor: 'alice', payload: { pr: 42 } });
c.add({ type: 'deploy',   source: 'ci', step: 1, timestamp: '2026-03-17T00:01:00.000Z', actor: 'ci-bot', payload: { env: 'prod' } });

c.lock();

const v = c.validate();
if (!v.ok) throw new Error(v.errors.join('; '));

const { signals, contextHash } = c.exportWithHash();

// ── Persist 'signals' and 'contextHash' somewhere ──────────

// ── Later: verify nothing was tampered with ────────────────
if (hashSignals(signals) !== contextHash) {
  throw new Error('Signal collection has been tampered with');
}

// ── Compare against a prior run ────────────────────────────
const diff = diffSignals(previousSignals, signals);
console.log(`+${diff.added.length} -${diff.removed.length} ~${diff.changed.length}`);

import { createSignalCollector } from '@nexart/signals';
import { certifyDecision, verifyCer } from '@nexart/ai-execution';

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();

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,
});

verifyCer(bundle).ok;            // true
bundle.context?.signals.length;  // 2