FrankenRobotics

Type sketches

5,440 words18 subsections1 table18 listingsPlan version 1.1

On this page18
I.1 Groups, frames, cones and portsI.2 The claim product and evidenceI.3 A mission query and its answerI.4 A proof object and a certificate bundle entryI.5 A model variant and a shape classI.6 A clock, a phase accumulator and the seven instantsI.7 The transactional stepI.8 A requirement and its monitorI.9 A study, in two typesI.10 A qualification request and its receiptI.11 A counterexample worldI.12 An intervention and a forkI.13 A ladder rung and an allocation decisionI.14 A family policy and an inheritance mapI.15 An energy budget and a shieldI.16 A calibration recordI.17 A build packetI.18 Backends, the environment, the record

DESIGN. These sketches fix intent, not signatures. Where a chapter prints a sketch of the same type, the chapter governs and this appendix repeats it; where two chapters sketch one type differently, the sketch here is their union and the difference is named in a note. Field types that are not defined here (Qty, Ratio, Blake3, ModelId and the other identities of §11) are the obvious ones.

I.1 Groups, frames, cones and ports

/// A Lie group with two retractions. Its laws are G0 property tests (§13.8), not comments.
pub trait LieGroup: Copy {
    type Algebra: LieAlgebra;
    const DIM: usize;
    fn identity() -> Self;
    fn compose(self, rhs: Self) -> Self;
    fn inverse(self) -> Self;
    fn exp(x: Self::Algebra) -> Self;              // deterministic elementary functions
    fn log(self) -> Self::Algebra;
    fn cay(x: Self::Algebra) -> Self;              // +, −, ×, ÷, √ only
    fn cay_inv(self) -> Self::Algebra;
    fn adjoint(self) -> <Self::Algebra as LieAlgebra>::Operator;   // Ad_g
}

pub trait LieAlgebra: Copy {
    type Dual: Copy;                               // 𝔤*: momenta, wrenches
    type Operator;                                 // linear maps on 𝔤
    fn bracket(self, rhs: Self) -> Self;
    fn ad(self) -> Self::Operator;
    fn coad(self, mu: Self::Dual) -> Self::Dual;   // ad*_x μ = (ad_x)ᵀ μ, no minus sign (§11.2)
    fn pair(self, mu: Self::Dual) -> Power;        // ⟨μ, x⟩, in watts
}

/// A joint: a product of one-parameter subgroups of SE(3) given by a screw basis (C-01, T-11).
pub struct JointSubgroup { class: HerveClass, screws: ScrewBasis, closed_under_bracket: bool }

/// `a_from_b`. Composition type-checks: Transform<A,B> * Transform<B,C> = Transform<A,C>.
pub struct Transform<A: Frame, B: Frame> { motor: fs_ga::Se3, _frames: PhantomData<(A, B)> }
pub struct TwistIn<F: Frame>  { xi: fs_ga::Twist,  _f: PhantomData<F> }
pub struct WrenchIn<F: Frame> { w:  fs_ga::Wrench, _f: PhantomData<F> }

/// Three maps, three types, so a wrench is never moved by the twist map (§11.2, §13.3).
pub struct TwistMap<A: Frame, B: Frame>(Transform<A, B>);          // Ad_g: a twist in b to a twist in a
pub struct WrenchPushforward<A: Frame, B: Frame>(Transform<A, B>); // Ad_g⁻ᵀ: a wrench in b to a wrench in a
pub struct WrenchPullback<A: Frame, B: Frame>(Transform<A, B>);    // Ad_gᵀ: a wrench in a to a wrench in b

/// A symmetric cone, by its Jordan algebra. Instances: the nonnegative orthant, the three-dimensional
/// friction cone, and the four-dimensional cone (normal, two tangential, spin) of §18.
pub trait Cone {
    type Point;
    fn jordan(a: &Self::Point, b: &Self::Point) -> Self::Point;
    fn spectral(a: &Self::Point) -> Spectrum;
    fn project(a: &Self::Point) -> Self::Point;    // T-07: P(x) ∈ 𝒦, P(x) − x ∈ 𝒦*, ⟨P(x), P(x) − x⟩ = 0
    fn barrier(a: &Self::Point) -> f64;
}

/// A convex contact potential whose negative gradient is the impulse (C-06).
pub trait ContactLaw { fn potential(&self, vc: ContactVelocity, p: &InterfaceCard) -> ConvexTerm; }

/// What a free tree limb presents to its parent at a mechanical port, at one instant (§14.6).
/// Positive semidefinite, never guaranteed definite: it cannot be inverted at the port.
pub struct LimbPortPacket { inertia: SymPsd6, bias: WrenchIn<PortFrame> }

I.2 The claim product and evidence

/// The four evidence classes of §12. Combination takes the minimum.
pub enum EvidenceClass { Estimated, Tested, Certified, Proved }   // Ord: Estimated < Tested < Certified < Proved

/// Exactly one of the seven claims of §8.
pub enum ClaimKind { Proof, KnownAnswer, Parity, Fidelity, DesignComparison, Reality, Performance }

