PUT/physical/sites/:idadmin

Enrol a site, or replace its key: the key the site signs its batches and its command receipts with. Needs the project in LW_PHYSICAL_COMMAND_TENANTS.

Body

site_keythe site's key as ed25519:<64 lowercase hex> or p256:<66 lowercase hex, compressed>, from the site's operator tooling
GET/physical/sitesmember

The project's enrolled sites: id, key, the last command sequence number issued and the last batch sequence number accepted.

POST/physical/commandsadmin

Issue one command to a site, only for a twin inside its solved band: the twin must be calibrated, every value inside the band, and the twin's forecasts proven (at least 20 scored, 80% inside their 90% interval). The command is a setpoint or a trajectory chunk (an action chunk of a learned policy), signed by the core's command signer with the twin's certificate; the site decides on its own policy and answers with a signed receipt. The mode is shadow by default. Mode actuate is signed only when the project is in LW_PHYSICAL_COMMAND_TENANTS and a stored approval, signed by an enrolled approver key, covers the site, the system class, the actuator and the kind through the command's expiry and has not been revoked; otherwise 403 actuation_not_approved. The site decides again on its own stage and approvals. Needs a configured signer (503 otherwise).

Body

sitean enrolled site id
twina twin loop id
band_keythe band coefficient the setpoint, or the joint position of a trajectory (radian), is, mean.<name> or scale.<name>
effort_band_keytrajectory only: the band coefficient that bounds joint effort (newton metre); required when the steps carry tau
target{actuator_id, scope}
setpoint{quantity, unit, value}; exactly one of setpoint and trajectory
trajectory{chunk_index, dof, step_ms, steps: [{q, tau?, xyz?}], start: {q, dq, ddq}, limits: {q_min, q_max, dq_max, ddq_max, dddq_max, tau_max?, xyz_min?, xyz_max?}}; every step must lie inside the band (409 outside_solved_band) and q_min and q_max are clipped to it
policy_sha256the site's operator policy hash, 64 hex
model_sha256the model's hash, 64 hex
birth_record_sha256optional, 64 hex
envelopesetpoint only: {min?, max?, max_rate_per_s}, clipped to the band; the site applies its own stricter envelope
ttl_s1..300; default 60
modeshadow (the default) or actuate
system_classthe class of system the actuator belongs to, a lowercase name; required for actuate
PUT/physical/approvers/:idadmin

Enrol an approver key, or replace it: the hardware-held key whose signature makes an actuation approval valid. Needs the project in LW_PHYSICAL_COMMAND_TENANTS.

Body

keythe approver's key as ed25519:<64 lowercase hex>
GET/physical/approversmember

The project's enrolled approver keys.

POST/physical/approvalsadmin

Store an actuation approval: the request body is its canonical JSON text byte for byte (format actuation-approval, version 1). Verified against an enrolled approver key, for this project and an enrolled site, not yet ended; valid for at most 31 days. The same record twice is accepted once; a different record with the same id is a 409. Codes: malformed, not_canonical, unsupported_format, approval_too_long, unknown_approver, bad_signature, wrong_tenant, approval_expired, approval_conflict.

GET/physical/approvalsmember

The project's approvals with their site, class, actuators, kinds, validity and status (active, pending, expired or revoked).

POST/physical/approvals/:id/revocationadmin

Revoke an approval. Core stops issuing under it at once; the site's own copy is removed at the site by its operator, and a receipt that reports an execution under a revoked approval is recorded with an alert.

GET/physical/commandsmember

Commands issued, newest first, each with what the site decided (decision, code, ledger position) once its receipt is in.

Query

siteone site
limit1..200; default 50
POST/physical/receiptsmember

A site's receipt for a command, as its canonical JSON text (the request body, byte for byte). Verified against the key registered for the site and recorded; a replay of the same receipt is accepted once, a different receipt with the same sequence number is a 409. A receipt is recorded with an alert when it contradicts what core issued: executed_in_shadow_mode, execution_unapproved, execution_under_revoked_approval, mode_differs or command_hash_differs.

GET/physical/kindsmember

The physical interface: every measurement kind with its family, unit, range, whether it is measured or inferred, and the twin variable it validates; the derived signals; the purpose domains and the usual kinds of system; the integrations (robot_middleware, industrial_server, motion_bus, message_broker, vehicle_bus, register_device) with the systems and purposes they serve, the kinds and units they carry, their attestation ceiling (soft), that they are observe only and shadow only, and what has and has not been run; the capabilities (measure, plan, gate, actuate). Stateless; it reaches no site.

POST/physical/purposes/checksmember

Check a description of what a system is for: its purpose domains, the quantities it measures, the actions it can take, its safe operating limits and its twin. Answers every issue with a code; an action without a limit, a limit in the wrong unit, an unknown kind and a request to act are errors. Stores nothing and acts on nothing.

Body

vthe number 1
namestring
purpose[compute|processing|physics|motion|measurement|environment|energy|fluid_thermal|structure]
systemoptional kind of system
quantities[{kind, unit?, axes?, rate_hz?, uncertainty_sd?}]
integrationsoptional [integration id]: checked against the systems and purposes it serves and the kinds it carries
actions[{action: setpoint|trajectory|mode|model_update|calibration_update, quantity, unit, min?, max?}]
limits[{quantity, unit, min, max, max_rate_per_s?}]
twin{id?, variables: [string]}
POST/physical/measurements/admissionsmember

Decide what one typed measurement may be used for against a twin's solved band: inform always; validate and recalibrate only inside the band, only at or above the attestation floor, and recalibrate only when the sensor measured it rather than inferred it. Outside the band, or with no band, it validates nothing. Stateless.

Body

measurement{v: 1, kind, value, unit, uncertainty_sd?, attestation: soft|device|se|tee|dice|tpm, modality?: direct|inferred, placement?: environment|device}
bandthe twin's band, {mean.<variable>: [min, max]}, or null
floorlowest attestation level accepted; default soft
GET/physical/measurements/statsadmin

What the admissions route has been asked since this core started, for this project: per key label, requests, accepted, informs-only (could not validate), refused with the code, and by kind with the units seen, and when one was last seen. Counts only, kept in memory, emptied by a restart (since says from when).

POST/physical/signalsmember

Compute a derived signal (tilt_angle, vibration_rms, angular_speed, field_strength, dew_point, mechanical_power, pressure_height_change) from verified measurements, only inside the regime it is valid in; its attestation is the lowest of its inputs. Stateless.

Body

signalname
inputs[{kind, value, unit, attestation}]
referencereference pressure in pascals, for pressure_height_change
A glass tree whose crown holds many small worlds like fruit

Which world will you live in?

What grows here is meant to reach the real world. Start with a world of your own.