# Execution Context and Signals

URL: https://docs.nexart.io/docs/concepts/execution-context

The execution context captures the environment around a certified run, including model, tooling and policy details, and how those fields enter the certified.

## 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:

- capture input
- call tool
- compute decision
- produce output
- 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.

## Related

- Signals SDK: full `@nexart/signals` reference
- Certified Execution Records
- AI Execution SDK
- Context Signals
- Verification Semantics