Zero-Trust Physics

Every domain and card, each with one sentence, and count, how many there are. against_measurement is how the model did against its own measurements, in one of four words, "met", "missed", "met in part" or "not held to a measurement": it is accuracy and not fit, and a model that missed is still the served model of its thing.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "description": "No arguments. Returns every domain/card pair."
}

Inputs, units, bounds, step limits, reject names and meanings, advisory flags, frame slots, and worked examples for one pair. With form "short" the answer is a page, enough to write a first request: what the model is of, how it did against measurement, each input with its unit and range, the names of its stops, and a worked request. Read the full form, the answer when form is left out, when a request is refused or before relying on a result: only it has each bound's reason, the validation record and each stop's meaning.

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "The domain of the pair, as list_cards names it."
    },
    "card": {
      "type": "string",
      "description": "The card of the pair, as list_cards names it."
    },
    "form": {
      "type": "string",
      "enum": [
        "short",
        "full"
      ],
      "description": "Leave this key out, or \"full\", for the whole description; \"short\" for a page that is enough to write a first request."
    }
  },
  "required": [
    "domain",
    "card"
  ],
  "additionalProperties": false,
  "description": "Full limits, fields, reject names and meanings, advisory flags, frame slots, and worked examples for one pair."
}

One anchored step. Same bytes as POST /verify_physics. On this open connection one address holds at most 1 physics permit at a time, and a solve, a dataset job and a run of more than 10000 steps are long work, of which 1 runs at a time: a call that finds no permit or no place is answered "Too many concurrent physics tasks." and is sent again; nothing waits. An answer is waited for 60 seconds.

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "The domain of the pair, as list_cards names it."
    },
    "card": {
      "type": "string",
      "description": "The card of the pair, as list_cards names it."
    },
    "parameters": {
      "type": "object",
      "description": "The step's inputs: the card's phase fields, its load fields and dt_s, each a number (a vector field is an array of three numbers), and no other key. describe_card gives the fields of the pair, with each unit and bound."
    },
    "from": {
      "type": "object",
      "description": "Optional: a sealed run to start from, as run_trajectory takes it.",
      "properties": {
        "request": {
          "type": "object"
        },
        "run_seal": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$"
        },
        "coupling": {
          "type": "string"
        }
      },
      "required": [
        "request",
        "run_seal"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "domain",
    "card",
    "parameters"
  ],
  "additionalProperties": false,
  "description": "One anchored step. The same request as POST /verify_physics. The shape of parameters depends on the pair: read describe_card for it."
}

