//DOCS Evidence Contract

Punk Evidence Contract

This is the public contract for how Punk represents execution evidence. It defines what the runtime records, what each proof stage establishes, and what must remain qualified. It is a product specification, not a certification, customer outcome, or claim that every deployment has enabled every control.

The machine-readable companion is the [public claim registry](/marketing-pages/trust/evidence-registry-v1.json).

The Evidence Plane

Punk's opinion is that an agent runtime needs more than model intelligence. Between intelligence and action, the system needs an evidence plane with three explicit contracts:

1. Perception contract: what information and structure the agent received.
2. Authority contract: who may do what, under which policy and consequence

boundary.

3. Adaptation contract: which cheaper or reusable execution path has earned

this request.

Punk implements the adaptation contract and integrates with perception and authority systems. The trace ledger is append-only during its configured retention lifetime. Patterns, artifacts, evaluations, route statistics, and other projections are derived state and must be rebuildable from recorded events.

Route Explanation Contract

Every served response has a route explanation. The canonical TypeScript contract is RouteExplanation in packages/trace-schema/src/index.ts. Its stable core is:

An explanation proves that the runtime recorded a routing decision. It does not prove that the answer was correct, that an estimate became realized savings, or that a policy covered activity which bypassed Punk.

Declarative Artifact Contract

Reusable artifacts are interpreted data, never generated or evaluated source code. The version-one program contains:

{
  "dslVersion": 1,
  "kind": "deterministic_transform",
  "output": "json",
  "outputVar": "result",
  "inputSchema": {},
  "outputSchema": {},
  "steps": []
}

The interpreter accepts these operations:

literal, get, template, ruleset, object, string, number, regex_extract, json_parse, json_stringify, concat, map, and model_fallback.

Execution is bounded by a step ceiling, wall-clock timeout, and string-size limit. The default interpreter limits are 256 steps, 2,000 milliseconds, and 1 MiB per string. Input and output schemas may further restrict an artifact. Invalid, ineligible, timed-out, or schema-invalid artifacts fail open to the live provider where policy permits.

A tool_plan artifact produces a declarative plan; it does not execute the tool. The calling runtime remains responsible for current identity, tool contract, policy, approval, and side-effect enforcement.

Side-Effect Taxonomy

Undeclared SDK tools default to level 3. A lower declared level is not trusted blindly: current tool contracts and policy still gate execution. Level describes consequence, not whether the output is useful or safe in every context.

Replay Contract

Replay evaluates a candidate against reconstructed historical runs. It uses recorded inputs, expected outputs, and recorded tool results. The artifact DSL cannot call tools or the network, so replay cannot reproduce a historical external effect.

For deterministic and schema-deterministic tasks, promotion requires exact deterministic replay with zero recorded mismatches. Runs with incomplete model output, failed structured-output evidence, terminal integrity errors, or uncorrected negative feedback are not accepted as ground truth.

Replay establishes agreement with eligible recorded examples. It does not establish current-world freshness, complete dataset coverage, or production fitness on unseen work.

Shadow Contract

Shadow evaluates a candidate beside the live path while the live result remains authoritative. Shadow evidence compares candidate behavior with current work; it does not authorize the candidate to serve.

Replay and shadow are complementary:

• replay asks whether a candidate agrees with accepted history;
• shadow asks whether it continues to agree on current traffic;
• neither stage may use evaluation as permission to repeat a real-world write.

Hybrid artifacts have model-dependent fields. They require at least 10 shadow passes and confidence of at least 0.75 under the default implementation, and they are never automatically promoted.

Promotion Contract

The default promotion thresholds are implementation defaults, not universal safety guarantees:

Tenant-local preference may tighten or modestly relax shadow and confidence thresholds, but it cannot reduce shadow evidence below 3 passes or confidence below 0.60. It cannot change the replay floor, negative-pattern gate, side-effect ceiling, or deterministic-type allowlist.

Read-only tool_plan artifacts may automatically qualify up to side-effect level 1 because they emit a plan rather than execute an effect. Plans for write-capable tools and artifact types outside the deterministic allowlist require human approval. Eligibility and automatic promotion are deliberately separate decisions.

When canary rollout is enabled, promotion begins at 1% of eligible pattern traffic, then can advance to 10% and 25%. Each rung requires its own evidence window; the current implementation requires 25 live-plus-shadow passes per rung and holds or degrades on failure evidence.

Economics Contract

Punk keeps four economic states distinct:

• Recorded cost: provider or bounded estimated cost attached to an actual

execution.

• Realized savings: avoided reference cost persisted for an optimized route

that actually served.

• Estimated opportunity: forward-looking potential based on a stated

baseline and assumptions.

• Ghost savings: observe-mode counterfactual where the live path still

served.

No savings number is complete without the route, reference method, population, time window, failure accounting, and evidence source. A benchmark is not a customer invoice, and an estimate is not realized value.

Public Claim Standard

Public claims use one of these evidence classes:

Every quantitative claim must identify its unit, population, denominator, measurement date, code or product version, failure/exclusion handling, and limitations. Test counts and repository size are engineering inventory, not proof of customer outcomes.

Versioning and Review

This contract describes the repository reviewed on July 28, 2026. Runtime types remain canonical when this narrative and the code differ. Material contract changes should update this document, the machine-readable registry, relevant tests, and the review date together.