trials

Newest first. No session is public: a session is visible to its owner (the campaign's, else the device's) and the owner org's members; filters narrow within that.

C4. A session is a sequence of trials on one device, each a checkpoint run under its own M13 approval, in an order the hub writes down before anything runs: the control first, the candidates by ascending sim risk (fewer locked gates passed, then fewer seeds upright, runs later), the control again last — the founder's A/B/A bracket (700 → A800 → 700), whose rule is checked once both control runs have a log (TrialSession.bracket). Each trial gets a run sheet drafted from the review — the stages (hang → floor → teleop), gain profile, kd and power scale, the environment, the abort rules, the predictions copied from the round's locked gates with the sim conditions they were measured under, and the criteria the log will be judged against — editable until its approval is issued, and locked then (RunSheet.locked_at; the token carries its digest). With a device_id (or when exactly one of the owner's devices embodies the robot and accepts every trial's contract) the hub files one consent request per trial at once — never an approval (M13). decideRound {shortlist} calls this for the round it shortlists; AG1's agent shortlist files its requests through the same trials. key:write: a plan and requests a person must still approve, one by one.

For a session created without a device (none of the owner's devices accepted every contract, or several did): names the device and files one M13 consent request per trial that has none, each pinned to the checkpoint's ONNX and its digest and carrying the session's reason. A contract the device does not accept is 409 naming the trial, and nothing is filed. Idempotent: a trial that already has a request is left alone. Never approves anything (M13).

Newest first, under the session's visibility rule. status=needs_verdict is what the Inbox's "needs your verdict" card reads; approval_id is how a driver finds the trial an approval belongs to.

One real-robot trial as a record. criteria are judged on every read from the uploaded summary against what was written down before the run: the run sheet's criteria (locked with its approval) and the round's locked gates the log can measure, each with the sim measurement beside it; a comparison with the session's control trials is pending until one of them has a log. log.files[].url are presigned GETs (1 h). Invisible is 404.

Partial: a key that is absent is unchanged, and null clears an optional one. Stages, gain profile, kd and power scale, environment, abort rules and criteria may change until the trial's approval is issued; from then on the sheet is what a person approved and this is 409 — "no tuning on site". The approval token carries the locked sheet's digest (run_sheet_sha256), and the driver refuses a sheet that does not hash to it.

The driver's first step after a trial's run stops: one presigned PUT (1 h) per log file, under trials/{trial_id}/log/. Bytes never pass through the API. Allowed only while the trial's approval is running or stopped and no log has been recorded; the upload is not a record until uploadTrialLog names each file's sha256 under the device's signature.

Storage (L0). The declared sizes count toward the trial session owner's storage quota (STORAGE_QUOTA_BYTES, the same 50 GiB as repo files): over it is 413 and no URL is issued.

The driver's word on what the robot-side command wrote: state: uploaded with each file's sha256, bytes and rows and the summary it computed on the box (tilt mean and max over the log's steady second half, the worst left–right joint asymmetry, per-joint tracking error, the motor temperatures the command printed at stop, battery, falls, what stopped it, the stages it ran), or missing / malformed with the reason — a stated failure, never silence. Signed with the device's own Ed25519 key over the canonical payload (trial_log_payload: approval, device, trial, state, files, summary, stages, detail, ts) and verified against the key registered for the trial's device, exactly like postDeviceEvent. The hub then hashes every uploaded object and refuses (422) a file whose bytes do not match the signed digest, re-derives the log's own numbers (tilt, asymmetry, tracking) from the CSV and stores whether they agree (summary.hub_check). Once only (409 after), while the approval is running or stopped. Audited trial.log.

Read out of the uploaded log files (every stage, on the trial's own clock, with the stage boundaries) and decimated like getEpisodeSeries: min/max per bucket, so a one-frame tilt spike survives. channels picks what to return: tilt (degrees, from the logged gravity vector — the founder's acos(−g_z)), q:<joint>, tgt:<joint>, act:<joint>; default tilt. 409 while no log is recorded.

The phone form's autosave: a key that is absent is unchanged, null clears it, and the response carries filed_at (the time of this save) so the form can say "notes saved 14:33". Fields are taps — stability 1–5, drift, four toggles, which motors were hot — plus free text kept in the language it was written in (lang, detected when absent). A machine translation (translation), when the hub has one, is labelled as one and never replaces the text; this hub fills it from recorded fixtures only (no live model call). The first save is audited trial.notes; later saves update the same record. Notes may be filed from the moment the trial is approved, and until its verdict.

One multipart upload under trials/{trial_id}/videos/, straight from the phone to object storage (M3's presigned multipart, 8 MiB parts, 1 h URLs); completeTrialVideo takes the part list from storage and attaches the video to the notes. Up to 2 GiB and eight videos a trial.

Completes the multipart upload from the parts object storage holds (the phone need not keep ETags), checks the stored size against the declared one, and adds the video to TrialNotes.videos. Audited trial.video.

Session only — a person decides what a real robot showed; no API key of any scope, and so no agent, can (403). Three options, none the default, each with a reason: promote — this checkpoint becomes the campaign's policy on the robot (Campaign.policy_on_robot, and the baseline the next session's criteria are drafted from); iterate — back to simulation: the checkpoint stays a valid parent, and an agent session attached to the campaign is woken with the verdict, the notes and the summary to draft the next round from (a person still approves it); stop — this checkpoint's lineage ends the way a FAIL does: no round may resume from it (rule.fail_ends_lineage), and iterating from it is refused. Only a candidate trial takes a verdict (a control is measured, not judged), only once, and only after its run started. Audited trial.verdict, with a sentence in listActivity.

Either a campaign round (campaign + round), whose shortlist supplies the candidates and controls, or explicit candidates and controls (checkpoints the caller can read). One control is run first and again last; two controls are run first and last.

Signed like a device event: signature is the device key's Ed25519 signature (base64url) over the canonical JSON of {approval_id, device_id, trial_id, kind: "trial_log", state, files: [{name, stage, sha256, bytes, rows}], summary, detail, ts} — ts exactly as sent.

A partial save — absent keys are unchanged, null clears.

A checkpoint to trial — checkpoints/step_<step>/ of a run's output model repo.

The A/B/A bracket check, the founder's rule: run the control first and last, and when the two control runs differ by more than the tolerance the session was polluted (battery, floor, temperature) and its A/B decides nothing. holds is null until both control runs have a log, or when the session has no second control run.

The checkpoint's verdict in simulation, from its round's locked gates.

What will be done on the robot, written before anything runs: drafted from the review when the trial is planned, editable until its approval is issued, locked then (locked_at = the approval's issued_at; digest is what the token's run_sheet_sha256 binds). "No tuning on site" is the rule, not a field.

Computed on the robot box by the driver from the log the robot-side command wrote, with the founder's own formulas (tools/policy_io.summarize, docs/DECISIONS.md "C4"): tilt = acos(−g_z) over the judged stage's steady second half; a pair's asymmetry = |mean(l) + mean(r)| there (his mirror convention, l ≈ −r); tracking error = mean(target − measured) per joint; the motor temperatures his deploy script prints at stop; falls when its tilt protection fired. Numbers the log cannot give are null, never invented.

One stage of the run sheet, as a person reads it and as the driver maps it onto a command configured on the robot box (the hub sends values, never a command line). duration_s null runs until the operator stops it (teleop). status comes from the driver's signed log upload.

A machine translation of the notes' text, labelled as one and never replacing it. This hub fills it only from recorded fixtures (TRIAL_TRANSLATION=recorded); no live model call is made.

The real-robot numbers a <=control criterion compares against when the campaign has a promoted policy: that trial's own summary.

awaiting — the run has not ended or the driver has not reported; uploaded — files and a summary, signed; missing — the driver found no log where the box's config said the command would write one; malformed — it found one it could not read.

A left / right pair of one joint.

The hub re-derived the log's own numbers from the uploaded CSV.

What the log measures: tilt_mean_deg, tilt_max_deg (over the judged stage's steady second half), asym_max_deg (the worst left–right pair), falls, tracking_error_rad (|mean target − measured| of joint, both sides), loop_hz, temp_max_c.

<= < >= > == against threshold; <=control against the mean of the session's control trials (or the campaign's promoted baseline, baseline); as_in_sim — within tolerance of sim_value, reported as as_in_sim / differs_from_sim, never pass/fail.

PASS / FAIL against a threshold; as_in_sim / differs_from_sim for a comparison with simulation (never a pass); pending — the control it compares with has no log yet; unmeasured — the log does not carry the metric.