One anchored run under a changing load. Same bytes as POST /run_trajectory. The size of the answer follows from the request: about 230 characters for each recorded state, plus the request as it was sent, plus up to 8000 characters for the final state and the seals. A state is recorded at each multiple of record_every and at the last landed step, so 10,000 steps with record_every 1 answer with about 2.3 million characters, and the same steps with record_every 10000 with one recorded state. What keeps it small: a larger record_every; the final state is returned in full whatever is recorded. To read quantities without the frames, add readout: {"quantities": [names the card publishes], "first_past": {"quantity": <one of them>, "above" or "below": <level>}}. The answer then holds each quantity in decimals at the recorded steps, its minimum and maximum over every landed step with the step, the time (the step times dt_s) and every other listed quantity at that step (at_minimum, at_maximum), and, when asked, the first landed step at which it is past the level, with every other listed quantity there (at_step); with record_every equal to the steps, one state is recorded and the readout gives the extremes of every step. The readout is not part of the sealed request: the run_seal is the seal of the same run without it, the receipt covers it, and at most 8 quantities are read. With from (see its schema) the run starts from a sealed run, and is refused by name when the upstream's seal or a carried value does not hold. A run can be refused in two ways, and they come back differently. A request the door turns away before computing is an error, not a result: its text is one sentence, nothing is sealed, and when the sentence gives the card's name for the refusal the name is in round brackets. A run that starts and is refused part way is a result: outcome is "refused", reject holds the name (null when the cause has none), reject_detail holds the sentence, which ends "The run is sealed to step N. The state at step N+1 was refused and is not sealed.", and the run is sealed up to that last landed step N: steps_landed is N, the count of steps that landed, so the step that was refused is steps_landed + 1. A run that reaches an end its card declares (the first maximum of power of a reactor burst, a capsule's flown parachute deployment, a mission's last day, the end of a record's clock or track) is not refused: outcome is "ended", reject holds the end's name, reject_detail a sentence beginning "Ended" that names the end, and the run is sealed up to its last landed step; describe_card lists a card's declared ends under declared_ends. A sentence that begins "Physical Failure" says the state asked for or reached is outside the card: past a published bound, a limit of the specimen, or the conservation ledger. A sentence that begins "Physical Violation" says the request, or a number in it or computed from it, is not one the engine takes: its shape, a missing or unknown key, the number rule, the step floor or ceiling, a load rule, a size limit, or a value that is not finite. On this open connection one address holds at most 1 physics permit at a time, and a solve, a dataset job and a run of more than 10000 steps are long work, of which 1 runs at a time: a call that finds no permit or no place is answered "Too many concurrent physics tasks." and is sent again; nothing waits. An answer is waited for 60 seconds.

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "The domain of the pair, as list_cards names it."
    },
    "card": {
      "type": "string",
      "description": "The card of the pair, as list_cards names it."
    },
    "initial": {
      "type": "object",
      "description": "The phase fields of the card at the start of the run, each a number (a vector field is an array of three numbers), and no other key. describe_card gives them, with each unit and bound."
    },
    "dt_s": {
      "type": "number",
      "description": "Step, in seconds. Held for the whole run."
    },
    "record_every": {
      "type": "integer",
      "minimum": 1
    },
    "segments": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "steps": {
            "type": "integer",
            "minimum": 1
          },
          "load": {
            "type": "object",
            "description": "The load fields of the card for this segment, and no other key. describe_card gives them, with each unit and bound."
          }
        },
        "required": [
          "steps",
          "load"
        ],
        "additionalProperties": false
      }
    },
    "readout": {
      "type": "object",
      "properties": {
        "quantities": {
          "type": "array",
          "minItems": 1,
          "maxItems": 8,
          "items": {
            "type": "string"
          },
          "description": "Names of numbers the card publishes in its state; one component of a 3-vector is written name[0], name[1] or name[2]."
        },
        "first_past": {
          "type": "object",
          "properties": {
            "quantity": {
              "type": "string"
            },
            "above": {
              "type": "number"
            },
            "below": {
              "type": "number"
            }
          },
          "additionalProperties": false,
          "description": "A quantity of the list and one of above or below: the first landed step at which it is strictly above (or below) that level, with its time, its value and every other listed quantity at that step (at_step); null when no landed step passes it."
        }
      },
      "required": [
        "quantities"
      ],
      "additionalProperties": false,
      "description": "Optional. The named quantities in decimals at the recorded steps, each one's minimum and maximum over every landed step with its step, its time and every other listed quantity at that step (at_minimum, at_maximum), and first_past when asked. Not part of the sealed request: the run_seal is that of the same run without it."
    },
    "from": {
      "type": "object",
      "description": "Optional: start from a sealed run. request: that run_trajectory request as sent (it may hold its own from); run_seal: its seal; coupling: absent to continue the same card (describe_card says how), or a coupling's name. The upstream is computed again; each carried value must equal its sealed value bit for bit. The run_seal is that of this request without from; chain.chain_seal commits it to the upstream.",
      "properties": {
        "request": {
          "type": "object"
        },
        "run_seal": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$"
        },
        "coupling": {
          "type": "string"
        }
      },
      "required": [
        "request",
        "run_seal"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "domain",
    "card",
    "initial",
    "dt_s",
    "segments",
    "record_every"
  ],
  "additionalProperties": false,
  "description": "One anchored run. Total steps must be <= 1000000. Recorded frames must be <= 10000. The shape of initial and of each segment's load depends on the pair: read describe_card for it."
}

Check a run's seal. Short form, which needs only what is short: request is the run_trajectory request as it was sent, with its readout and its from when it had them (the answer's inputs holds neither), and run_seal is the seal its answer gave. The run is computed again, under a physics permit and the limits and refusals of run_trajectory, and the answer is holds (the seal given is the seal the request runs to), cause ("run_seal" when it is not), recomputed_run_seal and recomputed_receipt_sha256 when it holds (when it does not, no seal is returned: run_trajectory gives the true one), a sentence of what was checked, and text_not_compared: the short form compares no answer text you hold, so a copy with a decimal changed still holds; verify_receipt checks a copy against the receipt that copy carries, and the check is complete only when that receipt equals recomputed_receipt_sha256 here. Nothing is stored, so the short form answers the same on every connection. Worked example: {"request":{"domain":"energy","card":"thermal","initial":{"temperature_k":293.15},"dt_s":1.0,"segments":[{"steps":60,"load":{"heat_power_w":5.0,"ambient_k":293.15}}],"record_every":60},"run_seal":"<the run_seal of its run_trajectory answer, 64 lowercase hex digits>"}. Long form: the whole run_trajectory answer sent back byte for byte, without request; it takes no physics permit, recomputes the chain, the state digest and the run seal, and checks the exact hex values and the seals, not the decimal copies of the values and not the receipt; verify_receipt checks a copy's bytes against the receipt it carries. A chain: its request with from, run_seal and chain_seal, computed again; or links, its answers in order, with no physics. Same bytes as POST /verify_tape. On this open connection one address holds at most 1 physics permit at a time, and a solve, a dataset job and a run of more than 10000 steps are long work, of which 1 runs at a time: a call that finds no permit or no place is answered "Too many concurrent physics tasks." and is sent again; nothing waits. An answer is waited for 60 seconds.