/// A typed leaf: evidence for one claim kind K. Its class is set only by the checker that produced it,
/// and no constructor of Evidence<Proof> exists outside frob-lemma (GATE-LEMMA-06).
pub struct Evidence<K> {
    class: EvidenceClass,             // private
    scope: Scope,                     // model, tier, domain, quantifier prefix
    assumptions: AssumptionSet,       // each with its polarity (C-18)
    receipts: Vec<ReceiptId>,         // certificate hashes, checker identities, study receipts
    flags: NoAuthorization,
    kind: PhantomData<K>,
}

/// What a result asserts, how strongly, about what, and that it authorizes nothing. Owned by frob-core;
/// carried in every output envelope (§32) and read from every bundle by frob-verify (§12).
pub struct ClaimProduct {
    kind: ClaimKind,
    class: EvidenceClass,             // minimum over inputs; no setter
    weakest: InputRef,                // the input that set the class: content hash and field path
    scope: Scope,                     // design family, world family, quantifier order, horizon, validity region
    tier: Tier,                       // lowest physics tier among the inputs
    determinism: DetClass,            // weakest of D0..D4 among the inputs
    reality: RealityScope,            // NoClaim, or the calibrated family a band was issued for
    conditions: FlagSet,              // union over inputs: tier-sensitive, controller-sensitive, model-conditional
    inputs: Vec<InputRef>,            // every consumed artifact, each with its own claim product
    authorization: NoAuthorization,
}

impl ClaimProduct {
    /// The only way to build a product from parts. Class, tier and determinism take the weakest; scope takes
    /// the intersection; conditions take the union; a mismatch of quantifier order is a refusal.
    pub fn combine(kind: ClaimKind, parts: &[ClaimProduct]) -> Result<ClaimProduct, Refusal>;
}

/// `False` is a unit type that serializes as the JSON literal false. No constructor, setter or deserializer
/// yields `true`; a reader rejects an artifact in which a flag is absent or true.
pub struct NoAuthorization {
    pub execution_authorized: False,
    pub hardware_safety_signoff: False,
    pub sim_to_real_certified: False,
}

/// Build packets add a fourth flag (§31.12).
pub struct PacketAuthorization { pub base: NoAuthorization, pub fabrication_released: False }

/// Reality status of a result (§30). Everything outside a calibrated cell is NoClaim.
pub enum RealityStatus { NoClaim, Synthetic, PublishedAnchor, Candidate, Calibrated, Retired }

// Three things do not exist, and a compile-fail test pins each: a conversion from ClaimProduct into a
// Proved value; a setter for `class`; a public constructor that takes a class as an argument.

Note. §8.2 writes the product as one struct with combine, and §12.2 writes it as a pair ClaimProduct<A, B> of typed leaves whose class is the minimum. They are one mechanism: the pair is the two-input case of combine. The serialized flags object is spelled flags in a bundle (§12.4), authorization in an envelope and a build packet (§32.4, §31.12), and no_authorization in a verdict, a qualification receipt and a counterexample world (§24, §26). The three field names inside it are the same everywhere.

I.3 A mission query and its answer

/// A `.fmission` document (§25.3.2). Its canonical bytes hash to the MissionId.
pub struct MissionQuery {
    design_domain: DesignDomain,      // family, topologies, ports, isomorphisms, free and bound parameters, tolerances
    world: WorldFamily,               // nonempty; kind BoundedSet or Population; persistence per hidden parameter
    observation: Channel,             // fields, noise bounds, timing in the seven instants of §20
    policy_class: PolicyClass,        // Causal on the history of Y; indexing; authority; randomization
    horizon: Horizon,                 // Static | Time(Qty) | Ticks(u64) | TerminalModes(..)
    predicates: Predicates,           // accept, hard_loss, margins; atoms carry comparator and units
    quantifiers: Vec<Binder>,         // ordered; part of the MissionId
    objective: Option<Objective>,     // a declared cost and the claim wanted
    evidence: EvidenceProfile,        // Exact | Enclosed | Empirical, with accepted classes
    resolution: Resolution,           // largest unresolved set accepted, in a stated measure
    response: Vec<ResponsePart>,
    budget: Budget,                   // wall, CPU core, GPU, referee and checker seconds; sync_wait_ms
}

pub enum Binder { Exists { var: Var, scope: PolicyScope }, ForAll { var: Var },
                  Prob { var: Var, population: PopulationId, at_least: Ratio, confidence: Ratio } }

pub struct Cell { topology: TopologyId, chart: ChartId, bounds: Vec<Bound>,      // closed or open per end
                  units: Vec<Unit>, assumptions: AssumptionSet, policy_scope: PolicyScope }

pub enum Verdict { Inner(Vec<ProofRef>), Excluded(Vec<ProofRef>), Unresolved(Vec<Explanation>) }

pub enum Explanation { StraddlesThreshold, ModeSequenceUnenclosed, SolverFailure, BudgetExhausted,
                       CompetingMechanisms(Vec<MechanismRef>), NeedsMeasurement(MeasurementRef) }

pub struct Witness { proof: ProofRef, kind: ProofKind, at: ChartPoint, payload: WitnessPayload }

pub struct CostBounds { incumbent: Ratio, lower_bound: Ratio, unit: Unit, attained: bool, gap: Ratio }

