Skip to content

Summary

Every EV claim in a playbook must be computed by the blessed code referenced in an Attested Computation concept (/85-computations/), never improvised in prose. This skill defines the execution protocol and the receipt format.

Execution Protocol

  1. Resolve the AC concept (e.g. /85-computations/ev-vertical-spread.md) and read its computation, parameters, and executor frontmatter.
  2. Assemble inputs: fill every parameter marked required: true from live data (ThetaData for options/1-min bars from 2016, Tiingo for underlying EOD). rv_window and garch_forecast are required, fail-closed real-world inputs: the computation refuses to run without them rather than substituting implied vol for the physical distribution. Optional parameters may be null; the computation must tolerate that and emit TODO(data-feed) placeholders in the receipt.
  3. Run: import the module and construct its params dataclass, filling every required: true field, then call compute_ev(params). Running python references/computations/<module>.py executes the hard-coded sample scenario only (useful as a smoke test, not as a real evaluation). The runtime is python; pricing is py_vollib-class Black-Scholes-Merton (py_vollib is used when installed; an exact internal BSM closed form is the fallback).
  4. Record the receipt (below) alongside the playbook decision, with the regime context from /60-regimes/.

Receipt Format

The executor returns a flat, top-level receipt with exactly four keys — computation, inputs, outputs, code_version. Any extra top-level key is rejected by the attester:

{
  "computation": "ev_vertical_spread.py",
  "inputs":  { "spot": 450.0, "iv": 0.22, "dte": 45, "...": "all declared parameters" },
  "outputs": { "ev_net": -0.02, "ev_gross": 0.11, "baseline_vrp": 0.031, "baseline_garch": null },
  "code_version": "ab12..."
}
  • computation — the file name (basename) of the computation module that produced the receipt; it must equal the basename of the AC's declared computation path.
  • inputs — the exact values passed to compute_ev, one key per declared parameter.
  • outputs — the EV dict, including ev_net (GARCH-based), baseline_ev_rv (the SAME structure's EV under the RV distribution), baseline_vrp (IV−RV in annualized vols; calendars use front IV − rv_window), and edge_vs_rv (ev_net − baseline_ev_rv). A run without the RV baseline populated is not sufficient evidence of edge.
  • code_version — the plain sha256 hexdigest of the computation file's own source, computed at runtime by the module (see attester).

Attestation

Run references/attesters/ev-binding.py against the receipt. The attester parses the declared parameters and the declared bundle-rooted computation path from the AC concept frontmatter in /85-computations/ and verifies (a) the supplied computation path resolves to that exact declared path and receipt.computation equals the file's basename, (b) inputs contain exactly the declared parameter names (extras and missing required parameters are rejected) with matching types, (c) outputs carry the mandatory EV keys, (d) code_version matches the sha256 hexdigest of the referenced computation file, and (e) the receipt has no top-level key outside {computation, inputs, outputs, code_version} — extra keys are rejected. A fail verdict invalidates the EV claim.

Re-execution. Once those structural checks pass — code_version in particular, which proves the file on disk is the code that produced the receipt — the attester imports that file, rebuilds its params dataclass from receipt.inputs, calls compute_ev, and requires every recorded output to match the recomputed one (tolerance 1e-5 absolute, absorbing only last-digit rounding flips between BSM implementations). An invented, missing, or altered output key fails. Re-execution is skipped when a structural check fails; the verdict then reports "reexecuted": false. Computation contract: a module exposes compute_ev(p) whose parameter is annotated with a dataclass.

The attester reports two independent results:

  • verdict — is the receipt well-formed, bound to the declared computation, and reproduced by re-execution?
  • ev_gate — may this receipt support a proposal? This is Layer 1 of Amendment 2026-09-17/01: ev_net > 0 under the physical forecast, net of costs. Derived from ev_net so that receipts predating the amendment remain evaluable, and evaluated only on outputs re-execution has confirmed — a receipt that fails attestation reports ev_gate: "unverified", never "pass".

The exit code is 0 only when both pass, so a caller that checks only the exit status still cannot advance a negative-expectancy candidate.

edge_vs_rv is retained in the outputs as a diagnostic, not a gate — it reduces algebraically to garch_forecast < rv_window and carries no information about profitability.

Attesting the Production Engine

The daily round prices with ev_ladder.py, not these computations. Its ladders are attested by ladder-binding.py, which re-executes build_ladder on the recorded snapshot and trades — see the EV Ladder concept. It attests reproducibility only; it applies no EV gate.

Verifying a Historical Receipt

code_version is the sha256 of the computation file, so editing a computation invalidates every receipt it previously produced. The repository is the recovery path: check out the commit the receipt was produced under and attest there.

# find the commit whose source matches the receipt's code_version
cv=$(python3 -c "import json,sys;print(json.load(open(sys.argv[1]))['code_version'])" <receipt>)
for c in $(git rev-list HEAD -- options-system-wiki/references/computations/<module>.py); do
  h=$(git show $c:options-system-wiki/references/computations/<module>.py | sha256sum | cut -d' ' -f1)
  [ "$h" = "$cv" ] && echo "produced under $c" && break
done

# attest against that source, without disturbing the working tree.
# Copy in the CURRENT attester first: one checked out from an older commit
# may predate re-execution and would only shape-check the receipt.
git worktree add --detach /tmp/histcheck <commit>
cp options-system-wiki/references/attesters/ev-binding.py \
   /tmp/histcheck/options-system-wiki/references/attesters/ev-binding.py
cd /tmp/histcheck/options-system-wiki
python3 references/attesters/ev-binding.py --computation <path> --receipt <path>
cd - && git worktree remove --force /tmp/histcheck

Verified for the 2026-09-09 condor rehearsal receipt: against commit de4a658 it re-executes bit-for-bit (verdict: pass, reexecuted: true), and a coherent forgery of it is refused with every fabricated value named beside the recomputed one. Against current source it fails on code_version, as it should.

References

  • OKF v0.2 specification, section 10 (EV contract): ../../../OKF_SPEC_v0.2.md
  • py_vollib documentation: https://py_vollib.readthedocs.io/
  • ThetaData API documentation: https://docs.thetadata.us/
  • Tiingo API documentation: https://www.tiingo.com/about/api

Links