{
  "type": "object",
  "properties": {
    "request": {
      "type": "object",
      "description": "With run_seal alone: the run_trajectory request as it was sent, with its readout and its from when it had them (the answer's inputs holds neither). It is run again, under a physics permit and the limits of run_trajectory, and its seal is compared with run_seal. Its fields are run_trajectory's."
    },
    "inputs": {
      "type": "object",
      "description": "The inputs of the run_trajectory answer, sent back as returned: the request that was run. It is hashed, not run. A card's fields, units and bounds are in describe_card."
    },
    "frames": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "step": {
            "type": "integer",
            "minimum": 1
          },
          "frame_hex": {
            "type": "string"
          },
          "link": {
            "type": "string"
          }
        },
        "required": [
          "step",
          "frame_hex",
          "link"
        ],
        "additionalProperties": false
      }
    },
    "outcome": {
      "type": "string"
    },
    "steps_landed": {
      "type": "integer",
      "minimum": 0
    },
    "reject": {
      "type": [
        "string",
        "null"
      ]
    },
    "run_seal": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$",
      "description": "The run_seal of the run_trajectory answer: with request, or as part of the whole answer."
    },
    "final_state": {},
    "final_residual_conservation_error_hex": {
      "type": [
        "string",
        "null"
      ]
    },
    "max_residual_conservation_error_hex": {
      "type": [
        "string",
        "null"
      ]
    },
    "state_digest": {
      "type": [
        "string",
        "null"
      ]
    },
    "chain_seal": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$",
      "description": "With request and run_seal: a chained answer's chain_seal."
    },
    "links": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Alone: a chain's answers in order."
    }
  },
  "additionalProperties": true,
  "description": "Either request and run_seal alone, the short form: the run is computed again and its seal compared with run_seal. Or the whole run_trajectory answer sent back as it was returned, without request: inputs, frames, outcome, steps_landed, reject, run_seal, final_state, final_residual_conservation_error_hex, max_residual_conservation_error_hex and state_digest are then all required, and the trajectory chain, the state digest and the run seal are recomputed with no physics run."
}

Every field solver, each with one sentence, and count, how many there are. against_measurement is how the model did against its own measurements, in one of four words, "met", "missed", "met in part" or "not held to a measurement": it is accuracy and not fit, and a model that missed is still the served model of its thing.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "description": "No arguments. Returns every solver."
}

Inputs and bounds, outputs, invariants and tolerances, refusal names and meanings, the published reference, and a worked example for one solver. With form "short" the answer is a page, enough to write a first request: what the model is of, how it did against measurement, each input with its unit and range, the names of its stops, and a worked request. Read the full form, the answer when form is left out, when a request is refused or before relying on a result: only it has each bound's reason, the validation record and each stop's meaning.

{
  "type": "object",
  "properties": {
    "solver": {
      "type": "string",
      "description": "The solver, as list_solvers names it."
    },
    "part": {
      "type": "string",
      "description": "Leave this key out to get the solver's whole description. Some long descriptions name, under 'more', parts kept back for asking: set part to one of the names listed there for that part alone. Only a name listed under 'more' is a part."
    },
    "form": {
      "type": "string",
      "enum": [
        "short",
        "full"
      ],
      "description": "Leave this key out, or \"full\", for the whole description; \"short\" for a page that is enough to write a first request."
    }
  },
  "required": [
    "solver"
  ],
  "additionalProperties": false,
  "description": "Inputs and bounds, outputs, invariants and tolerances, refusals and meanings, the published reference, and a worked example for one solver."
}

One sealed solution. Same bytes as POST /solve. Send parameters, or example in their place: the name of a worked example describe_solver lists (example_solve, or a key beginning example_solve_), so a long worked input need not be typed again; the request is filled with that example's parameters, and the filled request is the one solved, sealed and returned as inputs. The receipt covers the request as it was written, number spellings included, while a seal covers its values: a request sent with 310 and the same request sent with 310.0 give different receipts and the same seal, so a receipt that differs between two such answers is not a sign of tampering. To check a solution later, send this request, or its inputs, and its solution_seal to verify_solution. On this open connection one address holds at most 1 physics permit at a time, and a solve, a dataset job and a run of more than 10000 steps are long work, of which 1 runs at a time: a call that finds no permit or no place is answered "Too many concurrent physics tasks." and is sent again; nothing waits. An answer is waited for 60 seconds.

{
  "type": "object",
  "properties": {
    "solver": {
      "type": "string",
      "description": "The solver, as list_solvers names it."
    },
    "parameters": {
      "type": "object",
      "description": "The inputs of the solver named in 'solver', each a number, a whole number, a word, a flag or an array as describe_solver gives it, and no other key. Every number of a solve request must be a finite, normal 64-bit number or zero, and a number written as non-zero must not read as zero. This rule is the one every card's request follows, and it stands beside each input's range and refuses some values inside it: a subnormal such as 5e-324 is refused wherever zero and larger numbers are accepted. A solution has no frame, so the card's rule that a number fit a 32-bit frame slot does not apply."
    },
    "example": {
      "type": "string",
      "description": "In place of parameters: the name of one of the solver's worked examples as describe_solver keys it (example_solve, or a key that begins example_solve_). The request is filled with that example's parameters, and the filled request is the one solved, sealed and returned as inputs."
    }
  },
  "required": [
    "solver"
  ],
  "additionalProperties": false,
  "description": "One sealed solution. The same request as POST /solve."
}