/// The answer carries I ⊆ F ⊆ O as a list of cells. It is immutable and addressed `a:…`; a later query with
/// more budget produces a new answer that refines it.
pub struct Answer { mission: MissionId, cells: Vec<(Cell, Verdict)>, witnesses: Vec<Witness>,
                    cost: Option<CostBounds>, next_test: Option<NextTest>, claim: ClaimProduct, bundle: BundleHash }

impl Answer {
    pub fn inner(&self) -> impl Iterator<Item = &Cell>;        // cells with a constructive witness
    pub fn excluded(&self) -> impl Iterator<Item = &Cell>;     // cells with an exclusion proof
    pub fn unresolved(&self) -> impl Iterator<Item = &Cell>;   // work still to do, each with its reason
    /// The outer set is the domain minus the excluded cells (INV-AUGUR-02): inner ∪ unresolved.
    pub fn outer(&self) -> impl Iterator<Item = &Cell>;
}

I.4 A proof object and a certificate bundle entry

frob-mission emits plain proof objects. frob-lemma writes them into .frobcert bundles against the schema of §12.4 and shares no code with the reader. frob-cert reads a bundle with the standard library alone, and frob-verbs runs the checker before an answer is returned.

/// A proof object as frob-mission emits it (§25.5). Numbers are exact rationals (reduced, positive
/// denominator) or outward-rounded intervals with a declared implementation and precision.
pub struct ProofObject {
    id: ProofRef,                     // "p0", "p1", … within one answer
    kind: ProofKind,                  // closed registry frob.cert.kinds/1
    cell: CellRef,
    establishes: Establishes,         // the prefix, horizon, policy class and cell the proof is about
    payload: ProofPayload,            // witness vectors, dual vectors, enclosures, policy tables
    side_conditions: Vec<ProofRef>,   // sub-certificates a rule requires
    primitive_equations: Vec<Equation>, // in Unicode text and as an expression DAG
    expects: Expected,                // Inner | Excluded
}

pub enum ProofKind { LpPrimal, LpFarkas, ConicFarkas, IntervalBox, TaylorBox, SosGram, FiniteGame, AliasPair,
                     MonotoneTransport, SymmetryTransport, Partition, Composition, ProductUnreachable,
                     TraceWitness, SampleCoverage }

/// One `.frobcert` file (schema frob.cert/1): everything needed to re-check one claim on a machine that has
/// neither the agent, a GPU nor the simulator.
pub struct Bundle {
    schema: SchemaId,                 // "frob.cert/1"
    claim: ClaimStatement,            // kind, class, quantifiers, horizon
    query: Embedded,                  // BLAKE3 and the canonical bytes of the statement it certifies
    definitions: Definitions,         // units, frame, clocks, ordered ports
    assumptions: Vec<Assumption>,     // each with `survives`: grow | shrink (C-18)
    plant: PlantRef,                  // model and policy class
    domain: Domain,                   // chart and cell
    proof: BundleProof,               // kind from the registry of §12.4, primitive equations, payload
    checker: CheckerRef,              // name and build
    expected_verdict: CheckVerdict,
    lineage: Lineage,                 // Merkle root; alpha_spend entries for qualification receipts
    flags: NoAuthorization,
}

/// What the auditor returns, with the first failing rule named.
pub enum CheckVerdict { Accept, Reject { rule: RuleId }, Unsupported { kind: String } }

Note: one closed registry names the proof kinds, frob.cert.kinds/1, in §12.4. §25.5.2 lists the rows of that registry that mission answers use, under the same names, so a proof object's kind is the bundle's kind and frob-lemma maps nothing when it writes a bundle.

Kinds of frob.cert.kinds/1 (§12.4) Used by Class
lp-primal, lp-farkas, conic-farkas, interval-box, taylor-box, sos-gram, finite-game, alias-pair, monotone-transport, symmetry-transport, partition, composition, product-unreachable Mission answers (§25.5.2) Certified
trace-witness Mission answers: a replayed execution At most Tested
sample-coverage Mission answers: an empirical bound Estimated; never a proof
poly-identity, rational-ldlt, interval-root, complex-connectivity, tube-inclusion, rewrite-trace, orbit-count, group-enumeration, energy-budget, alpha-root, lean-capsule Kernel and analysis certificates As §12.4

I.5 A model variant and a shape class

/// The capacities one static step plan is built for (§17.4, §21.11). Its hash, the ShapeClassId, is part of
/// the StepPlanId. One kernel set and one launch graph exist per class per device.
pub struct ShapeClass {
    pub n_v: u16,                 // degree-of-freedom capacity: one of 12, 18, 24, 32, 48, 64 by default
    pub links: u16,               // link capacity
    pub depth: u8,                // maximum tree depth
    pub samples: u16,             // collision samples tested per world
    pub contacts: u16,            // C of §16.6
    pub rows: u16,                // R of §16.6
    pub actuators: u16,
    pub sensor_layout: SensorLayoutId,
    pub policy_layout: LayoutId,
    pub contact_law: LawId,
    pub precision: PrecisionProfile,   // default | stiff
    pub iterations: u8,           // the lockstep iteration count, a class constant
    pub single_structure: bool,   // P-A: one tree, unmasked path
}

