@nexart/signals 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## v0.1.0
+
+> Initial release. Fully independent of `@nexart/ai-execution` — no shared dependencies.
+
+- **`createSignal(input)`**: normalizes a `CreateSignalInput` into a fully-populated `NexArtSignal`. Only `type` and `source` are required. All other fields default safely (`step: 0`, `actor: "unknown"`, `status: "ok"`, `payload: {}`, `timestamp: now`). No undefined values in output.
+
+- **`createSignalCollector(options?)`**: ordered signal buffer. Auto-assigns step values in insertion order when signals omit `step`. Supports `defaultSource` and `defaultActor` collector-level options. `export()` sorts by step and is non-destructive. `size` property for quick count.
+
+- **Types**: `NexArtSignal`, `CreateSignalInput`, `CollectorOptions`, `SignalCollection`, `SignalCollector` — all exported from package root.
+
+- **Build**: dual ESM/CJS with tsup, full TypeScript declaration files.
+
+- **Tests**: 45 tests across 9 describe blocks covering normalization, defaults, insertion order, step sorting, collector options, non-destructive export, size, package exports, and determinism.
+
+- **Example**: `examples/basic.ts` — standalone signal, collected pipeline run, explicit step sorting, CER binding preview.

package/README.md

@@ -0,0 +1,230 @@
+# @nexart/signals v0.1.0
+
+Minimal, protocol-agnostic signal capture SDK.
+
+Captures and normalizes structured upstream signals so they can be bound into **Certified Execution Records (CERs)** as optional context evidence.
+
+- Does **not** define governance semantics or enforce policy
+- Does **not** interpret the meaning of signals
+- Validates structure only and provides normalization helpers
+- Fully optional and independent of `@nexart/ai-execution`
+
+---
+
+## Install
+
+```bash
+npm install @nexart/signals
+```
+
+---
+
+## Quick start
+
+```ts
+import { createSignal, createSignalCollector } from '@nexart/signals';
+
+// ── Standalone signal ──────────────────────────────────────────────────────
+
+const signal = createSignal({
+  type: 'approval',
+  source: 'github-actions',
+  actor: 'ci-bot',
+  status: 'ok',
+  payload: { pr: 42, approved_by: 'alice' },
+});
+
+// {
+//   type: 'approval',
+//   source: 'github-actions',
+//   step: 0,
+//   timestamp: '2026-...',
+//   actor: 'ci-bot',
+//   status: 'ok',
+//   payload: { pr: 42, approved_by: 'alice' }
+// }
+
+
+// ── Collected signals ──────────────────────────────────────────────────────
+
+const collector = createSignalCollector({ defaultSource: 'my-pipeline' });
+
+collector.add({ type: 'fetch',     source: 'my-pipeline', payload: { url: '...' } });
+collector.add({ type: 'transform', source: 'my-pipeline', actor: 'etl-bot' });
+collector.add({ type: 'store',     source: 'my-pipeline', status: 'ok' });
+
+const collection = collector.export();
+// {
+//   signals: [
+//     { type: 'fetch',     step: 0, ... },
+//     { type: 'transform', step: 1, ... },
+//     { type: 'store',     step: 2, ... },
+//   ],
+//   count: 3,
+//   exportedAt: '2026-...'
+// }
+```
+
+---
+
+## Signal shape
+
+Every `NexArtSignal` has exactly these fields — all always present, no undefined values:
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `type` | `string` | required | Signal category — free-form (e.g. `"approval"`, `"deploy"`, `"audit"`) |
+| `source` | `string` | required | Upstream system or protocol — free-form (e.g. `"github-actions"`, `"linear"`) |
+| `step` | `number` | `0` / auto | Position in sequence. Auto-assigned in insertion order by the collector |
+| `timestamp` | `string` | current time | ISO 8601 |
+| `actor` | `string` | `"unknown"` | Who produced this signal — free-form |
+| `status` | `string` | `"ok"` | Outcome — free-form (e.g. `"ok"`, `"error"`, `"pending"`, `"skipped"`) |
+| `payload` | `Record<string, unknown>` | `{}` | Opaque upstream data — NexArt does not interpret this |
+
+---
+
+## API
+
+### `createSignal(input)`
+
+Creates a single normalized signal. `type` and `source` are required. All other fields are optional with safe defaults.
+
+```ts
+const signal = createSignal({
+  type: 'review',
+  source: 'linear',
+  step: 2,
+  actor: 'alice',
+  status: 'ok',
+  payload: { issue: 'NX-123', verdict: 'approved' },
+});
+```
+
+### `createSignalCollector(options?)`
+
+Creates an ordered signal buffer. Returns a `SignalCollector` with three members:
+
+#### `collector.add(input)`
+
+Adds a signal. Returns the normalized `NexArtSignal` that was stored.
+
+- If `step` is omitted, it is auto-assigned using the insertion index (0, 1, 2, …)
+- If `step` is explicitly provided, that value is used and the signal is sorted correctly on export
+
+#### `collector.export()`
+
+Returns a `SignalCollection`:
+
+```ts
+interface SignalCollection {
+  signals:    NexArtSignal[];  // sorted by step (ascending)
+  count:      number;
+  exportedAt: string;          // ISO 8601, time of export() call
+}
+```
+
+Non-destructive — calling `export()` multiple times is safe. The internal buffer is not cleared.
+
+#### `collector.size`
+
+Returns the current number of collected signals.
+
+#### Collector options
+
+```ts
+interface CollectorOptions {
+  defaultSource?: string;  // applied when signal source is empty/omitted
+  defaultActor?:  string;  // applied when signal actor is omitted
+}
+```
+
+---
+
+## Step ordering
+
+Signals without an explicit `step` get steps assigned in insertion order:
+
+```ts
+collector.add({ type: 'a', source: 's' });  // step = 0
+collector.add({ type: 'b', source: 's' });  // step = 1
+collector.add({ type: 'c', source: 's' });  // step = 2
+```
+
+Signals with an explicit `step` are sorted by that value on export, regardless of insertion order:
+
+```ts
+collector.add({ type: 'deploy', source: 's', step: 10 });
+collector.add({ type: 'build',  source: 's', step: 0  });
+collector.add({ type: 'test',   source: 's', step: 5  });
+
+collector.export().signals.map(s => s.type);
+// ['build', 'test', 'deploy']
+```
+
+---
+
+## Determinism
+
+Pin `timestamp` and `step` for deterministic output that can be hashed:
+
+```ts
+const signal = createSignal({
+  type: 'approval',
+  source: 'ci',
+  step: 0,
+  timestamp: '2026-03-17T00:00:00.000Z',  // pinned
+  actor: 'bot',
+  payload: { pr: 42 },
+});
+// same input → identical object every time
+```
+
+---
+
+## Integration with @nexart/ai-execution (v0.10.0+)
+
+`NexArtSignal[]` is structurally identical to `CerContextSignal[]` in `@nexart/ai-execution` — no casting or conversion needed. Pass `collection.signals` directly to any certify call and it will be sealed into the `certificateHash` alongside the execution record.
+
+```ts
+import { createSignalCollector } from '@nexart/signals';
+import { certifyDecision, certifyLangChainRun, 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();
+
+// ── certifyDecision ──────────────────────────────────────────
+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,  // ← sealed into certificateHash; omit = identical hash as before
+});
+
+verifyCer(bundle).ok;               // true
+bundle.context?.signals.length;     // 2
+
+// ── certifyLangChainRun ──────────────────────────────────────
+const { bundle: lcBundle } = certifyLangChainRun({
+  provider: 'openai',
+  model: 'gpt-4o-mini',
+  input: { messages: [{ role: 'user', content: 'Summarise.' }] },
+  output: { text: 'Summary...' },
+  signals,  // ← same field, same semantics
+});
+```
+
+Signals are evidence-only — they do not affect execution behavior or parameters. See `@nexart/ai-execution` README for the full `CerContextSignal` shape and tamper-detection guarantees.
+
+---
+
+## Version history
+
+| Version | Description |
+|---|---|
+| v0.1.0 | Initial release: `createSignal`, `createSignalCollector`, `NexArtSignal`, `SignalCollection`, `CollectorOptions`, `SignalCollector` types |