Check a solution's seal. Short form, which needs only what is short: request is the solve request as it was sent (the answer's inputs), and solution_seal is the seal its answer gave. The request is solved again, under a physics permit and the limits and refusals of solve, and the answer is holds, cause ("solution_seal" when the seal given is not the seal the request solves to), recomputed_solution_seal and recomputed_receipt_sha256 when it holds (when it does not, no seal is returned: solve gives the true one), a sentence of what was checked, and text_not_compared: the short form compares no answer text you hold, so a copy with a decimal changed still holds; verify_receipt checks a copy against the receipt that copy carries, and the check is complete only when that receipt equals recomputed_receipt_sha256 here. Nothing is stored, so the short form answers the same on every connection. Worked example: {"request":{"solver":"atom_dft","parameters":{"atomic_number":10}},"solution_seal":"<the solution_seal of its solve answer, 64 lowercase hex digits>"}. Long form: the whole solve answer sent back, without request; it takes no physics permit, recomputes the solution seal and names the part that fails, and checks only the exact hex values and the seals, not the decimal copies of the values and not the receipt, as its answer says; verify_receipt checks a copy's bytes against the receipt it carries. Same bytes as POST /verify_solution. On this open connection one address holds at most 1 physics permit at a time, and a solve, a dataset job and a run of more than 10000 steps are long work, of which 1 runs at a time: a call that finds no permit or no place is answered "Too many concurrent physics tasks." and is sent again; nothing waits. An answer is waited for 60 seconds.

{
  "type": "object",
  "properties": {
    "request": {
      "type": "object",
      "description": "With solution_seal alone: the solve request as it was sent (the answer's inputs). It is solved again, under a physics permit and the limits of solve, and its seal is compared with solution_seal. Its fields are solve's."
    },
    "inputs": {
      "type": "object",
      "description": "The inputs of the solve answer, sent back as returned: the request that was solved. It is hashed, not solved."
    },
    "engine_version": {
      "type": "string"
    },
    "outcome": {
      "type": "string"
    },
    "iterations": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "reject": {
      "type": [
        "string",
        "null"
      ]
    },
    "result": {
      "type": [
        "object",
        "null"
      ]
    },
    "invariants": {
      "type": [
        "object",
        "null"
      ]
    },
    "field_sha256": {
      "type": [
        "string",
        "null"
      ]
    },
    "seal_parts": {
      "type": "object",
      "properties": {
        "inputs": {
          "type": "string"
        },
        "engine_version": {
          "type": "string"
        },
        "result": {
          "type": "string"
        },
        "invariants": {
          "type": "string"
        },
        "field_sha256": {
          "type": "string"
        },
        "outcome": {
          "type": "string"
        }
      },
      "required": [
        "inputs",
        "engine_version",
        "result",
        "invariants",
        "field_sha256",
        "outcome"
      ],
      "additionalProperties": true
    },
    "solution_seal": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$",
      "description": "The solution_seal of the solve answer: with request, or as part of the whole answer."
    }
  },
  "additionalProperties": true,
  "description": "Either request and solution_seal alone, the short form: the request is solved again and its seal compared with solution_seal. Or the whole solve answer sent back, without request: inputs, engine_version, outcome, iterations, reject, result, invariants, field_sha256, seal_parts and solution_seal are then all required, the solution seal is recomputed and the part that fails is named, with no physics run."
}