/// One model variant: a read-only table per model slot, about 192 bytes per link (12 kB for a 64-link variant,
/// §21.11); collision sample lists are counted separately (§17.4).
pub struct ModelTable {
    pub model: ModelId,
    pub level_start: Vec<u16>,    // links sorted by depth; ranges per level
    pub parent: Vec<u16>,         // parent index, less than the link's own; padding links are roots of nothing
    pub placement: Vec<Se3Packed>,     // parent_from_joint
    pub screw: Vec<[f32; 18]>,    // screw basis S in ℝ^(6×3)
    pub screw_cols: Vec<u8>,      // k = 0 (padding), 1, 2 or 3 active columns: joint classes are data
    pub inertia: Vec<[f32; 10]>,  // zero for padding links
    pub limits: Vec<JointLimits>,
    pub actuator_slot: Vec<u16>,
    pub sample_range: Vec<(u16, u16)>,
}

/// A world is a row of indices into its bucket's tables, plus its address.
pub struct WorldSlots { pub model: u32, pub scene: u32, pub task: u32, pub job: u32, pub addr: WorldAddr }

/// One shape class on one device: one arena, one compiled kernel set, one step plan, one launch graph.
pub struct Bucket { class: ShapeClass, device: DeviceId, model_variants: u16, scene_variants: u16, worlds: u32 }

/// A slab is touched by the host only under an epoch-fenced lease (§21.10).
pub enum Access { Device, HostRead, HostWrite }
pub struct SlabLease { slab: SlabId, epoch: u64, access: Access }   // valid only while `epoch` is committed

Note. §17.4 spells the capacities n_v, links, depth, samples, contacts, rows, actuators and carries single_structure; §21.11 spells them with a _cap suffix, adds policy_layout, contact_law, precision and iterations, and names the world row WorldRow with 16-bit variant indices. The sketch above is the union under the names of §17.4, which owns the type.

I.6 A clock, a phase accumulator and the seven instants

/// Simulation time: an unsigned 64-bit count of quanta of 1/Q seconds, Q the least common multiple of the
/// denominators of every period in the run (§20.4.1). Admission refuses Q above 2⁴⁰.
pub struct Quanta(pub u64);

pub struct ClockSpec { period: Quanta, phase: Quanta, rate_error: Ratio, intra_step: IntraStep }
pub enum IntraStep { Split, Interpolate { bound: Bound }, Hold }

/// Integer addition and comparison only: determinism class D0, and no drift.
pub struct PhaseAccumulator { next_event: Quanta, period: Quanta }
impl PhaseAccumulator {
    /// At a boundary at time t: fire while next_event ≤ t, advancing by the period each time.
    pub fn fire(&mut self, t: Quanta) -> u32;
}

/// The seven instants (§20.4.2). Order constraints: sample ≤ exposure ≤ arrival; a packet is used by a
/// decision at t only if its arrival is at or before t; decision ≤ command ≤ actuation. The timestamp is
/// deliberately unconstrained: it is what the device believes.
pub enum Instant { Sample, Exposure, Timestamp, Arrival, Decision, Command, Actuation }

pub struct Packet {
    sensor: SensorId, seq: u32,
    t_sample: Quanta, t_exposure: Quanta, t_stamp: DeviceTime, t_arrival: Quanta,
    lateness: Quanta, mask: MaskRef, payload: BufRef,
}
pub struct Command { t_decision: Quanta, t_command: Quanta, t_actuation: Quanta, payload: BufRef }

/// Every observation exposes its age, decision minus sample, as an integer count of quanta.
pub struct Age(pub Quanta);

I.7 The transactional step

/// Step profiles (§16). `Lockstep` is the fixed-step throughput profile; `Strict` and `Referee` are
/// transactional and event-located.
pub enum StepProfile { Lockstep, Strict, Referee }

/// Everything a retried interval must restore so that it equals a first attempt (INV-KIN-02): physical
/// state, contact feature memory and impulses, warm starts, actuator and thermal state, clock phases and
/// packet queues, controller and estimator state, terrain edits, energy-ledger accumulators, event
/// counters and the command cursor. Random streams are counter-based and have no state to restore.
pub struct RestoreSet { /* the fields above */ }

/// A candidate interval is built beside the committed state and becomes visible in one step.
pub struct Transaction<'a> {
    committed: &'a Committed,         // read through a named commit_epoch and nothing else
    interval: (Quanta, Quanta),       // a base interval [t0, t1), fixed by the schedule, never by the state
    checkpoint: RestoreSet,
    attempt: u8,                      // 0..=3; selects a numerical plan only (ADR-KIN-05)
    work: VecDeque<(Dyadic, Dyadic)>, // sub-intervals on the dyadic grid of the base interval, L ≤ 16
    events: u8,                       // at most 64 per base interval
}

pub enum StepOutcome {
    /// commit_epoch advances; state, impulses, sensor inputs, diagnostics and the attempt index are
    /// published together.
    Committed { epoch: u64, attempt: u8, events: Vec<EventRecord>, checks: CheckReport },
    /// After the last attempt the checkpoint is restored and nothing from the interval is published.
    /// A numerical failure is not a physical failure: the world is Faulted with cause numerical-fault.
    Faulted { refusal: Refusal /* FROB-REF-220 or -221 */ },
}

