Framework

Gadfly applies the method in When meaning is load-bearing. This page is the bridge between the essay's symbols and the library's public names, and deliberately an overview: the tutorial runs one frame, and the reference lists every callable.

---

The path from premise to verdict

Stage	What it makes	What stays fixed
situate	a checked Frame and its SHA-256	every declared coordinate, including grain and battery
plan	the trials derived from the frame	trial bodies and order; the caller may inspect them before spending anything
run	one Record per call	the exact body, input, trial and quorum index recorded beside the observation
judge	one Finding per input	the frame, battery, body hashes, trial set, quorum and label vocabulary
overall	one Overall over the findings	every input's category and evidence while combining the frame-level answer

Gadfly is a library with no hidden store: run() is the only stage that calls a battery, and records go to your on_record callback as they are made. judge() recomputes the reading from those records. Keep them as JSON Lines, database rows or fixtures, but keep them.

---

The essay and the frame

The essay's situated use becomes the frame's descriptive keys:

$$L=(I,B,r,g,P,T,B_0,C,p)$$

and its assessment frame adds the anchors, the observation map, the declared interventions and standing:

$$\mathrm{\Gamma }=(A,r,g,P,T,B_0,p,o_p,D,\sigma )$$

Essay	Frame	Meaning in Gadfly
$I$	relation	the premise under intervention
$v$	locus	where it acts
$B$	body.spans	the text it lives in, at the declared grain
$r,g,P,T$	role, grain, purpose, trajectory	whose reading, at what unit, for what path
$B_0$	baseline	everything pinned for the comparison
$C,p$	crossing, promise	the boundary and the consequence required there
$A$	anchors	span ids removed by ablation
$o_p$	observe.instruction, labels, order plus your battery	what the scorer reads and the complete label vocabulary
$D$	interventions, allowed, standing	the admissible changes, allowed influence, and sampling standing
$\sigma$	standing.quorum, agree, stable	observation standing
${\simeq }_p$	exact label equality	no hidden similarity function
$E_{p,\delta }$	allowed	the permitted influence relation
carriage checks	carriage	whether a category waits for the checks it needs, every carriage check for carried and a control that moved for cooled (all-checks), or is named with its open checks beside it (listed)
scope check	outsideScope, scopeCheck	the owner's exclusion, and the owner's own check of it

The code hashes the whole frame, including the situated-use keys. This is stricter than changing only $\mathrm{\Gamma }$: editing any coordinate creates a new frame hash and requires records to be made or replayed under that new frame.

materialized, outsideScope and scopeCheck are declarations about the receiving side: Gadfly reads them, it does not inspect the receiving system. See Architecture and limits.

---

The four data objects

Object	Created by	What it answers
Frame	situate	what was declared, under one hash
Trial	plan	what one intervention changes
Record	run through on_record	what one scorer call read and observed
Finding / Overall	judge / overall	what the fixed rules say, with evidence and obligations

The records are the durable evidence. judge does not rerun a scorer and does not consult the frame's source file; it reads the records, checks they are records this frame could have made, and applies the rules.

---

Where the rest lives

Each part of the frame has a page of its own.

• Your first frame: one frame, from JSON to verdict.
• Write a frame: every key, and what the parser refuses.
• Interventions: each trial and its cost.
• Reading a verdict: the category rules, evidence and obligations.
• Batteries: deterministic and live scorers.
• Glossary: the essay's words, in a sentence each.