Run a declared plan of runs on one card, or of solves of one solver, and seal the rows under one root. Same bytes as POST /run_dataset. The seal shows the dataset was not altered after it was sealed. It does not show the engine made it: send a row's request to run_trajectory and compare run seals. A plan is a list of runs, a grid over a base run, or a seeded sample over a base run; a run is a run_trajectory request without domain and card. A path names one number: initial.<field>, dt_s, or segments[0].load.<field>, with the segment's number in square brackets and [0], [1] or [2] after a 3-vector field for one of its components. steps and record_every are not paths and cannot vary: every row of a grid or a sample takes them from the base run. A value an axis or a draw sets replaces the base's value of that field, and the answer's base_replaced names each field replaced; a 3-vector the base sets whole is replaced only when the paths set all three of its components. Two paths may not set one number. One worked plan of each kind, each a whole request: list: {"domain":"energy","card":"thermal","plan":{"kind":"list","runs":[{"initial":{"temperature_k":293.15},"dt_s":1.0,"segments":[{"steps":60,"load":{"heat_power_w":5.0,"ambient_k":293.15}}],"record_every":60}]},"store":"none","return":"inline"} grid: {"domain":"energy","card":"thermal","plan":{"kind":"grid","base":{"initial":{},"dt_s":1.0,"segments":[{"steps":60,"load":{"ambient_k":293.15}}],"record_every":60},"axes":[{"path":"initial.temperature_k","values":[283.15,293.15]},{"path":"segments[0].load.heat_power_w","values":[0.0,5.0,10.0]}]},"store":"none","return":"inline"} sample: {"domain":"energy","card":"thermal","plan":{"kind":"sample","base":{"initial":{},"dt_s":1.0,"segments":[{"steps":60,"load":{"ambient_k":293.15}}],"record_every":60},"rows":4,"generator":"splitmix64_counter_v1","seed_hex":"0000000000000001","draws":[{"path":"initial.temperature_k","choice":[283.15,293.15]},{"path":"segments[0].load.heat_power_w","uniform":{"low":0.0,"high":10.0}}]},"store":"none","return":"inline"}. The answer is small by default: the head, which holds the request, the counts and the dataset_seal, and one summary row per run with row, set (the values a grid's or a sample's row sets), outcome, steps_landed, reject and run_seal. With "answer": "states" each summary row also holds final_state in decimals; with "answer": "full" the answer is the head, every row whole and frames_hex. The head and the dataset_seal are the same in all three forms, and answer is not part of the sealed request. To read quantities of one row, send its request to run_trajectory with a readout. An inline answer is counted from the plan before anything runs, and one above 40000 characters is refused with what to change: a summary row counts 220 characters and the values it sets; with states, each number of the final state adds its name and 28 characters (84 for a 3-vector, 9 for a flag); a whole row counts its own request and 1900 characters, and for each number twice its name and 60 characters (150 for a 3-vector, 9 for a flag); store "frames" adds 128 characters for each recorded state to a full answer; the head repeats the request. return "file" stores the rows and answers with the head and the names of the files, whatever the plan's size and whatever answer says; verify_dataset checks it by its dataset_seal. A row is completed, ended, refused or unadmitted. An ended row is a run that stopped at an end its card declares: it has a run seal, the end's reject name in reject and the sentence naming the end in reject_detail. A refused row is a run the card refused part way: it has a run seal, the refusal's name in reject and its sentence in reject_detail. An unadmitted row is a request the door turned away before computing: it has no run seal, and its sentence, with the refusal's name in round brackets when the sentence gives one, is its reject_detail; its summary row gives that name in reject. Each row of a grid is held to the card's bounds alone, as each run of a list is: a value outside a bound makes that row unadmitted and the other rows run. A sample's interval or choice outside a bound refuses the plan. What a sentence that begins "Physical Failure" or "Physical Violation" means is in the description of run_trajectory. A plan of solves names solver in place of domain and card, takes no store and no return, and is answered inline: a list, {"kind":"list","solves":[{"parameters":{...}}]}, or a grid, {"kind":"grid","base":{"parameters":{...}},"axes":[{"path":"parameters.<input>","values":[...]}]}, of at most 64 solves. Each row is a solve request, solved as solve solves it and carrying the solution_seal solve gives it; a request the door or the solver turns away without a seal is an unadmitted row. The rows are sealed under one dataset_seal by the rules of a plan of runs, with solution_seal in the leaf in the place of run_seal, and completed in the counts counts the solves that converged. A summary row has row, set, outcome, reject, solution_seal and every single number of the result in decimals; answer "full" gives every solution whole, and is refused when it comes to more than 40000 characters. verify_dataset checks a plan of solves by its request and dataset_seal, and validate_series compares one number of its results with measurements. Worked plan of solves: {"solver":"atom_dft","plan":{"kind":"list","solves":[{"parameters":{"atomic_number":10}}]}}. On this open connection a dataset is smaller than the engine's own limits allow: runs <= 300 (OPEN_MAX_DATASET_ROWS), steps in total <= 1000000 (OPEN_MAX_DATASET_STEPS), recorded states <= 10000, an answer counted from the plan at no more than 4194304 bytes (OPEN_MAX_DATASET_ANSWER_BYTES), and return "inline" only: no dataset is stored here, so return "file" is refused, and verify_dataset takes the request with its dataset_seal, or head, rows and frames_hex, not dataset_seal alone. On this open connection one address holds at most 1 physics permit at a time, and a solve, a dataset job and a run of more than 10000 steps are long work, of which 1 runs at a time: a call that finds no permit or no place is answered "Too many concurrent physics tasks." and is sent again; nothing waits. An answer is waited for 60 seconds.

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string"
    },
    "card": {
      "type": "string"
    },
    "plan": {
      "oneOf": [
        {
          "type": "object",
          "description": "A list of runs. Each is a run_trajectory request without domain and card.",
          "properties": {
            "kind": {
              "const": "list"
            },
            "runs": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "object"
              }
            }
          },
          "required": [
            "kind",
            "runs"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "description": "With solver: a list of solves. Each is a solve request without solver.",
          "properties": {
            "kind": {
              "const": "list"
            },
            "solves": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "object"
              }
            }
          },
          "required": [
            "kind",
            "solves"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "description": "A base run (with solver: a base solve request without solver) and axes of explicit values. The rows are the product of the axes, the last axis varying fastest.",
          "properties": {
            "kind": {
              "const": "grid"
            },
            "base": {
              "type": "object"
            },
            "axes": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "object",
                "properties": {
                  "path": {
                    "type": "string"
                  },
                  "values": {
                    "type": "array",
                    "minItems": 1
                  }
                },
                "required": [
                  "path",
                  "values"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "kind",
            "base",
            "axes"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "description": "A base run and draws from the counter sampler. Row n is worked out without the rows before it.",
          "properties": {
            "kind": {
              "const": "sample"
            },
            "base": {
              "type": "object"
            },
            "rows": {
              "type": "integer",
              "minimum": 1
            },
            "generator": {
              "const": "splitmix64_counter_v1"
            },
            "seed_hex": {
              "type": "string",
              "pattern": "^[0-9a-f]{16}$"
            },
            "draws": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "object",
                "properties": {
                  "path": {
                    "type": "string"
                  },
                  "uniform": {
                    "type": "object",
                    "properties": {
                      "low": {
                        "type": "number"
                      },
                      "high": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "low",
                      "high"
                    ],
                    "additionalProperties": false
                  },
                  "choice": {
                    "type": "array",
                    "minItems": 1
                  }
                },
                "required": [
                  "path"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "kind",
            "base",
            "rows",
            "generator",
            "seed_hex",
            "draws"
          ],
          "additionalProperties": false
        }
      ]
    },
    "store": {
      "type": "string",
      "enum": [
        "frames",
        "none"
      ]
    },
    "return": {
      "type": "string",
      "enum": [
        "inline",
        "file"
      ]
    },
    "solver": {
      "type": "string",
      "description": "A plan of solves: the solver, in place of domain and card. It takes no store and no return."
    },
    "answer": {
      "type": "string",
      "enum": [
        "summary",
        "states",
        "full"
      ],
      "description": "Leave out, or \"summary\", for the head and one short summary row per row: the values it sets, outcome, steps landed, refusal name and seal; \"states\" adds each run's final state in decimals; \"full\" gives every row whole. With return \"file\" the answer is the head and the names of the files whatever this says. Not part of the sealed request."
    }
  },
  "required": [
    "plan"
  ],
  "additionalProperties": false,
  "description": "A plan of runs on one card (domain, card, plan, store and return, all required) or of solves of one solver (solver and plan). Rows <= 100000, steps in total <= 100000000, stored frames <= 16777216; inline: rows <= 1000, frames <= 10000, an answer counted from the plan <= 40000 characters; solves <= 64. With return \"file\" the answer is the head and the names of the files the gateway stored, and the gateway must have been started with a directory for them."
}