/// Noise that acts over an interval is defined on the dyadic tree of the base interval, so a retry can
/// refine a path and can never redraw it.
pub struct NoiseAddress { world: WorldAddr, base_interval: u64, stream: StreamId, level: u8, index: u32 }

I.8 A requirement and its monitor

/// A comparison of two expressions of one dimension, with a scale of that dimension (§24.5).
pub struct Atom { id: Ident, cmp: Cmp, lhs: Expr, rhs: Expr, scale: Scale }
pub enum Cmp { Gt, Ge, Lt, Le, Eq }
pub enum Scale { Qty(Qty), Exact }                 // Exact: integer-valued signal, margin +1 or −1
pub enum Expr { Signal(SignalId), Qty(Qty), Op(ArithOp, Vec<Expr>), Delay(Qty, SignalId) }

pub struct Window { lo: Qty, hi: Qty, round: Option<Rounding> }   // closed; exact rational comparison of ticks
pub enum Past { Atom(Ident), And(Vec<Past>), Or(Vec<Past>), Not(Box<Past>),
                Historically(Window, Box<Past>), Once(Window, Box<Past>), Since(Window, Box<Past>, Box<Past>) }
pub enum Future { Past(Past), And(Vec<Future>), Or(Vec<Future>), Not(Box<Future>),
                  Always(Window, Box<Future>), Eventually(Window, Box<Future>),
                  Until(Window, Box<Future>, Box<Future>) }

pub struct Requirement {
    clock: ClockId,                    // each requirement names the clock it is evaluated on
    atoms: Vec<Atom>,
    online: Vec<(Ident, Past)>,        // compiled into kernels of the last stage of the batched step
    verdict: (Ident, Future),          // evaluated offline on the completed trace
    examples: Vec<(TraceRef, Label)>,  // at least two satisfied and two violated
}

/// Two monitors, one function. Online: fixed memory of 2·W values per operator node and world, no
/// data-dependent control flow. Offline: a two-pass evaluator on the CPU. Minimum, maximum and negation are
/// exact in floating point, so both return identical bits for identical atom values.
pub trait Monitor {
    fn margin(&self, tick: Tick) -> Margin;        // dimensionless; its sign agrees with the Boolean value
    fn decided_at(&self) -> Option<Tick>;          // the tick at which a prefix fixed the verdict
}

/// The unit that scorecards, studies and searches count (schema frob.verdict/1, stored in `.frun`).
pub struct VerdictRecord {
    task: TaskId, requirement: Ident, world: WorldAddr, model: ModelId, controller: ControllerId,
    verdict: VerdictValue,             // Satisfied | Violated | Undetermined | Invalid
    margin: f64, binding_atom: Ident, binding_time: Qty, decided_at: Qty, reason: Option<FailureClass>,
    coverage: Coverage,                // Sampled | Interval, with the count of missing samples
    boundary: BoundaryFlag,            // flagged inside the guard band of 2⁻²¹ and re-evaluated exactly
    atoms_min: Map<Ident, f64>, evidence: ClaimProduct, no_authorization: NoAuthorization, trace_digest: Blake3,
}

I.9 A study, in two types

/// A registered plan to answer one comparative or absolute question. It declares its type when it is
/// created and keeps it (INV-ARENA-05). The two types are never mixed inside one study.
pub enum Study { Anytime(AnytimeStudy), FixedN(FixedNStudy) }

pub struct AnytimeStudy {
    null: Hypothesis, margin: Qty,
    span: LossSpan,                    // a bound on the paired difference, fixed before the first observation
    betting_rule: RuleId, level: Ratio, budget: Budget,
    // reports: the e-value, the confidence sequence, pairs used, the stopping reason
}

pub struct FixedNStudy {
    n: u32, rule: RuleId, level: Ratio, margin: Qty,
    preanalysis: PreAnalysis,          // computed before the first episode; a study without one is refused
    // reports: counts, the interval, the verdict, the pre-analysis hash. The verdict is computed once, at n.
}

/// Which verdicts are reachable at this n and level, and the power at declared alternatives.
pub struct PreAnalysis { outcomes: u64, reachable: Set<StudyVerdict>, power: Vec<(Alternative, Ratio)>, hash: Blake3 }
pub enum StudyVerdict { Promote, Inferior, PracticalTie, Inconclusive }

/// What `study.plan` returns: the content address of the resolved manifest. Planning runs no physics.
pub struct StudyPlan {
    designs: Vec<DesignId>, scene: SceneRef, task: TaskId, controller_arm: ControllerArm,
    seed_protocol: SeedProtocol,       // pairing by (world, replicate); clusters are the unit of inference
    budget: Budget, backend: BackendRequest, study: Study, estimate: CostEstimate,
}

/// The accounting identity every paired study satisfies:
/// a_only + b_only + both + neither + unscored = planned.
pub struct PairCounts { a_only: u32, b_only: u32, both: u32, neither: u32, unscored: u32, planned: u32 }

I.10 A qualification request and its receipt