package/dist/index.cjs

@@ -0,0 +1,84 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  SIGNALS_VERSION: () => SIGNALS_VERSION,
+  createSignal: () => createSignal,
+  createSignalCollector: () => createSignalCollector
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/create.ts
+function createSignal(input) {
+  return normalize(input, input.step ?? 0);
+}
+function normalize(input, resolvedStep) {
+  return {
+    type: input.type,
+    source: input.source,
+    step: resolvedStep,
+    timestamp: input.timestamp ?? (/* @__PURE__ */ new Date()).toISOString(),
+    actor: input.actor ?? "unknown",
+    status: input.status ?? "ok",
+    payload: input.payload ?? {}
+  };
+}
+
+// src/collector.ts
+function createSignalCollector(options) {
+  const buffer = [];
+  let insertionIndex = 0;
+  return {
+    add(input) {
+      const resolvedStep = input.step ?? insertionIndex;
+      const resolved = {
+        ...input,
+        source: input.source !== void 0 && input.source !== "" ? input.source : options?.defaultSource ?? input.source ?? "",
+        actor: input.actor !== void 0 && input.actor !== "" ? input.actor : options?.defaultActor ?? input.actor
+      };
+      const signal = normalize(resolved, resolvedStep);
+      buffer.push(signal);
+      insertionIndex++;
+      return signal;
+    },
+    export() {
+      const sorted = [...buffer].sort((a, b) => a.step - b.step);
+      return {
+        signals: sorted,
+        count: sorted.length,
+        exportedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+    },
+    get size() {
+      return buffer.length;
+    }
+  };
+}
+
+// src/index.ts
+var SIGNALS_VERSION = "0.1.0";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SIGNALS_VERSION,
+  createSignal,
+  createSignalCollector
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/create.ts","../src/collector.ts"],"sourcesContent":["/**\n * @nexart/signals v0.1.0\n *\n * Minimal, protocol-agnostic signal capture SDK.\n *\n * Captures and normalizes structured upstream signals so they can be bound\n * into Certified Execution Records (CERs) as optional context evidence.\n *\n * Does NOT define governance semantics, enforce policy, or interpret meaning.\n * Only validates structure and provides normalization helpers.\n *\n * @example\n * ```ts\n * import { createSignal, createSignalCollector } from '@nexart/signals';\n *\n * // Standalone signal\n * const signal = createSignal({\n *   type: 'approval',\n *   source: 'github-actions',\n *   actor: 'ci-bot',\n *   payload: { pr: 42 },\n * });\n *\n * // Collected signals\n * const collector = createSignalCollector();\n * collector.add({ type: 'fetch', source: 'pipeline', payload: { url: '...' } });\n * collector.add({ type: 'store', source: 'pipeline', actor: 'etl-bot' });\n * const collection = collector.export();\n * ```\n */\n\nexport { createSignal } from './create.js';\nexport { createSignalCollector } from './collector.js';\n\nexport type {\n  NexArtSignal,\n  CreateSignalInput,\n  CollectorOptions,\n  SignalCollection,\n  SignalCollector,\n} from './types.js';\n\nexport const SIGNALS_VERSION = '0.1.0' as const;\n","/**\n * @nexart/signals — createSignal()\n *\n * Normalizes a CreateSignalInput into a fully-populated NexArtSignal.\n * Every field is always present — no undefined values in the output.\n */\n\nimport type { CreateSignalInput, NexArtSignal } from './types.js';\n\n/**\n * Create a single normalized NexArtSignal from a CreateSignalInput.\n *\n * - type and source are required.\n * - step defaults to 0 if omitted (use a collector for auto-incrementing step).\n * - timestamp defaults to the current time (ISO 8601).\n * - actor defaults to \"unknown\".\n * - status defaults to \"ok\".\n * - payload defaults to {}.\n *\n * @example\n * ```ts\n * const signal = createSignal({\n *   type: 'approval',\n *   source: 'github-actions',\n *   actor: 'ci-bot',\n *   status: 'ok',\n *   payload: { pr: 42, approved_by: 'alice' },\n * });\n * ```\n */\nexport function createSignal(input: CreateSignalInput): NexArtSignal {\n  return normalize(input, input.step ?? 0);\n}\n\n/**\n * Internal normalization helper — shared by createSignal() and the collector.\n * Applies all field defaults deterministically.\n *\n * @internal\n */\nexport function normalize(input: CreateSignalInput, resolvedStep: number): NexArtSignal {\n  return {\n    type: input.type,\n    source: input.source,\n    step: resolvedStep,\n    timestamp: input.timestamp ?? new Date().toISOString(),\n    actor: input.actor ?? 'unknown',\n    status: input.status ?? 'ok',\n    payload: input.payload ?? {},\n  };\n}\n","/**\n * @nexart/signals — createSignalCollector()\n *\n * A lightweight, ordered buffer for collecting signals from multiple\n * upstream sources before exporting them as a single SignalCollection.\n *\n * Auto-assigns step values in insertion order when signals do not\n * carry an explicit step. Signals with explicit steps are sorted\n * by step on export.\n */\n\nimport { normalize } from './create.js';\nimport type {\n  CollectorOptions,\n  CreateSignalInput,\n  NexArtSignal,\n  SignalCollection,\n  SignalCollector,\n} from './types.js';\n\n/**\n * Create a signal collector.\n *\n * The collector maintains insertion order and auto-assigns step values.\n * When a signal provides an explicit step, that value is used as-is.\n * On export(), all signals are sorted by step (ascending).\n *\n * @example\n * ```ts\n * const collector = createSignalCollector({ defaultSource: 'my-pipeline' });\n *\n * collector.add({ type: 'fetch', source: 'my-pipeline', payload: { url: '...' } });\n * collector.add({ type: 'transform', source: 'my-pipeline', status: 'ok' });\n * collector.add({ type: 'store', source: 'my-pipeline', actor: 'etl-bot' });\n *\n * const collection = collector.export();\n * // collection.signals[0].step === 0\n * // collection.signals[1].step === 1\n * // collection.signals[2].step === 2\n * ```\n */\nexport function createSignalCollector(options?: CollectorOptions): SignalCollector {\n  const buffer: NexArtSignal[] = [];\n  let insertionIndex = 0;\n\n  return {\n    add(input: CreateSignalInput): NexArtSignal {\n      const resolvedStep = input.step ?? insertionIndex;\n\n      const resolved: CreateSignalInput = {\n        ...input,\n        source: input.source !== undefined && input.source !== ''\n          ? input.source\n          : (options?.defaultSource ?? input.source ?? ''),\n        actor: input.actor !== undefined && input.actor !== ''\n          ? input.actor\n          : (options?.defaultActor ?? input.actor),\n      };\n\n      const signal = normalize(resolved, resolvedStep);\n      buffer.push(signal);\n      insertionIndex++;\n      return signal;\n    },\n\n    export(): SignalCollection {\n      const sorted = [...buffer].sort((a, b) => a.step - b.step);\n      return {\n        signals: sorted,\n        count: sorted.length,\n        exportedAt: new Date().toISOString(),\n      };\n    },\n\n    get size(): number {\n      return buffer.length;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;AC8BO,SAAS,aAAa,OAAwC;AACnE,SAAO,UAAU,OAAO,MAAM,QAAQ,CAAC;AACzC;AAQO,SAAS,UAAU,OAA0B,cAAoC;AACtF,SAAO;AAAA,IACL,MAAM,MAAM;AAAA,IACZ,QAAQ,MAAM;AAAA,IACd,MAAM;AAAA,IACN,WAAW,MAAM,cAAa,oBAAI,KAAK,GAAE,YAAY;AAAA,IACrD,OAAO,MAAM,SAAS;AAAA,IACtB,QAAQ,MAAM,UAAU;AAAA,IACxB,SAAS,MAAM,WAAW,CAAC;AAAA,EAC7B;AACF;;;ACTO,SAAS,sBAAsB,SAA6C;AACjF,QAAM,SAAyB,CAAC;AAChC,MAAI,iBAAiB;AAErB,SAAO;AAAA,IACL,IAAI,OAAwC;AAC1C,YAAM,eAAe,MAAM,QAAQ;AAEnC,YAAM,WAA8B;AAAA,QAClC,GAAG;AAAA,QACH,QAAQ,MAAM,WAAW,UAAa,MAAM,WAAW,KACnD,MAAM,SACL,SAAS,iBAAiB,MAAM,UAAU;AAAA,QAC/C,OAAO,MAAM,UAAU,UAAa,MAAM,UAAU,KAChD,MAAM,QACL,SAAS,gBAAgB,MAAM;AAAA,MACtC;AAEA,YAAM,SAAS,UAAU,UAAU,YAAY;AAC/C,aAAO,KAAK,MAAM;AAClB;AACA,aAAO;AAAA,IACT;AAAA,IAEA,SAA2B;AACzB,YAAM,SAAS,CAAC,GAAG,MAAM,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,IAAI;AACzD,aAAO;AAAA,QACL,SAAS;AAAA,QACT,OAAO,OAAO;AAAA,QACd,aAAY,oBAAI,KAAK,GAAE,YAAY;AAAA,MACrC;AAAA,IACF;AAAA,IAEA,IAAI,OAAe;AACjB,aAAO,OAAO;AAAA,IAChB;AAAA,EACF;AACF;;;AFpCO,IAAM,kBAAkB;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,209 @@
+/**
+ * @nexart/signals — Core signal types
+ *
+ * All types are intentionally protocol-agnostic.
+ * The SDK validates structure only — it does not interpret meaning.
+ */
+/**
+ * A normalized upstream signal captured for optional inclusion in a CER.
+ *
+ * Fields are normalized at creation time — all fields are always present
+ * (no undefined values) to make hashing and downstream consumption reliable.
+ */
+interface NexArtSignal {
+    /** Signal category. Free-form — examples: "approval", "review", "deploy", "audit". */
+    type: string;
+    /** Upstream system or protocol that produced this signal. Free-form. */
+    source: string;
+    /**
+     * Position of this signal in a sequence.
+     * Auto-assigned (0-based insertion order) when not explicitly provided.
+     */
+    step: number;
+    /** ISO 8601 timestamp. Defaults to the time createSignal() was called. */
+    timestamp: string;
+    /** Actor that produced this signal. Free-form — defaults to "unknown". */
+    actor: string;
+    /**
+     * Outcome or state of the signal. Free-form — defaults to "ok".
+     * Examples: "ok", "error", "pending", "skipped".
+     */
+    status: string;
+    /**
+     * Opaque payload from the upstream system.
+     * NexArt does not interpret, validate, or modify this field.
+     * Defaults to {} if omitted.
+     */
+    payload: Record<string, unknown>;
+}
+/**
+ * Input to createSignal(). Only type and source are required.
+ * All other fields are optional and normalized to safe defaults.
+ */
+interface CreateSignalInput {
+    /** Signal category. Required. */
+    type: string;
+    /** Upstream system or protocol. Required. */
+    source: string;
+    /**
+     * Explicit step index. When omitted on a collector, auto-assigned
+     * in insertion order. When omitted on standalone createSignal(), defaults to 0.
+     */
+    step?: number;
+    /** ISO 8601 timestamp. Defaults to current time if omitted. */
+    timestamp?: string;
+    /** Actor that produced this signal. Defaults to "unknown". */
+    actor?: string;
+    /**
+     * Outcome or state. Defaults to "ok".
+     * Examples: "ok", "error", "pending", "skipped".
+     */
+    status?: string;
+    /**
+     * Opaque payload. NexArt does not interpret this.
+     * Defaults to {} if omitted.
+     */
+    payload?: Record<string, unknown>;
+}
+/** Options for createSignalCollector(). */
+interface CollectorOptions {
+    /**
+     * Default source applied to every signal added via collector.add()
+     * when the signal does not supply its own source.
+     */
+    defaultSource?: string;
+    /**
+     * Default actor applied to every signal added via collector.add()
+     * when the signal does not supply its own actor.
+     */
+    defaultActor?: string;
+}
+/**
+ * Exported signal collection produced by collector.export().
+ * Stable, deterministic, and ready to be hashed or bound into a CER.
+ */
+interface SignalCollection {
+    /** Signals sorted by step (ascending). */
+    signals: NexArtSignal[];
+    /** Total number of signals in this collection. */
+    count: number;
+    /** ISO 8601 timestamp of when export() was called. */
+    exportedAt: string;
+}
+/** A signal collector returned by createSignalCollector(). */
+interface SignalCollector {
+    /**
+     * Add a signal to the collector.
+     * Returns the normalized NexArtSignal that was stored.
+     */
+    add(input: CreateSignalInput): NexArtSignal;
+    /**
+     * Export all collected signals as a stable SignalCollection.
+     * Signals are sorted by step (ascending).
+     * Does not clear the internal buffer — calling export() twice is safe.
+     */
+    export(): SignalCollection;
+    /**
+     * Return the current number of signals in the collector.
+     */
+    readonly size: number;
+}
+
+/**
+ * @nexart/signals — createSignal()
+ *
+ * Normalizes a CreateSignalInput into a fully-populated NexArtSignal.
+ * Every field is always present — no undefined values in the output.
+ */
+
+/**
+ * Create a single normalized NexArtSignal from a CreateSignalInput.
+ *
+ * - type and source are required.
+ * - step defaults to 0 if omitted (use a collector for auto-incrementing step).
+ * - timestamp defaults to the current time (ISO 8601).
+ * - actor defaults to "unknown".
+ * - status defaults to "ok".
+ * - payload defaults to {}.
+ *
+ * @example
+ * ```ts
+ * const signal = createSignal({
+ *   type: 'approval',
+ *   source: 'github-actions',
+ *   actor: 'ci-bot',
+ *   status: 'ok',
+ *   payload: { pr: 42, approved_by: 'alice' },
+ * });
+ * ```
+ */
+declare function createSignal(input: CreateSignalInput): NexArtSignal;
+
+/**
+ * @nexart/signals — createSignalCollector()
+ *
+ * A lightweight, ordered buffer for collecting signals from multiple
+ * upstream sources before exporting them as a single SignalCollection.
+ *
+ * Auto-assigns step values in insertion order when signals do not
+ * carry an explicit step. Signals with explicit steps are sorted
+ * by step on export.
+ */
+
+/**
+ * Create a signal collector.
+ *
+ * The collector maintains insertion order and auto-assigns step values.
+ * When a signal provides an explicit step, that value is used as-is.
+ * On export(), all signals are sorted by step (ascending).
+ *
+ * @example
+ * ```ts
+ * const collector = createSignalCollector({ defaultSource: 'my-pipeline' });
+ *
+ * collector.add({ type: 'fetch', source: 'my-pipeline', payload: { url: '...' } });
+ * collector.add({ type: 'transform', source: 'my-pipeline', status: 'ok' });
+ * collector.add({ type: 'store', source: 'my-pipeline', actor: 'etl-bot' });
+ *
+ * const collection = collector.export();
+ * // collection.signals[0].step === 0
+ * // collection.signals[1].step === 1
+ * // collection.signals[2].step === 2
+ * ```
+ */
+declare function createSignalCollector(options?: CollectorOptions): SignalCollector;
+
+/**
+ * @nexart/signals v0.1.0
+ *
+ * Minimal, protocol-agnostic signal capture SDK.
+ *
+ * Captures and normalizes structured upstream signals so they can be bound
+ * into Certified Execution Records (CERs) as optional context evidence.
+ *
+ * Does NOT define governance semantics, enforce policy, or interpret meaning.
+ * Only validates structure and provides normalization helpers.
+ *
+ * @example
+ * ```ts
+ * import { createSignal, createSignalCollector } from '@nexart/signals';
+ *
+ * // Standalone signal
+ * const signal = createSignal({
+ *   type: 'approval',
+ *   source: 'github-actions',
+ *   actor: 'ci-bot',
+ *   payload: { pr: 42 },
+ * });
+ *
+ * // Collected signals
+ * const collector = createSignalCollector();
+ * collector.add({ type: 'fetch', source: 'pipeline', payload: { url: '...' } });
+ * collector.add({ type: 'store', source: 'pipeline', actor: 'etl-bot' });
+ * const collection = collector.export();
+ * ```
+ */
+
+declare const SIGNALS_VERSION: "0.1.0";
+
+export { type CollectorOptions, type CreateSignalInput, type NexArtSignal, SIGNALS_VERSION, type SignalCollection, type SignalCollector, createSignal, createSignalCollector };

package/dist/index.d.ts

@@ -0,0 +1,209 @@
+/**
+ * @nexart/signals — Core signal types
+ *
+ * All types are intentionally protocol-agnostic.
+ * The SDK validates structure only — it does not interpret meaning.
+ */
+/**
+ * A normalized upstream signal captured for optional inclusion in a CER.
+ *
+ * Fields are normalized at creation time — all fields are always present
+ * (no undefined values) to make hashing and downstream consumption reliable.
+ */
+interface NexArtSignal {
+    /** Signal category. Free-form — examples: "approval", "review", "deploy", "audit". */
+    type: string;
+    /** Upstream system or protocol that produced this signal. Free-form. */
+    source: string;
+    /**
+     * Position of this signal in a sequence.
+     * Auto-assigned (0-based insertion order) when not explicitly provided.
+     */
+    step: number;
+    /** ISO 8601 timestamp. Defaults to the time createSignal() was called. */
+    timestamp: string;
+    /** Actor that produced this signal. Free-form — defaults to "unknown". */
+    actor: string;
+    /**
+     * Outcome or state of the signal. Free-form — defaults to "ok".
+     * Examples: "ok", "error", "pending", "skipped".
+     */
+    status: string;
+    /**
+     * Opaque payload from the upstream system.
+     * NexArt does not interpret, validate, or modify this field.
+     * Defaults to {} if omitted.
+     */
+    payload: Record<string, unknown>;
+}
+/**
+ * Input to createSignal(). Only type and source are required.
+ * All other fields are optional and normalized to safe defaults.
+ */
+interface CreateSignalInput {
+    /** Signal category. Required. */
+    type: string;
+    /** Upstream system or protocol. Required. */
+    source: string;
+    /**
+     * Explicit step index. When omitted on a collector, auto-assigned
+     * in insertion order. When omitted on standalone createSignal(), defaults to 0.
+     */
+    step?: number;
+    /** ISO 8601 timestamp. Defaults to current time if omitted. */
+    timestamp?: string;
+    /** Actor that produced this signal. Defaults to "unknown". */
+    actor?: string;
+    /**
+     * Outcome or state. Defaults to "ok".
+     * Examples: "ok", "error", "pending", "skipped".
+     */
+    status?: string;
+    /**
+     * Opaque payload. NexArt does not interpret this.
+     * Defaults to {} if omitted.
+     */
+    payload?: Record<string, unknown>;
+}
+/** Options for createSignalCollector(). */
+interface CollectorOptions {
+    /**
+     * Default source applied to every signal added via collector.add()
+     * when the signal does not supply its own source.
+     */
+    defaultSource?: string;
+    /**
+     * Default actor applied to every signal added via collector.add()
+     * when the signal does not supply its own actor.
+     */
+    defaultActor?: string;
+}
+/**
+ * Exported signal collection produced by collector.export().
+ * Stable, deterministic, and ready to be hashed or bound into a CER.
+ */
+interface SignalCollection {
+    /** Signals sorted by step (ascending). */
+    signals: NexArtSignal[];
+    /** Total number of signals in this collection. */
+    count: number;
+    /** ISO 8601 timestamp of when export() was called. */
+    exportedAt: string;
+}
+/** A signal collector returned by createSignalCollector(). */
+interface SignalCollector {
+    /**
+     * Add a signal to the collector.
+     * Returns the normalized NexArtSignal that was stored.
+     */
+    add(input: CreateSignalInput): NexArtSignal;
+    /**
+     * Export all collected signals as a stable SignalCollection.
+     * Signals are sorted by step (ascending).
+     * Does not clear the internal buffer — calling export() twice is safe.
+     */
+    export(): SignalCollection;
+    /**
+     * Return the current number of signals in the collector.
+     */
+    readonly size: number;
+}
+
+/**
+ * @nexart/signals — createSignal()
+ *
+ * Normalizes a CreateSignalInput into a fully-populated NexArtSignal.
+ * Every field is always present — no undefined values in the output.
+ */
+
+/**
+ * Create a single normalized NexArtSignal from a CreateSignalInput.
+ *
+ * - type and source are required.
+ * - step defaults to 0 if omitted (use a collector for auto-incrementing step).
+ * - timestamp defaults to the current time (ISO 8601).
+ * - actor defaults to "unknown".
+ * - status defaults to "ok".
+ * - payload defaults to {}.
+ *
+ * @example
+ * ```ts
+ * const signal = createSignal({
+ *   type: 'approval',
+ *   source: 'github-actions',
+ *   actor: 'ci-bot',
+ *   status: 'ok',
+ *   payload: { pr: 42, approved_by: 'alice' },
+ * });
+ * ```
+ */
+declare function createSignal(input: CreateSignalInput): NexArtSignal;
+
+/**
+ * @nexart/signals — createSignalCollector()
+ *
+ * A lightweight, ordered buffer for collecting signals from multiple
+ * upstream sources before exporting them as a single SignalCollection.
+ *
+ * Auto-assigns step values in insertion order when signals do not
+ * carry an explicit step. Signals with explicit steps are sorted
+ * by step on export.
+ */
+
+/**
+ * Create a signal collector.
+ *
+ * The collector maintains insertion order and auto-assigns step values.
+ * When a signal provides an explicit step, that value is used as-is.
+ * On export(), all signals are sorted by step (ascending).
+ *
+ * @example
+ * ```ts
+ * const collector = createSignalCollector({ defaultSource: 'my-pipeline' });
+ *
+ * collector.add({ type: 'fetch', source: 'my-pipeline', payload: { url: '...' } });
+ * collector.add({ type: 'transform', source: 'my-pipeline', status: 'ok' });
+ * collector.add({ type: 'store', source: 'my-pipeline', actor: 'etl-bot' });
+ *
+ * const collection = collector.export();
+ * // collection.signals[0].step === 0
+ * // collection.signals[1].step === 1
+ * // collection.signals[2].step === 2
+ * ```
+ */
+declare function createSignalCollector(options?: CollectorOptions): SignalCollector;
+
+/**
+ * @nexart/signals v0.1.0
+ *
+ * Minimal, protocol-agnostic signal capture SDK.
+ *
+ * Captures and normalizes structured upstream signals so they can be bound
+ * into Certified Execution Records (CERs) as optional context evidence.
+ *
+ * Does NOT define governance semantics, enforce policy, or interpret meaning.
+ * Only validates structure and provides normalization helpers.
+ *
+ * @example
+ * ```ts
+ * import { createSignal, createSignalCollector } from '@nexart/signals';
+ *
+ * // Standalone signal
+ * const signal = createSignal({
+ *   type: 'approval',
+ *   source: 'github-actions',
+ *   actor: 'ci-bot',
+ *   payload: { pr: 42 },
+ * });
+ *
+ * // Collected signals
+ * const collector = createSignalCollector();
+ * collector.add({ type: 'fetch', source: 'pipeline', payload: { url: '...' } });
+ * collector.add({ type: 'store', source: 'pipeline', actor: 'etl-bot' });
+ * const collection = collector.export();
+ * ```
+ */
+
+declare const SIGNALS_VERSION: "0.1.0";
+
+export { type CollectorOptions, type CreateSignalInput, type NexArtSignal, SIGNALS_VERSION, type SignalCollection, type SignalCollector, createSignal, createSignalCollector };

package/dist/index.mjs

@@ -0,0 +1,55 @@
+// src/create.ts
+function createSignal(input) {
+  return normalize(input, input.step ?? 0);
+}
+function normalize(input, resolvedStep) {
+  return {
+    type: input.type,
+    source: input.source,
+    step: resolvedStep,
+    timestamp: input.timestamp ?? (/* @__PURE__ */ new Date()).toISOString(),
+    actor: input.actor ?? "unknown",
+    status: input.status ?? "ok",
+    payload: input.payload ?? {}
+  };
+}
+
+// src/collector.ts
+function createSignalCollector(options) {
+  const buffer = [];
+  let insertionIndex = 0;
+  return {
+    add(input) {
+      const resolvedStep = input.step ?? insertionIndex;
+      const resolved = {
+        ...input,
+        source: input.source !== void 0 && input.source !== "" ? input.source : options?.defaultSource ?? input.source ?? "",
+        actor: input.actor !== void 0 && input.actor !== "" ? input.actor : options?.defaultActor ?? input.actor
+      };
+      const signal = normalize(resolved, resolvedStep);
+      buffer.push(signal);
+      insertionIndex++;
+      return signal;
+    },
+    export() {
+      const sorted = [...buffer].sort((a, b) => a.step - b.step);
+      return {
+        signals: sorted,
+        count: sorted.length,
+        exportedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+    },
+    get size() {
+      return buffer.length;
+    }
+  };
+}
+
+// src/index.ts
+var SIGNALS_VERSION = "0.1.0";
+export {
+  SIGNALS_VERSION,
+  createSignal,
+  createSignalCollector
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/create.ts","../src/collector.ts","../src/index.ts"],"sourcesContent":["/**\n * @nexart/signals — createSignal()\n *\n * Normalizes a CreateSignalInput into a fully-populated NexArtSignal.\n * Every field is always present — no undefined values in the output.\n */\n\nimport type { CreateSignalInput, NexArtSignal } from './types.js';\n\n/**\n * Create a single normalized NexArtSignal from a CreateSignalInput.\n *\n * - type and source are required.\n * - step defaults to 0 if omitted (use a collector for auto-incrementing step).\n * - timestamp defaults to the current time (ISO 8601).\n * - actor defaults to \"unknown\".\n * - status defaults to \"ok\".\n * - payload defaults to {}.\n *\n * @example\n * ```ts\n * const signal = createSignal({\n *   type: 'approval',\n *   source: 'github-actions',\n *   actor: 'ci-bot',\n *   status: 'ok',\n *   payload: { pr: 42, approved_by: 'alice' },\n * });\n * ```\n */\nexport function createSignal(input: CreateSignalInput): NexArtSignal {\n  return normalize(input, input.step ?? 0);\n}\n\n/**\n * Internal normalization helper — shared by createSignal() and the collector.\n * Applies all field defaults deterministically.\n *\n * @internal\n */\nexport function normalize(input: CreateSignalInput, resolvedStep: number): NexArtSignal {\n  return {\n    type: input.type,\n    source: input.source,\n    step: resolvedStep,\n    timestamp: input.timestamp ?? new Date().toISOString(),\n    actor: input.actor ?? 'unknown',\n    status: input.status ?? 'ok',\n    payload: input.payload ?? {},\n  };\n}\n","/**\n * @nexart/signals — createSignalCollector()\n *\n * A lightweight, ordered buffer for collecting signals from multiple\n * upstream sources before exporting them as a single SignalCollection.\n *\n * Auto-assigns step values in insertion order when signals do not\n * carry an explicit step. Signals with explicit steps are sorted\n * by step on export.\n */\n\nimport { normalize } from './create.js';\nimport type {\n  CollectorOptions,\n  CreateSignalInput,\n  NexArtSignal,\n  SignalCollection,\n  SignalCollector,\n} from './types.js';\n\n/**\n * Create a signal collector.\n *\n * The collector maintains insertion order and auto-assigns step values.\n * When a signal provides an explicit step, that value is used as-is.\n * On export(), all signals are sorted by step (ascending).\n *\n * @example\n * ```ts\n * const collector = createSignalCollector({ defaultSource: 'my-pipeline' });\n *\n * collector.add({ type: 'fetch', source: 'my-pipeline', payload: { url: '...' } });\n * collector.add({ type: 'transform', source: 'my-pipeline', status: 'ok' });\n * collector.add({ type: 'store', source: 'my-pipeline', actor: 'etl-bot' });\n *\n * const collection = collector.export();\n * // collection.signals[0].step === 0\n * // collection.signals[1].step === 1\n * // collection.signals[2].step === 2\n * ```\n */\nexport function createSignalCollector(options?: CollectorOptions): SignalCollector {\n  const buffer: NexArtSignal[] = [];\n  let insertionIndex = 0;\n\n  return {\n    add(input: CreateSignalInput): NexArtSignal {\n      const resolvedStep = input.step ?? insertionIndex;\n\n      const resolved: CreateSignalInput = {\n        ...input,\n        source: input.source !== undefined && input.source !== ''\n          ? input.source\n          : (options?.defaultSource ?? input.source ?? ''),\n        actor: input.actor !== undefined && input.actor !== ''\n          ? input.actor\n          : (options?.defaultActor ?? input.actor),\n      };\n\n      const signal = normalize(resolved, resolvedStep);\n      buffer.push(signal);\n      insertionIndex++;\n      return signal;\n    },\n\n    export(): SignalCollection {\n      const sorted = [...buffer].sort((a, b) => a.step - b.step);\n      return {\n        signals: sorted,\n        count: sorted.length,\n        exportedAt: new Date().toISOString(),\n      };\n    },\n\n    get size(): number {\n      return buffer.length;\n    },\n  };\n}\n","/**\n * @nexart/signals v0.1.0\n *\n * Minimal, protocol-agnostic signal capture SDK.\n *\n * Captures and normalizes structured upstream signals so they can be bound\n * into Certified Execution Records (CERs) as optional context evidence.\n *\n * Does NOT define governance semantics, enforce policy, or interpret meaning.\n * Only validates structure and provides normalization helpers.\n *\n * @example\n * ```ts\n * import { createSignal, createSignalCollector } from '@nexart/signals';\n *\n * // Standalone signal\n * const signal = createSignal({\n *   type: 'approval',\n *   source: 'github-actions',\n *   actor: 'ci-bot',\n *   payload: { pr: 42 },\n * });\n *\n * // Collected signals\n * const collector = createSignalCollector();\n * collector.add({ type: 'fetch', source: 'pipeline', payload: { url: '...' } });\n * collector.add({ type: 'store', source: 'pipeline', actor: 'etl-bot' });\n * const collection = collector.export();\n * ```\n */\n\nexport { createSignal } from './create.js';\nexport { createSignalCollector } from './collector.js';\n\nexport type {\n  NexArtSignal,\n  CreateSignalInput,\n  CollectorOptions,\n  SignalCollection,\n  SignalCollector,\n} from './types.js';\n\nexport const SIGNALS_VERSION = '0.1.0' as const;\n"],"mappings":";AA8BO,SAAS,aAAa,OAAwC;AACnE,SAAO,UAAU,OAAO,MAAM,QAAQ,CAAC;AACzC;AAQO,SAAS,UAAU,OAA0B,cAAoC;AACtF,SAAO;AAAA,IACL,MAAM,MAAM;AAAA,IACZ,QAAQ,MAAM;AAAA,IACd,MAAM;AAAA,IACN,WAAW,MAAM,cAAa,oBAAI,KAAK,GAAE,YAAY;AAAA,IACrD,OAAO,MAAM,SAAS;AAAA,IACtB,QAAQ,MAAM,UAAU;AAAA,IACxB,SAAS,MAAM,WAAW,CAAC;AAAA,EAC7B;AACF;;;ACTO,SAAS,sBAAsB,SAA6C;AACjF,QAAM,SAAyB,CAAC;AAChC,MAAI,iBAAiB;AAErB,SAAO;AAAA,IACL,IAAI,OAAwC;AAC1C,YAAM,eAAe,MAAM,QAAQ;AAEnC,YAAM,WAA8B;AAAA,QAClC,GAAG;AAAA,QACH,QAAQ,MAAM,WAAW,UAAa,MAAM,WAAW,KACnD,MAAM,SACL,SAAS,iBAAiB,MAAM,UAAU;AAAA,QAC/C,OAAO,MAAM,UAAU,UAAa,MAAM,UAAU,KAChD,MAAM,QACL,SAAS,gBAAgB,MAAM;AAAA,MACtC;AAEA,YAAM,SAAS,UAAU,UAAU,YAAY;AAC/C,aAAO,KAAK,MAAM;AAClB;AACA,aAAO;AAAA,IACT;AAAA,IAEA,SAA2B;AACzB,YAAM,SAAS,CAAC,GAAG,MAAM,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,IAAI;AACzD,aAAO;AAAA,QACL,SAAS;AAAA,QACT,OAAO,OAAO;AAAA,QACd,aAAY,oBAAI,KAAK,GAAE,YAAY;AAAA,MACrC;AAAA,IACF;AAAA,IAEA,IAAI,OAAe;AACjB,aAAO,OAAO;AAAA,IAChB;AAAA,EACF;AACF;;;ACpCO,IAAM,kBAAkB;","names":[]}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@nexart/signals",
+  "version": "0.1.0",
+  "description": "Minimal, protocol-agnostic signal capture SDK for optional CER context evidence",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "build:tsc": "tsc --project tsconfig.json --outDir dist-tsc",
+    "test": "npm run build:tsc && node --test --test-concurrency 1 dist-tsc/__tests__/signals.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "nexart",
+    "signals",
+    "cer",
+    "ai",
+    "audit",
+    "tracing"
+  ],
+  "license": "MIT"
+}