Evidence contract

Unknown is a first-class result.

NetOkay Evidence is the single JSON EvidenceBundle that a CLI or Agent run writes to stdout. It records the runtime that ran the check, the bounded policy decisions, every observation with its facts and limitations, and what was redacted. A missing observation is never promoted to a green check.

Get the current schema from the CLI with netokay schema; the tables below summarise version 2.

Bundle fields

Field Type Meaning
schema_version string Schema major.minor, currently 2.x. Readers should reject other majors.
bundle_id string Unique identifier for this run.
run_status enum How the run ended: completed, rejected, cancelled, or errored.
outcome enum Overall reading: ready, attention, incomplete, rejected, or error.
started_at / completed_at string UTC timestamps for the run.
duration_ms integer Wall-clock duration of the run.
runner object cli_version, core_version, and control_profile_version that produced the bundle.
execution_context object Where the check ran: process kind, agent_host, os_family, architecture, container and proxy signals, and agent_internal_runtime.
intent object Requested transport (http, https, sse, wss, mcp), profile_id, and has_target.
policy object Policy version, run_decision, target_decision, and the reasons behind them.
observations array One entry per check stage; see the observation fields below.
differentials array Pairwise comparisons between two observations, each with its own limitations.
diagnoses array Interpretations: code, summary, evidence_refs, possible_layers, limitations, and suggested_next_steps.
redaction object Lists of what was not_collected, removed, or truncated.
completeness object Whether the control and target checks finished, and what is missing.

Observation fields

Each entry in observations describes one stage of one check. Read status, result_code, facts, and limitations together; a passed HTTPS baseline does not make the selected transport check passed.

Field Type Meaning
check_id string Stable name of the check, for example control-self or control-echo.
scope enum control for NetOkay's own service, target for the URL you supplied.
transport enum http, https, sse, wss, or mcp.
stage enum Where the observation was made: control, policy, dns, tcp, tls, headers, stream, or upgrade.
status enum passed, failed, incomplete, skipped, not_observed, or cancelled.
result_code / reason_code string Machine-readable outcome, for example SSE_PASSED or WSS_PASSED, with an optional reason.
facts object What was observed. Transport details live under facts.template_facts.
limitations array Plain-language statements of what this observation cannot prove.
source enum local_runner or netokay_control.
colo string NetOkay edge location that answered, when known.

What is not retained

NetOkay does not retain credentials, cookies, request bodies, full user-agent values, proxy URLs or credentials, certificate chains, target URLs after policy evaluation, or response bodies.

Agent runtime boundary

agent_internal_runtime remains not_observed. A caller-declared host marker is not attestation. Evidence is local unless a human explicitly shares it.