/// Request i of a campaign in the blinded lane (§24.13). Hashed into the ledger with an idempotency key
/// before any confirmation world exists (INV-QUAL-04).
pub struct QualifyRequest {
    campaign: CampaignId, index: u32,
    alpha_total: Ratio,
    alpha_i: Ratio,                    // α / [i·(i + 1)]; spent whether or not the answer is liked
    candidate: Arm, baseline: Arm,     // each a design and a controller
    task: TaskId, claim: String,
    study: Study,                      // for FixedN, the pre-analysis is computed at α_i
    tier_plan: TierPlan, clusters: u32, budget: Budget,
    commit: Commit,                    // ledger sequence (a string on the wire), hash, idempotency key
}

/// All the agent receives. Sealed until the campaign closes: world addresses, per-unit outcomes,
/// telemetry, stills.
pub struct QualifyReceipt {
    campaign: CampaignId, index: u32, alpha_i: Ratio, alpha_spent: Ratio,
    decision: Decision,                // Promoted | NotPromoted | Inconclusive
    units_used: u32, receipt_hash: Blake3, no_authorization: NoAuthorization,
}

I.11 A counterexample world

/// A minimal counterexample world (`.fmcw`, schema frob.mcw/1; §26.7). It carries what replays it:
/// identities, edits, addresses and state digests (INV-NEMESIS-04).
pub struct CounterexampleWorld {
    id: WorldId, task: TaskId, requirement: Ident,
    candidate: Candidate,              // model, controller, policy
    base: BaseWorld,                   // a scene and a world address in which the candidate passes
    edits: Vec<WorldEdit>,             // op, path, from, to, and which aspects of the scene each changes
    minimality: Minimality,            // OneMinimal { pairs_exhausted } | NonMinimal(k); tests run; failing seeds
    failure: Failure,                  // class, binding atom, margin, time
    replay: Replay,                    // backend, determinism class, state digests
    promotion: Promotion,              // tier, reproduced, numerical variants tried
    oracle: OracleResult,              // solvable-causal with a witness controller, or the failed necessary condition
    legality: Legality,                // inside the profile; bounds touched, each with its provenance
    prior: Prior,                      // log₁₀ density ratio against the nominal world law
    neighbours_passing: Vec<WorldId>,  // the worlds with one edit removed
    evidence: ClaimProduct, no_authorization: NoAuthorization,
}

I.12 An intervention and a fork

/// `do(factor := value)`. Each intervention changes one declared mechanism, and the model difference it
/// makes is stored with the fork (INV-AUTOPSY-02).
pub struct Intervention { factor: FactorPath, value: Value, mechanism: MechanismId, model_diff: Blake3 }

/// The classification every requested change receives before anything is restored. The five classes are
/// defined in §27.4, which owns the intervention semantics; the fork mechanism of §29.8 implements them.
pub enum ForkClass {
    Continuation,                                  // the null fork, a placebo, replay, teleport
    Exogenous,                                     // restart at the fork tick; nothing regenerated
    ContactAffecting,                              // fork tick; contact memory discarded; first solve cold; labelled
    Information,                                   // fork tick; packet queues and filter state re-initialized
    Structural,                                    // design parameters too: the authored initial condition, settled again
}

/// A fork is a parent episode, a fork tick and a change set. It never mutates its parent.
pub struct Fork {
    parent: EpisodeId, tick: Tick, changes: Vec<Intervention>,
    class: ForkClass, earliest_valid_tick: Tick, forced_by: Vec<FieldPath>,
    addr: WorldAddr,                               // the parent's address extended by a fork path
    null_replay: NullReplay,                       // Bitwise, or the record is unsound and nothing is attributed
}

pub struct Contrast { intervention: Intervention, rescued: (u32, u32), contrast: f64,
                      flip_rate: FlipRates /* at 10⁻¹² and at 10⁻⁷ */, label: CauseLabel }
pub enum CauseLabel { ButFor, Contributing, Joint, Alternative, PrecedesSnapshot, PrecisionSensitive,
                      ChaoticUnattributable, None }

/// Schema frob.autopsy.attribution/1. Class Estimated: a cause in the model at this tier, among the listed
/// factors.
pub struct Attribution { fork: ForkId, tier: Tier, precision: Precision, horizon: Qty, forks_run: u32,
                         null_replay: NullReplay, placebo: Placebo, contrasts: Vec<Contrast>,
                         pairs: Vec<PairContrast>, refused: Vec<RefusedIntervention>, evidence: ClaimProduct }

Note. §27.4 lists five classes and §29.8 three. The sketch nests the three intervention kinds of §27.4 inside the middle class of §29.8 and treats "structural or design-parameter intervention" as StructuralSubstitution.

I.13 A ladder rung and an allocation decision

/// Six rungs, each about an order of magnitude dearer than the one below, each allowed to decide only what
/// its evidence supports (§28.9).
pub enum Rung {
    R0Static,                          // design.check and the bound analyses: refuse or exclude; never ranks
    R1SharedPolicy,                    // a family policy zero-shot, or the baseline controller: discard
    R2FineTuned { fraction: Ratio },   // each fraction is its own rung for calibration
    R3Specialist,                      // one training run: rank finalists, as provisional
    R4Referee,                         // paired re-evaluation on the referee: establish, or label tier-sensitive
    R5RareFailure,                     // a failure-rate bound for finalists
}

