nexart.iodocs

    Execution Context and Signals

    How to capture structured execution signals with @nexart/signals and certify them with @nexart/ai-execution.

    1. Overview

    Execution context is a sequence of structured signals captured during execution.

    Signals represent steps such as:

    • input
    • tool calls
    • decisions
    • output

    Context is optional.

    If included, it becomes part of the Certified Execution Record and is included in the certificateHash.

    If not included, the record remains valid.

    2. SDKs involved

    @nexart/signals

    • Used to capture and structure execution signals.
    • Provides the builder API: createContext, step, wrap, and the typed helpers below.
    • Full reference: Signals SDK.

    @nexart/ai-execution

    • Used to certify execution.
    • Accepts signals as part of the execution payload.
    • Produces CER bundles.

    The two SDKs have separate responsibilities and should not be mixed.

    3. Basic implementation

    Step 1. Create context

    Use createContext() to initialize signal collection.

    Create a context
    import { createContext } from "@nexart/signals";

const ctx = createContext();

    Step 2. Capture signals

    Use the typed helpers:

    • ctx.input()
    • ctx.tool()
    • ctx.decision()
    • ctx.output()

    Or use ctx.step() for custom signals.

    Step 3. Optional auto-instrumentation

    Use ctx.wrap(type, fn) to capture start and end spans automatically.

    Step 4. Certify execution

    Pass ctx.signals into the certification call. Signals are automatically included in the CER.

    Certify with signals
    import { createContext } from "@nexart/signals";
import { certifyExecution } from "@nexart/ai-execution";

const ctx = createContext();

ctx.input({ prompt: "Summarize this contract" });
ctx.tool({ name: "vector-search", args: { query: "termination clause" } });
ctx.decision({ id: "policy.allow", result: "pass" });
ctx.output({ text: "The contract states that..." });

const result = await certifyExecution({
  model: "gpt-4o-mini",
  input: { prompt: "Summarize this contract" },
  output: { text: "The contract states that..." },
  signals: ctx.signals,
  nodeUrl: "https://your-nexart-node.example",
  apiKey: process.env.NEXART_API_KEY,
});

console.log(result.certificateHash);

    4. Example flow

    A simple execution captures the following ordered signals:

    1. capture input
    2. call tool
    3. compute decision
    4. produce output
    5. certify with signals attached

    Signals are ordered and deterministic.

    5. Determinism and hashing

    Signals must be deterministic if reproducibility is required.

    • step ordering must be stable
    • timestamps should be controlled if needed
    • payload should not contain non-deterministic values

    The context is canonicalized and included in the certificate hash.

    The certificate hash always reflects the exact bundle that is returned and verified.

    6. What changed in v0.16.1

    Previous versions could mutate the context after hashing. This caused mismatches between the hash and the bundle.

    In v0.16.1:

    • Context is constructed before hashing.
    • Context is included in the certificate hash when present.
    • The bundle is immutable after hashing.
    • Verification uses the bundle as-is.

    7. Verification behavior

    verifyCer validates the full bundle.

    If signals are present, they are part of the verification boundary.

    Any modification to:

    • signals
    • contextHash
    • contextSummary

    invalidates the certificate.

    8. When to use signals

    Use signals when:

    • execution trace matters
    • workflows involve multiple steps
    • decisions need to be reviewed

    Do not require signals for simple executions.

    9. Compatibility note

    Bundles created with v0.16.0 that include signals may fail verification. Re-seal using v0.16.1.