Check a dataset's seal. Short form, which needs only what is short: request is the run_dataset request as it was sent (the head's request), and dataset_seal is the seal its answer gave. The plan is run again, under the permits and the limits of run_dataset, whatever its return mode and its answer form, and the answer is holds, cause ("dataset_seal" when the seal given is not the seal the plan runs to), recomputed_dataset_seal when it holds (when it does not, no seal is returned: run_dataset gives the true one), a sentence of what was checked, and text_not_compared: the short form compares no rows you hold. Nothing is stored or read from storage, so the short form answers the same on every connection. Worked example: {"request":{"domain":"energy","card":"thermal","plan":{"kind":"list","runs":[{"initial":{"temperature_k":293.15},"dt_s":1.0,"segments":[{"steps":60,"load":{"heat_power_w":5.0,"ambient_k":293.15}}],"record_every":60}]},"store":"none","return":"inline"},"dataset_seal":"<the dataset_seal of its run_dataset answer, 64 lowercase hex digits>"}. A plan of solves is checked by this short form only. Two long forms take no physics permit. The three parts a full inline answer carries (answer "full": head, rows and frames_hex, all three together): the rows, the root and the seal are recomputed and the first break is named; a dataset made without the engine can pass, and replaying a row through run_trajectory shows the engine made it; the exact hex values and the seals are checked, not the decimal copies of the values in the rows, and holds does not cover the receipt, which the report states apart. Or dataset_seal alone, for a dataset the gateway stored (return "file"). Same bytes as POST /verify_dataset. On this open connection a dataset is smaller than the engine's own limits allow: runs <= 300 (OPEN_MAX_DATASET_ROWS), steps in total <= 1000000 (OPEN_MAX_DATASET_STEPS), recorded states <= 10000, an answer counted from the plan at no more than 4194304 bytes (OPEN_MAX_DATASET_ANSWER_BYTES), and return "inline" only: no dataset is stored here, so return "file" is refused, and verify_dataset takes the request with its dataset_seal, or head, rows and frames_hex, not dataset_seal alone. On this open connection one address holds at most 1 physics permit at a time, and a solve, a dataset job and a run of more than 10000 steps are long work, of which 1 runs at a time: a call that finds no permit or no place is answered "Too many concurrent physics tasks." and is sent again; nothing waits. An answer is waited for 60 seconds.