/// What a lower rung may do in one stratum, from the rank-agreement ledger (§28.10): Selective when the
/// lower bound on top-weighted Kendall τ is at least 0.7, DiscardOnly between 0.5 and 0.7, Uninformative
/// below 0.5.
pub enum LadderMode { Selective, DiscardOnly, Uninformative }

pub enum AllocationRule {
    FixedTable { eta: u8 },            // successive halving with η = 3; the baseline and every fallback
    ConformalSurvivors { alpha: Ratio, q_hat: f64, audit_n: u32 },   // calibrated on the audit lane only
}

pub struct AllocationDecision {
    campaign: CampaignId, stratum: StratumId, from: Rung, to: Rung,
    rule: AllocationRule, mode: LadderMode,
    advanced: Vec<DesignId>, discarded: Vec<DesignId>,
    audit_lane: Vec<DesignId>,         // drawn by a keyed stream before any score exists; never cancelled
    rank_record: Option<RankAgreementId>,   // a rung without a record may not discard
    policy: DecisionPolicyId,          // the versioned decision rule, e.g. ("atelier.dc01.promote", 3)
    spend: Budget,
}

I.14 A family policy and an inheritance map

/// The manifest and mapping table every checkpoint carries (schema frob.policy/1, in safetensors metadata).
pub struct PolicyManifest {
    network: NetworkSpec,              // kind, widths, recurrent
    action_law: ActionLaw,             // e.g. latent-then-limit
    discount: PhysicalDiscount,        // per second, not per step
    channels: Vec<ChannelMap>,         // matched by role, never by position or name order (INV-CORTEX-04)
    observation_schema: ObsSchema,     // actor, critic-only and normalizer digests
    trained_on: TrainedOn,             // task, scenes, randomization, tier, determinism, reset mode, donor
    group: GroupTying,                 // Γ_mech, Γ_obs and how the tying was imposed
}
pub struct ChannelMap { id: Ident, role: Role, unit: Unit, sign: i8, bounds: (Qty, Qty), rate: Ratio }

/// A family policy: one policy for a generator of designs, with one token per link.
pub struct FamilyPolicy {
    manifest: PolicyManifest, generator: GeneratorId, split: DesignSplit,
    envelope: SupportEnvelope,         // `policy.apply` refuses a design outside it
    rank_record: Option<RankAgreementId>,   // without one it is not a rung (FROB-REF-537)
}

/// How a child design's policy starts from its parent's, through the typed edit that joins them (§23.12).
/// A mapping that cannot be built is a refusal, not a guess (FROB-REF-531).
pub struct InheritanceMap {
    donor: PolicyId, child: DesignId, edit_path: Vec<EditId>,
    correspondences: Vec<Correspondence>,   // frames, actuator roles, sensors, contact roles, phase clocks
    unmatched: Vec<Role>,              // new channels start at zero; unmatched recurrent state is reset
    depth: u8,                         // a lineage resets on a schedule (default k = 5)
}
pub enum Transport { Adjoint, AdjointDual, GroupElement(GroupElem), Zero, Reset }
pub struct Correspondence { from: Role, to: Role, transport: Transport }

I.15 An energy budget and a shield

/// A `.fenergy` document (schema frob.energy/1). Quantities are decimal strings so that no binary rounding
/// enters the predicate, which is evaluated in the exact-integer kernel class with declared unit scales.
pub struct EnergyBudget {
    boundary: BoundaryId,
    load_path: Vec<ComponentId>,       // every port that can inject power is listed or cut (FROB-REF-451)
    unit_scale: UnitScale,             // e.g. 1e-6 J and 1e-6 s
    terms: Terms,                      // kinetic_ub, drive, external[], stored[], reserve
    absorber: Absorber,                // card, w_abs, provenance
    premises: Premises,                // sources_complete, absorber_on_path
    claim: ClaimProduct,
}
impl EnergyBudget {
    /// Admit iff T_ub + E_drive + E_ext + E_stored + E_reserve ≤ W_abs, as integers at the declared scale.
    pub fn admits(&self, speed_reading: Qty) -> bool;
    /// (W_abs − T_ub − E_ext − E_stored − E_reserve) / P_max.
    pub fn longest_cutoff_delay(&self, speed_reading: Qty) -> Qty;
}

/// A runtime shield: a stage of the environment after the policy and before the actuators (§22.12).
pub struct Shield {
    rows: Vec<BarrierRow>,             // written on a template of 2 to 12 states
    margin: MeasuredMargin,            // ε̂, keyed by design class, policy identity, task family and tier
    backup: BackupController,          // damping injection, posture hold, or widen-lower-freeze
    monitors: Vec<AssumptionMonitor>,  // an alarm also triggers the backup
    budget: Option<EnergyBudget>,
}
pub enum ShieldEvent { Projected { rows: u8 }, Alarm(MonitorId), Backup(BackupKind), Uncovered, MarginRefused }

I.16 A calibration record

