nexart.iodocs

    Context Signals

    Optional structured metadata recorded alongside an execution. May be hash-bound or supplemental.

    What are Context Signals

    Context Signals are structured metadata recorded alongside an execution to capture external context. They let builders attach additional evidence such as policy check results, environment state, or authorization decisions to a Certified Execution Record.

    Why They Exist

    • Logs are not verifiable. Traditional logging systems record events but provide no cryptographic proof that the logged data has not been modified.
    • Governance systems lack structured evidence. Compliance workflows often depend on assertions without machine-readable evidence of what actually happened at execution time.
    • Signals attach structured evidence to the record. They become part of the verifiable artifact (or are recorded alongside it) so reviewers can inspect what context was available when the execution ran.

    Key Properties

    • Optional. Signals are not required for CER creation. A record without signals is fully valid.
    • Protocol-agnostic. Any structured metadata can be recorded. The protocol does not prescribe specific signal types.
    • Scope varies. A signal MAY be included in the certificateHash (hash-bound) or recorded as supplemental context (outside the hash scope). Which mode applies depends on the artifact type and how the CER was produced.
    • Hash-bound signals are tamper-evident. Modifying them breaks bundleIntegrity.
    • Supplemental signals do not block core verification. Their absence or modification does not cause core artifact verification to fail. The verifier may surface them as supplemental evidence.
    Hash-bound vs supplemental
    Both modes are valid. A signal being outside the hash scope does NOT mean core artifact integrity has failed. It means that signal is recorded for context, not as part of the cryptographic commitment. See Verification Semantics for how this is reflected in verification reports.

    Example

    Create a signal, collect it, and pass it into a certified execution:

    Creating and attaching signals
    import {
  createSignal,
  createSignalCollector,
  certifyDecision
} from "@nexart/ai-execution";

const signal = createSignal({
  type: "policy.check",
  source: "compliance-engine",
  payload: {
    policyId: "ret-30d",
    result: "pass"
  }
});

const collector = createSignalCollector();
collector.add(signal);

const result = await certifyDecision({
  provider: "openai",
  model: "gpt-4o-mini",
  input: { messages: [{ role: "user", content: "Approve this request?" }] },
  output: { decision: "approve", reason: "policy_passed" },
  signals: collector.signals(),
  nodeUrl: "https://your-nexart-node.example",
  apiKey: process.env.NEXART_API_KEY
});

console.log(result.certificateHash);

    CLI Usage

    The NexArt CLI supports attaching signals from a JSON file when creating or certifying a CER:

    Attach signals via CLI
    npx @nexart/cli@1.0.0 ai create execution.json --signals-file signals.json

    Example signals.json:

    signals.json
    [
  {
    "type": "policy.check",
    "source": "compliance-engine",
    "payload": {
      "policyId": "ret-30d",
      "result": "pass"
    }
  }
]

    Verification

    How signals affect verification depends on whether they are hash-bound or supplemental:

    • Hash-bound signals are part of the data covered by the certificateHash. Any modification causes bundleIntegrity to FAIL.
    • Supplemental signals are recorded alongside the artifact but outside the hash. Their absence or modification does NOT cause core verification to fail. They may be surfaced by the verifier as supplemental evidence.

    Refer to Verification Semantics for how signal scope is reported in verification results.

    Important
    NexArt records signals but does not interpret or enforce them. The protocol treats signals as opaque metadata. Any semantic meaning or enforcement logic is the responsibility of the consuming application.

    Next Steps