{
  "type": "object",
  "properties": {
    "request": {
      "type": "object",
      "description": "With dataset_seal alone: the run_dataset request as it was sent (the head's request). The plan is run again, under the permits and the limits of run_dataset, and its seal is compared with dataset_seal. Nothing is stored or read from storage, so it works whatever the return mode and on every connection. Its fields are run_dataset's."
    },
    "head": {
      "type": "object",
      "description": "With rows and frames_hex: the head a run_dataset answer carries."
    },
    "rows": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "With head and frames_hex: the rows a full run_dataset answer (answer \"full\") carries."
    },
    "frames_hex": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^([0-9a-f]{2})*$",
      "description": "With head and rows: the frames a run_dataset answer carries, or null."
    },
    "dataset_seal": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$",
      "description": "With request: the dataset_seal of the run_dataset answer, compared with the seal the plan runs to. Alone: the seal of a dataset the gateway stored in files (return \"file\"); the gateway reads its own folder of that name. A dataset returned in the answer is not stored: send it with its request, or send its head, rows and frames_hex."
    }
  },
  "additionalProperties": false,
  "description": "Send one of three forms. request and dataset_seal, the short form: the plan is run again and its seal compared. The three parts a run_dataset answer carries (head, rows and frames_hex, all three required together): the rows, the root and the seal are recomputed with no physics run. dataset_seal alone: the stored dataset of that seal is checked with no physics run."
}

Check the receipt at the end of one response. Same bytes as POST /verify_receipt. Takes no physics permit. The receipt covers every byte of the response before it, the decimal values included, and shows who produced the response or when in no way: it has no key. The receipt covers the request as it was written, number spellings included, while a seal covers its values: a request sent with 310 and the same request sent with 310.0 give different receipts and the same seal, so a receipt that differs between two such answers is not a sign of tampering. Replaying the request through run_trajectory, solve or verify_step shows the engine produced it; verify_tape, verify_solution and verify_dataset with the request and its seal do that replay and compare the seals.

{
  "type": "object",
  "properties": {
    "response_text": {
      "type": "string",
      "description": "The exact text of a response as it was received, ending with the receipt."
    }
  },
  "required": [
    "response_text"
  ],
  "additionalProperties": false,
  "description": "The text of one response from verify_step, run_trajectory or solve, or the head of a dataset written as its JSON text."
}

Run a run_trajectory request (without a readout) and compare one published quantity with the caller's measurements, each at a landed step. The answer is the error in numbers (rms, mean signed, greatest absolute, model minus measurement, each with its exact hex), the model value at every compared step in decimals (model_values) and exact (model_values_hex), and a hash of the measurements, under one seal. Same bytes as POST /validate_series. There is no pass or fail and no threshold: the numbers are not a verdict. The seal has no key, so it does not show who measured or who computed. genesis_seal verify-validation rebuilds the seal and the statistics from the answer alone, of a run or of a plan of solves. In place of run, solves takes a plan of solves as run_dataset takes it (solver and plan, at most 64 solves): quantity is one number the solver publishes in its result, and each measurement is {"row": <the plan's row, from 0>, "value": <number>}. The solves are sealed under one dataset_seal as run_dataset seals them, and the comparison is sealed by the same statistics, measurement hash and validation seal as a run's, with the dataset_seal in the place of the run seal and the row in the place of the step; a measured row whose solve did not converge is counted in not_reached. The same request sent again gives the same seal. On this open connection one address holds at most 1 physics permit at a time, and a solve, a dataset job and a run of more than 10000 steps are long work, of which 1 runs at a time: a call that finds no permit or no place is answered "Too many concurrent physics tasks." and is sent again; nothing waits. An answer is waited for 60 seconds.

{
  "type": "object",
  "properties": {
    "run": {
      "type": "object",
      "properties": {
        "domain": {
          "type": "string",
          "description": "The domain of the pair, as list_cards names it."
        },
        "card": {
          "type": "string",
          "description": "The card of the pair, as list_cards names it."
        },
        "initial": {
          "type": "object",
          "description": "The phase fields of the card at the start of the run, each a number (a vector field is an array of three numbers), and no other key. describe_card gives them, with each unit and bound."
        },
        "dt_s": {
          "type": "number",
          "description": "Step, in seconds. Held for the whole run."
        },
        "record_every": {
          "type": "integer",
          "minimum": 1
        },
        "segments": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "properties": {
              "steps": {
                "type": "integer",
                "minimum": 1
              },
              "load": {
                "type": "object",
                "description": "The load fields of the card for this segment, and no other key. describe_card gives them, with each unit and bound."
              }
            },
            "required": [
              "steps",
              "load"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "domain",
        "card",
        "initial",
        "dt_s",
        "segments",
        "record_every"
      ],
      "additionalProperties": false,
      "description": "One anchored run. Total steps must be <= 1000000. Recorded frames must be <= 10000. The shape of initial and of each segment's load depends on the pair: read describe_card for it."
    },
    "solves": {
      "type": "object",
      "description": "In place of run: a plan of solves as run_dataset takes it (solver and plan, a list or a grid, at most 64 solves). quantity is then one number the solver publishes in its result, and each measurement names a row of the plan, numbered from 0, in place of a step."
    },
    "quantity": {
      "type": "string",
      "description": "The name of one number the card publishes in its state, a plain name that has a '_hex' sibling in the state. A flag is refused."
    },
    "component": {
      "type": "integer",
      "minimum": 0,
      "maximum": 2,
      "description": "0, 1 or 2: which of the three components of a 3-vector quantity is compared. Required when the quantity is a 3-vector, and refused when it is not. Any other value is refused."
    },
    "measurements": {
      "type": "array",
      "minItems": 1,
      "maxItems": 10000,
      "items": {
        "type": "object",
        "properties": {
          "step": {
            "type": "integer",
            "minimum": 1,
            "description": "With run: the landed step the value is compared with. The steps rise strictly and none is past the run's total."
          },
          "row": {
            "type": "integer",
            "minimum": 0,
            "description": "With solves, in place of step: the row of the plan whose solve the value is compared with, numbered from 0. The rows rise strictly."
          },
          "value": {
            "type": "number",
            "description": "The measurement, in the unit of the quantity."
          }
        },
        "required": [
          "value"
        ],
        "additionalProperties": false
      },
      "description": "At most 10000. A measurement is compared with the state after landed step k. There is no interpolation and no time matching: map your sample times to steps."
    }
  },
  "required": [
    "quantity",
    "measurements"
  ],
  "additionalProperties": false,
  "description": "One run, or one plan of solves, and measurements of one quantity. The answer is the error in numbers, sealed with a hash of the measurements. It holds no verdict. Send run, or solves, not both."
}

How to cite a card or a solver: the service itself first (Zero-Trust Physics, its maker and its address) and the paper (https://doi.org/10.5281/zenodo.23305697), then the people whose measurements the model stands on (authors, title, year, address, and what each asks of those who use its data), each as text and BibTeX. Send domain and card, or solver; with neither, the answer is how to cite the service itself: its name, who made it, its address and the paper. Same bytes as POST /cite.

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "With card: a card, by the name find_model or list_cards gives. When find_model has given it, no list need be read."
    },
    "card": {
      "type": "string"
    },
    "solver": {
      "type": "string",
      "description": "In place of domain and card: a solver, by the name find_model or list_solvers gives."
    }
  },
  "additionalProperties": false
}