/// What `ground.identify` writes (§30.9). A fit whose electrical-to-mechanical energy residual exceeds
/// the instrument bound is marked wrong-reason and cannot be admitted.
pub struct CalibrationRecord {
    dataset: DatasetId,                // a `.frun` bundle of origin real, with licence, rights and splits
    cell: CellKey,                     // unit, surface, envelope: one robot calibrates one robot
    prior: CardVersion,
    windows: WindowDef,                // traces enter as windows of summary features
    passes: Vec<Pass>,                 // A linear; B output error; C nonsmooth parameters, delay profiled
    posterior: Posterior,              // mean, joint covariance, delay profile with its 95% set
    misfit: (f64, f64),                // before and after
    residual_autocorrelation: Vec<f64>,     // at control-rate lags
    energy_check: EnergyCheck,         // the energy ledger evaluated on the real log
    discrepancy_floor: Variance,       // never reported below the model-form variance
    status: CardStatus,                // Candidate until a frozen prediction covers on sealed data
    labels: Vec<GroundLabel>,          // e.g. WrongReason, RankingFalsified
}
pub enum CardStatus { Candidate, Admitted, Rejected }

I.17 A build packet

/// The manifest of a `.fbuild` directory, written atomically and addressed by the manifest hash (§31.12).
pub struct BuildPacket {
    schema: SchemaId, design: DesignId, model: ModelId,
    qualification: Option<VerdictId>,
    authorization: PacketAuthorization,     // four flags, all false, no setter
    reality: RealityStatus,            // NoClaim until Ground supplies data
    review: ReviewStatus,              // NoClaim until a review, a quotation or an inspection is imported
    units: UnitSystem, exploratory: bool,
    files: Vec<(Path, Blake3)>,        // parts, geometry, tolerances, mass, harness, schedule, structure, fab, certs
}

Note. §31.12 names the schema frob.fbuild/1 and the format registry of §34.9 names it frob.build/1; likewise frob.fscene/1 and frob.fclear/1 in §19 against frob.scene/1 and frob.clearance/1 in §34.9. The registry of §34.9 owns schema names.

I.18 Backends, the environment, the record

/// Where kernels run. `batch-cpu` implements it with Rust symbols.
pub trait KernelBackend {
    fn compile(&mut self, lib: &KernelLibrary) -> Result<CompiledLibrary, Refusal>;
    fn allocate(&mut self, layout: &BufferLayout) -> Result<BufferSet, Refusal>;
    fn plan(&mut self, stages: &[Stage], class: &ShapeClass) -> Result<StepPlan, Refusal>;
    fn launch(&mut self, plan: &StepPlan, bufs: &mut BufferSet, cx: &Cx<'_>) -> Result<Receipt, Refusal>;
}

/// The vectorized environment. Buffers stay on the device. Explicit reset is the default (§23.3).
pub trait VecEnv {
    fn spec(&self) -> &TaskProgram;
    fn reset(&mut self, mask: &WorldMask, seeds: &SeedPlan, cx: &Cx<'_>) -> Result<ResetView<'_>, Refusal>;
    fn step(&mut self, actions: ActionView<'_>, cx: &Cx<'_>) -> Result<StepView<'_>, Refusal>;
    fn snapshot(&self, worlds: &[WorldId]) -> Result<Snapshot, Refusal>;
    fn restore(&mut self, snapshot: &Snapshot) -> Result<(), Refusal>;
}

pub struct StepView<'a> {
    pub obs: TensorView<'a>,             // after the transition; for an ended world, its final observation
    pub reward: TensorView<'a>,          // integrated over the control interval
    pub dt_sim: TensorView<'a>,          // simulated duration of the interval, per world
    pub terminated: MaskView<'a>,        // success, failure, or an intrinsic mission deadline
    pub truncated: MaskView<'a>,         // an external collection limit on a continuing task
    pub invalid: MaskView<'a>,           // numerical failure: a study error, not a transition
    pub needs_reset: MaskView<'a>,       // terminated | truncated | invalid
    pub applied_action: TensorView<'a>,  // after the limiter and any shield
    pub final_obs: Option<TensorView<'a>>, // masked-autoreset mode only; `obs` then holds post-reset values
    pub info: InfoView<'a>,              // sample ages, validity masks, control layer, shield events
}

/// A world's record is published in fixed logical chunks. The key names no device, shard, slot or retry.
pub struct ChunkKey { run: RunId, world: u32, episode: u32, stream: StreamId, index: u32 }
pub struct ChunkRecord {
    key: ChunkKey,
    content: Blake3,        // hash of the column file bytes
    prev: Blake3,           // chain digest of chunk index − 1; zero for index 0
    chain: Blake3,          // H(prev ‖ content ‖ key)
    state_digest: u128,     // in-kernel digest of the world's state at the chunk's last tick
    lease_gen: u64,         // fencing token of the writer
    commit_seq: u64,        // assigned inside the publishing transaction; a string on the wire
    gaps: Vec<Gap>,         // dropped intervals, each with a reason
}

/// The artifact graph (§29.13). Trace identifiers and wall-clock times never enter a content hash.
pub struct ClaimId(Blake3);            // BLAKE3(claim type ‖ subject identities ‖ statement ‖ scope)
pub struct EvidenceId(Blake3);         // BLAKE3(kind ‖ payload hash)
pub struct DecisionPolicyId { name: DottedName, version: u32 }   // a decision rule, not a control policy
pub struct TraceId(u128);              // time-ordered identifier of the execution that produced an item