ora/contracts/toolkit_protocol.py defines the single, manually numbered
PROTOCOL_VERSION = 1. The current readers declare support for [1]. This is
a semantic protocol number, not a source/content hash. Source hashes remain
evidence of what actually ran.
Every newly launched run has public toolkit-protocol.json, including runs
with record_toolkit_io=false. It is written before the Supervisor starts:
{
"schema": "ora.toolkit.protocol.v1",
"protocol_version": 1,
"recording_enabled": false,
"methods": ["perception.*", "state.*", "planner.*", "act.*", "episode.*", "privileged.*", "artifacts.*", "compute.*", "context.*"],
"implementation": {"harness_commit": "<run commit>"}
}
When recording is enabled, native/toolkit-io/manifest.json declares the same
protocol, and every calls.jsonl begin/end event carries protocol_version.
The request identity/hash and invocation ID formats do not change. Existing
logs and snapshots need no migration; source runs are never backfilled.
Replay results contain protocol_compatibility: source_version,
current_version, supported_versions, status (matched, mismatch,
unknown), all observed declarations in evidence, and warnings with the
potentially affected method families. Conflicting root/manifest/event versions
remain visible. Missing legacy versions produce unknown, not an assumed 1.
protocol_matched and exact_replay_eligible refer only to protocol agreement:
agreement is necessary, not sufficient, for an exact-replay claim. Physics,
source identity, service comparisons and sensor statistics have their own
evidence. Warnings are also copied to the result's top-level warnings.
A mismatch or missing version does not block execution with the current
decoder. A decodable method_version mismatch also warns: matching compares
all other semantic request fields exactly, while validating the stored
semantic hash against the original request, including its original version.
No action parameters, service identities, boundary identities or blob hashes
are normalized or waived. Unknown wire schemas without a decoder remain
unsupported. A protocol number alone cannot supply a missing decoder.
Audit of replay gates
Paths below are relative to ora/. “Kept” checks are intentionally not version
admission. This audit includes the old diagnostic and new snapshot paths.
| Path / check | Before M7.6 | After M7.6 |
|---|---|---|
agent/toolkit/interface/journal.py: request method_version |
Only 1 accepted | Decodable requests accepted; warning in protocol audit |
interface/replay.py, experiment.py, snapshot_services.py: request matching |
Hash equality also rejected a changed method-version label | Only that label ignored for matching; original hash still validated |
orchestrator/toolkit/replay.py: recorded/auto/live; snapshot_replay.py: snapshot/step/native-action |
No common protocol declaration | Root/manifest/events audited, including failed attempts; result includes both versions |
orchestrator/backends/robodojo/motion/replay.py: kernel admission in launch/report, launch commit vs report commit |
Kernel rejection unless admitted or explicitly overridden; report failed for another launch commit | Warnings include both identities and kernel admission's differing paths; no version-based failure |
orchestrator/backends/robodojo/toolkit_live.py: legacy live kernel equality |
Required identical kernel (native-action already warned) | Both paths warn; host/lease/clean-checkout constraints unchanged |
environment/backends/robodojo/control_replay.py: _require_same_sources |
Revision, layout hash and reset fingerprint differences rejected | Returns source warnings, persisted in worker and host reports |
environment/backends/robodojo/toolkit_restore.py / toolkit_native_state.py |
Native-action warned; old live restore rejected source drift | Shared warning audit for both; includes bootstrap warnings |
environment/backends/robodojo/bridge.py / source_identity.py: required source pins, tracked modifications, layout hash, derived CuRobo template, interpreter/package version |
Strict bootstrap rejection | Diagnostic worker config replay_identity_warnings=true warns with recorded/current values; production bootstrap remains strict |
environment/backends/robodojo/layout_rounds.py: scheduled file digest and planned digest at round start |
Rejected changed layout bytes | Diagnostic-only warning for planned identity; current file must still match bootstrap manifest and actual loaded scene |
orchestrator/evaluation/provider_replay.py: tape comparison |
No version-based gate; raw request comparison | Adds source/current and candidate protocol reports and implementation-commit warning; raw request differences unchanged |
orchestrator/toolkit/surface_audit.py |
Current vs frozen surface already warned | Unchanged; malformed frozen evidence and its own hash mismatch still reject |
agent/toolkit/lib/manifest.py, toolkit tool/script implementation hashes |
Evidence only; no identity gate | Unchanged |
| Q32 qualification/revalidation | Missing/stale qualification and kernel already warnings | Unchanged; this task does not loosen production launch |
The original python -m ora.environment.backends.robodojo.control_replay
entry now explicitly enables the diagnostic source-warning bootstrap, even
with an older worker config. A production qualification_binding in that
config is recorded as warning evidence and omitted from diagnostic bootstrap
(the host launcher already omitted it); operational and physical checks remain.
Its worker report includes protocol and source
warnings. Recorded control decoding, replay_control, native ticks, applied
target comparison, clocks, joint/finger/link6 comparisons, round sequencing,
teardown and output isolation are unchanged. ora motion replay no longer
needs --allow-kernel-drift; the flag is retained for CLI compatibility.
Its historical optional private-object determinism metric remains a reported
metric, not a newly introduced gate. Existing live/native/align physical and
GT verification gates remain strict.
Provider tape candidates are new formal runs: their preflight and bootstrap remain strict, including runtime pins. Comparison warnings do not authorize cross-runtime production startup. Such a mode would need a separate explicit diagnostic design. This distinction was confirmed for M7.6.
Refusals that remain
- CAS/blob length/hash checks, frozen manifest hashes, step hash chains and request hashes check the integrity of stored evidence, not code versions.
- Parent/model/call/round/observation/controller identities, exact normalized action matching, cursor order, ambiguous responses and gaps remain strict.
- Unknown schemas/methods without a decoder are unsupported; missing evidence remains NotRecorded. No future state is imported to fill a hole.
- All existing physical restoration comparisons and required GT comparisons still gate capability authorization. Sensor differences remain statistics under M7.4b; they are not silently called byte-exact.
- Path allowlists, output separation, clean checkout, allocation/lease and process cleanup checks remain. Warning mode grants no extra robot capability.
When to increment
Increment the number when changing public method semantics: signatures or defaults, semantic envelopes or blob encoding, units/frames, source categories, permission meaning, boundary/cursor semantics, or service comparison rules. Record the migration and supported decoder versions with that change. Keeping a decoder for an older version is an explicit implementation promise.
Do not increment for refactoring, a new commit, a tool/lib implementation hash, logging of additional advisory evidence, or a renderer producing different bytes. These identities and differences remain evidence independently of the protocol number. Version 1 describes the existing nine-family data interface; this change adds its declaration without changing robot-visible behavior.
CPU validation / live follow-up
Tests cover matching, mismatching and absent versions; conflicting declarations; old unversioned logs; differing method versions with valid original hashes; corrupt hashes still refused; publication/replay results; production vs diagnostic bootstrap; and changed kernels with exact vs divergent physical replay. No simulator or GPU run is part of this implementation check. The reviewer will validate a historical run on a router allocation.