Find the served model for a real thing described in plain words, such as "a lithium cell discharging in the cold". Returns the best few cards and solvers, each with fit first (the words that matched, and model_of, the one real thing it is a model of) and then accuracy (compared_with, the data it was fitted to and the data held back and compared, and accuracy_against_measurement: whether it passed the pass marks fixed before it was compared); a model's range and stops are in describe_card or describe_solver. against_measurement gives that verdict in one of four words, "met", "missed", "met in part" or "not held to a measurement", the word list_cards and list_solvers give on every row: it is accuracy and not fit. The two are separate: a model that failed its pass marks is still the served model of its thing. The names it gives (domain and card, or solver) are the names describe_card, describe_solver, cite and every other tool take, so no list need be read after it. When nothing served fits it says so, having compared every card and solver, names the nearest by words and why they are not it, or says that there is no near one, and says who to write to for a model. Matched against a fixed list of terms with no model call: the same words give the same answer. Same bytes as POST /find_model.

{
  "type": "object",
  "properties": {
    "description": {
      "type": "string",
      "description": "The real thing, in plain words."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5,
      "description": "How many models to return; 3 when left out."
    }
  },
  "required": [
    "description"
  ],
  "additionalProperties": false
}

Find where an outcome changes. Send request (a run_trajectory or solve request written out, its domain and card or its solver by the name find_model or the lists give; no from, readout or example), vary (the place of the one number to change: "segments[0].load.current_a", "segments[*].load.current_a" for every segment, "initial.soc", "dt_s", "segments[0].steps", "parameters.load_n"; a count is varied in whole numbers), and low and high, the two ends of the span, in either order: the smaller is taken as low. The span is halved to the place where the outcome or the stop name changes or, with level {"quantity": <a published quantity>, "value": <number>}, where that quantity of the final state (of a solve: of result) crosses the value, or, with level {"quantity": <a flag>}, where a true-or-false value of it turns. When both ends give the same, 7 values between them (3 for solves) are run to find a band, and the answer says so. The answer gives the run on each side as a request ready to send again, with its outcome, its stop name and sentence and the run_seal or solution_seal that request has when sent alone, the two values in decimals and exact hex, and the width between them. The same request gives the same pair. Bounded, and named when one stops the search: 64 runs (FLIP_MAX_RUNS), 1000000 steps in all (FLIP_MAX_STEPS), or 64 solves (FLIP_MAX_SOLVES), the ends included, and no new run after 20 seconds of computing (FLIP_MAX_SECONDS); send the pair back as the span to narrow it. A side that stops before computing has no proof. Same bytes as POST /find_flip. On this open connection a search is long work whenever it varies a solve or its runs may take more than OPEN_LIGHT_RUN_STEPS steps together.

{
  "type": "object",
  "properties": {
    "request": {
      "type": "object",
      "description": "A run_trajectory or solve request as that tool takes it."
    },
    "vary": {
      "type": "string",
      "description": "The place of the one number to vary."
    },
    "low": {
      "type": "number",
      "description": "One end of the span. low and high may come in either order; the smaller is taken as low."
    },
    "high": {
      "type": "number",
      "description": "The other end."
    },
    "level": {
      "type": "object",
      "properties": {
        "quantity": {
          "type": "string"
        },
        "value": {
          "type": [
            "number",
            "boolean"
          ]
        }
      },
      "required": [
        "quantity"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request",
    "vary",
    "low",
    "high"
  ],
  "additionalProperties": false
}