Type sketches
5,440 words18 subsections1 table18 listingsPlan version 1.1
On this page18
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