feat(perception): define stream-first profile and qualification contracts
This commit is contained in:
DCCONSTRUCTIONS
@@ -0,0 +1,175 @@
|
|||||||
|
{
|
||||||
|
"schema_version": "missioncore.perception-profile-candidate/v1",
|
||||||
|
"profile_id": "k1-perception-ddrnet39-rfdetr-tgs-prototype/v1",
|
||||||
|
"display_name": "K1 Perception — DDRNet-39 + RF-DETR + TGS",
|
||||||
|
"status": "stage-1-candidate-not-installed-not-qualified",
|
||||||
|
"experiment_policy": {
|
||||||
|
"bounded_lab_overload_allowed": true,
|
||||||
|
"retain_profiles_that_fail_current_hardware_realtime": true,
|
||||||
|
"realtime_failure_blocks_experimental_packaging": false,
|
||||||
|
"qualification_scope": ["profile-version", "effective-config", "hardware", "source", "transport"],
|
||||||
|
"preserve_original_source_clock": true,
|
||||||
|
"report_drops_and_staleness": true,
|
||||||
|
"overload_is_realtime_pass": false,
|
||||||
|
"future_onboard_placement_requires_new_measurement": true
|
||||||
|
},
|
||||||
|
"packaging": {
|
||||||
|
"image": "ndc-k1-perception-ddrnet39-rfdetr-tgs:prototype-v1",
|
||||||
|
"image_sha256": null,
|
||||||
|
"single_container": true,
|
||||||
|
"external_model_server_required": false,
|
||||||
|
"host_model_cache_required": false,
|
||||||
|
"runtime_model_download_allowed": false,
|
||||||
|
"model_environment_isolation": "supervised-processes-one-gpu-scheduler",
|
||||||
|
"common_interpreter_required": false
|
||||||
|
},
|
||||||
|
"hardware_baseline": {
|
||||||
|
"gpu": "NVIDIA GeForce RTX 4090",
|
||||||
|
"active_profiles_per_worker": 1,
|
||||||
|
"sources_per_worker": 1,
|
||||||
|
"gpu_inference_policy": "serialized",
|
||||||
|
"other_gpu_workloads_allowed": false
|
||||||
|
},
|
||||||
|
"cpu_execution_policy": {
|
||||||
|
"OPENBLAS_NUM_THREADS": 1,
|
||||||
|
"OMP_NUM_THREADS": 1,
|
||||||
|
"MKL_NUM_THREADS": 1,
|
||||||
|
"reason": "bounded-single-thread-numeric-libraries-before-whole-graph-qualification"
|
||||||
|
},
|
||||||
|
"input_contract": {
|
||||||
|
"schema_version": "missioncore.perception-stream-start/v1",
|
||||||
|
"channels": ["camera", "point-cloud", "pose"],
|
||||||
|
"camera": {
|
||||||
|
"width": 800,
|
||||||
|
"height": 600,
|
||||||
|
"projection": "KB4",
|
||||||
|
"decoded_pixel_format": "bgr8",
|
||||||
|
"calibration_sha256": "05f3ad9b38b3a4fc95388a8ec83da83c745e217709e51787b3d5aad0969f6fa9",
|
||||||
|
"valid_fov_sha256": "a40cee06b7c6f69b6a09a11563dcfd237f3de833b1ccd31459e66692e528ba63"
|
||||||
|
},
|
||||||
|
"point_cloud": {
|
||||||
|
"representation": "vendor-registered-current-increment",
|
||||||
|
"coordinate_frame": "map",
|
||||||
|
"units": "metres",
|
||||||
|
"scalar_type": "float32-little-endian",
|
||||||
|
"raw_fields_retained": true
|
||||||
|
},
|
||||||
|
"pose": {"parent_frame": "map", "child_frame": "sensor"},
|
||||||
|
"clock_mapping_required": true,
|
||||||
|
"source_end_or_duration_required": false,
|
||||||
|
"full_source_transfer_required": false,
|
||||||
|
"full_source_hash_pass_required": false,
|
||||||
|
"full_decode_or_png_cache_required": false,
|
||||||
|
"previous_perception_artifacts_allowed": false
|
||||||
|
},
|
||||||
|
"stream_policy": {
|
||||||
|
"replay_speed": 1.0,
|
||||||
|
"release_clock": "original-source-timestamps",
|
||||||
|
"inference_stride": 1,
|
||||||
|
"sampling_status": "strict-every-frame-initial-baseline-no-silent-multirate",
|
||||||
|
"first_result_requires_eof": false,
|
||||||
|
"lookahead_allowed": false,
|
||||||
|
"reconnect": "new-epoch-drop-old-backlog-reacquire-codec-keyframe",
|
||||||
|
"overflow": "bounded-drop-with-ledger-degraded-and-failed-runtime-gate",
|
||||||
|
"archive_export_on_critical_path": false,
|
||||||
|
"transport_candidate": "grpc-bidirectional-protobuf-binary-payloads",
|
||||||
|
"transport_qualified": false
|
||||||
|
},
|
||||||
|
"components": {
|
||||||
|
"segmentation": {
|
||||||
|
"model": "ddrnet_39-goose-fine-64",
|
||||||
|
"checkpoint_sha256": "b99c2838051bcd7b092fd3970aa62a77d5c0bbb809c9b9afb2ff4b0ebdaa4ee6",
|
||||||
|
"precision": "existing-fp32-baseline",
|
||||||
|
"preprocessing": "center-600-square-to-512-rgb-tensor-0-1",
|
||||||
|
"outside_crop": "undefined-not-free",
|
||||||
|
"class_count": 64,
|
||||||
|
"runtime": "python-3.9-pytorch-1.13.1-cu117-super-gradients-3.2.0"
|
||||||
|
},
|
||||||
|
"objects": {
|
||||||
|
"model": "rf_detr_large_native_kb4",
|
||||||
|
"checkpoint_sha256": "0f4e20e19a99c0f8a62b5685f57f6c8b5c371c59081feda6752a0561a79ccf38",
|
||||||
|
"engine_sha256": "b8a40b3580edff001ec9680de68707242294ff590ab296000fae371f1083f695",
|
||||||
|
"runtime": "tensorrt-11-fp16-native-uint8",
|
||||||
|
"minimum_score": 0.25,
|
||||||
|
"minimum_box_area_pixels": 64,
|
||||||
|
"maximum_box_area_fraction": 0.5,
|
||||||
|
"minimum_valid_fov_fraction": 0.5,
|
||||||
|
"require_center_inside_valid_fov": true,
|
||||||
|
"required_existing_classes": ["person", "cat", "dog"],
|
||||||
|
"fine_static_object_classifier_required": false,
|
||||||
|
"filter_quality_status": "existing-unchanged-near-large-and-small-object-risk-unqualified"
|
||||||
|
},
|
||||||
|
"geometry": {
|
||||||
|
"online_surface": "K1LocalSurfaceShadowEstimator",
|
||||||
|
"prepared_local_surface_allowed": false,
|
||||||
|
"generic_static_class": "static.unknown",
|
||||||
|
"detected_object_range": "median-camera-z-of-owned-current-points/v1",
|
||||||
|
"geometry_only_range": "nearest-euclidean-sensor-distance/v1",
|
||||||
|
"vehicle_clearance_claim": false,
|
||||||
|
"missing_support": "unavailable-not-zero-not-free"
|
||||||
|
},
|
||||||
|
"motion": {
|
||||||
|
"reuse": "BoundedSpatialTemporalProvider+ClassIndependentMotionEstimator",
|
||||||
|
"semantic_class_implies_motion": false
|
||||||
|
},
|
||||||
|
"costmap": {
|
||||||
|
"algorithm": "TRAVEL-TGS",
|
||||||
|
"revision": "95dc2fbd66a343efd9060c45a5711b6307a950a4",
|
||||||
|
"execution": "cpu",
|
||||||
|
"rolling_history_seconds": 1.0,
|
||||||
|
"states": ["UNOBSERVED", "GROUND_SUPPORT", "NONGROUND_OCCUPIED", "UNKNOWN_REJECTED"],
|
||||||
|
"policy_input": true
|
||||||
|
},
|
||||||
|
"policy": {
|
||||||
|
"scope": "rural-prototype-advisory-only",
|
||||||
|
"hard_surface": "ALLOW-candidate-subject-to-geometry-and-freshness",
|
||||||
|
"fine_road_sidewalk_bikeway_distinction_required": false,
|
||||||
|
"effective_material_rules_required": true,
|
||||||
|
"unknown_or_occupied_overrides_material_allowance": true,
|
||||||
|
"sensor_to_vehicle_mount": "simulation-only-until-measured"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"reference_files": [
|
||||||
|
{"path": "config/perception/rf-detr-large-native-kb4-risk-shadow-v0.json", "sha256": "dbf4da5dbad6c3c22b1280b46ffcad81719bd183c81c263a4859847d829019b6"},
|
||||||
|
{"path": "config/perception/lab-v1-goose-vegetation-benchmark-v1.json", "sha256": "96a427a8baae387b827ec9c0bf7ca42e3fb9114b8fa9a8671bbc9d10877670b9"},
|
||||||
|
{"path": "config/perception/lab-v1-vegetation-provider-label-map-v1.json", "sha256": "f2b69046b6a740fd9532d2d88e7fabae7c20fb662f783c9502adc9026406f352"},
|
||||||
|
{"path": "config/perception/lab-v1-vegetation-mission-policy-v1.json", "sha256": "b75c4ac841d7b4bcc57f7a9c8417ca2317d8ecfa499e72a9af8a8591a2ec0d35"},
|
||||||
|
{"path": "config/perception/m49-tgs-full-shadow-v1.json", "sha256": "c2e07010aaee78259d36c057962d6bfb885349251ff7356d867e5813e632881c"},
|
||||||
|
{"path": "config/perception/m4-geometry-association-v1.json", "sha256": "cc666c9389a5e221957faddec89584709b66918d14abaf646f1832e001421999"}
|
||||||
|
],
|
||||||
|
"reference_usage": "reuse-model-parameters-and-algorithms-only-not-recording-ids-or-precomputed-results",
|
||||||
|
"realtime_contract": {
|
||||||
|
"schema_version": "missioncore.perception-realtime-contract/v1",
|
||||||
|
"budget_status": "engineering-targets-worker-pilot-measured-not-whole-path-qualified-not-safety-approved",
|
||||||
|
"budgets": {
|
||||||
|
"maximum_start_metadata_bytes": 65536,
|
||||||
|
"maximum_chunk_bytes": 1048576,
|
||||||
|
"maximum_inflight_bytes": 16777216,
|
||||||
|
"maximum_pending_camera_frames": 2,
|
||||||
|
"maximum_codec_preroll_ms": 500.0,
|
||||||
|
"maximum_pose_age_ms": 100.0,
|
||||||
|
"maximum_clock_uncertainty_ms": 5.0,
|
||||||
|
"maximum_release_lag_ms": 25.0,
|
||||||
|
"maximum_output_age_p95_ms": 125.0,
|
||||||
|
"maximum_output_age_p99_ms": 125.0,
|
||||||
|
"maximum_layer_age_ms": 250.0,
|
||||||
|
"maximum_first_result_ms": 1000.0,
|
||||||
|
"maximum_warmup_seconds": 120.0,
|
||||||
|
"maximum_stop_seconds": 5.0,
|
||||||
|
"maximum_vram_mib": 22000,
|
||||||
|
"maximum_rss_mib": 8192,
|
||||||
|
"maximum_backlog_growth_ms": 25.0
|
||||||
|
},
|
||||||
|
"budget_origin": "125ms-historical-envelope-retained-as-target-now-applied-to-whole-path; other-limits-explicit-initial-engineering-guards",
|
||||||
|
"capacity_drop_count_max": 0,
|
||||||
|
"unaccounted_input_count_max": 0,
|
||||||
|
"full_input_transfer_before_first_result_allowed": false,
|
||||||
|
"independent_quality_and_physical_live_status": "pending"
|
||||||
|
},
|
||||||
|
"authority": {
|
||||||
|
"commands_enabled": false,
|
||||||
|
"actuation_allowed": false,
|
||||||
|
"navigation_or_safety_accepted": false,
|
||||||
|
"production_accepted": false
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,236 @@
|
|||||||
|
# ADR 0049 — Stream-first full perception profiles
|
||||||
|
|
||||||
|
Date: 2026-09-01. Status: stage-1 contract candidate; not a runtime cutover.
|
||||||
|
Execution order remains the four stages in
|
||||||
|
[the ExecPlan](../OBSERVATORY_REALTIME_PROFILES_EXECPLAN.md).
|
||||||
|
|
||||||
|
## Decision and owner intent
|
||||||
|
|
||||||
|
Observatory LABs test the real-time behavior of a complete perception profile,
|
||||||
|
not just the quality of an offline export. A recording replaces the physical
|
||||||
|
source, preserving original release timing at 1×. It must not enable a different
|
||||||
|
batch implementation. The first profile contains DDRNet-39 GOOSE, RF-DETR native,
|
||||||
|
online LiDAR geometry/ranges, temporal/motion, CPU TRAVEL TGS/costmap and advisory
|
||||||
|
policy. One dedicated RTX 4090 owns one active full profile.
|
||||||
|
|
||||||
|
The first rural prototype accepts existing coarse `hard_surface`, including
|
||||||
|
asphalt, sidewalk, bikeway and cobble. Existing `static_obstacle`/`static.unknown`
|
||||||
|
is sufficient. No new bollard classifier, extra segmenter, road/sidewalk taxonomy
|
||||||
|
or annotation campaign precedes this prototype. Other material rules remain an
|
||||||
|
explicit effective mission configuration; rural context alone is not permission
|
||||||
|
for all vegetation or soil. Geometry/unknown/freshness overrides material allowance.
|
||||||
|
|
||||||
|
EoMT is preserved as a separate future profile. It is not loaded with DDRNet.
|
||||||
|
RF-DETR and DDRNet are two required components of the same first profile: one
|
||||||
|
supervisor and serialized GPU scheduling, not competing profile jobs.
|
||||||
|
|
||||||
|
## CURRENT → TARGET / ownership
|
||||||
|
|
||||||
|
| Boundary | Current evidence | Decision / stage |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| Portable definitions | `portable_run_definitions.py` owns pins, resources and admission | KEEP identity/sealing; EXTEND stream capabilities and qualification in stage 3 |
|
||||||
|
| Source requirements | Recorded-only requirements include seekability, one media epoch and init digest | REPLACE as live admission criteria with channel/format/calibration/clock requirements; keep init digest as per-stream integrity |
|
||||||
|
| Job queue | `recorded_jobs.py` has durable claims but global single-active-job scope | KEEP durable queue; EXTEND worker-scoped fencing, not unbounded GPU concurrency |
|
||||||
|
| Worker agent | Blocking `execute(job)` and final publication | EXTEND incremental lifecycle and cancellation; no per-LAB agent |
|
||||||
|
| Runtime | `portable_worker_runtime.py:735` materializes before execution | NEW stream runtime in stage 2; never call this materializer in the real-time path |
|
||||||
|
| Source transport | Whole camera archive download/hash/extraction before use | REPLACE startup barrier with bounded metadata, chunks and incremental integrity |
|
||||||
|
| Installed LAB V1 | prepare → complete EoMT → complete DDRNet → assemble | Legacy evidence only; not the new profile and not real-time qualified |
|
||||||
|
| Camera/source replay | `recorded_source.py` has useful pacing and bounded prefetch, but source-specific timeline and paths | REUSE mechanisms; generic unknown-duration source adapter, no route-sized prefetch |
|
||||||
|
| Existing live ingress | `LivePerceptionIngress`, `LiveIngressEvent.wire_bytes`, `LiveSensorSynchronizer` already provide raw-first modality queues, hashes, epochs and bounded binding | REUSE, not a second acquisition system; extend worker/profile fencing and aggregate byte limits; map existing envelopes to the selected transport |
|
||||||
|
| Local surface | `RecordedGeometryStore` reads prepared NPZ | REUSE `K1LocalSurfaceShadowEstimator.process` and `lidar_local_surface_geometry`; feed current points/pose |
|
||||||
|
| Geometry/ranges | Current point association, exclusive ownership and geometry-only clusters exist | REUSE algorithms; remove recorded-store dependency and expose estimator/frame identity |
|
||||||
|
| Temporal/motion | `BoundedSpatialTemporalProvider`, `ClassIndependentMotionEstimator` | REUSE with current-run inputs and reset on epoch/lease change |
|
||||||
|
| TGS | Core algorithm reusable; old runners read a full schedule, some require exactly 4489 frames | REUSE TGS parameters/core; REPLACE schedule/file CLI with incremental input |
|
||||||
|
| Fusion | M49 TGS can be a neighboring shadow with `tgs_modifies_reference_graph_state=false` | TGS and semantics must influence the current advisory scene, not only viewer composition |
|
||||||
|
| Publication | Verified immutable result/publication/recovery exist | KEEP asynchronous final sealing; live results do not await it |
|
||||||
|
| Frontend | Setup/job/result surfaces exist, historical M49 viewer links other results | EXTEND common renderer capabilities with current-run layer references and freshness in stage 3 |
|
||||||
|
| Recording archive | Source identities and raw evidence must be retained | KEEP; create metadata/index/integrity during acquisition or incrementally, not via preflight full scan |
|
||||||
|
|
||||||
|
No changes to the active registry, old queue, source endpoint, UI or canonical
|
||||||
|
local server are made by this ADR or the stage-1 validators.
|
||||||
|
|
||||||
|
## Versioned handshake and observations
|
||||||
|
|
||||||
|
`missioncore.perception-stream-start/v1` is represented by `StreamStart` in
|
||||||
|
`src/k1link/perception/realtime_contract.py`. It contains run/source/worker/epoch,
|
||||||
|
lease generation, profile/image/effective-config/calibration identities, clock
|
||||||
|
domain, input mode and channel declarations. The first profile requires camera,
|
||||||
|
point-cloud and pose. Temporary absence of a sample is an explicit modality
|
||||||
|
outcome, not removal of a required capability.
|
||||||
|
|
||||||
|
It deliberately has no total source bytes, frame count, total duration, whole
|
||||||
|
archive, command, environment, complete member inventory or required EOF. The
|
||||||
|
initial metadata budget is 64 KiB. Large constant model assets and FOV masks
|
||||||
|
belong inside the image; calibration references resolve to bounded metadata.
|
||||||
|
|
||||||
|
The stage-2 wire mapping must carry:
|
||||||
|
|
||||||
|
- Run/epoch/lease binding on every message; source/channel sequence, capture
|
||||||
|
timestamp and clock domain; independently verifiable payload length/hash.
|
||||||
|
- Camera codec initialization and then incremental encoded access units, or
|
||||||
|
bounded fragments thereof. Native decoded representation is BGR8 800×600 KB4.
|
||||||
|
Do not send an entire fMP4 epoch as one observation or turn all frames into PNGs.
|
||||||
|
- Current vendor-registered map point increments with point IDs, coordinate
|
||||||
|
frame, units, scalar layout and retained raw attributes; map→sensor pose and
|
||||||
|
calibration identity. The adapter owns vendor decoding; the profile is not a
|
||||||
|
new K1 protocol implementation and cannot command the scanner.
|
||||||
|
- Explicit unavailable/gap/end/cancel messages. End is a termination event,
|
||||||
|
never a prerequisite for first inference. Final recording inventory/hash can
|
||||||
|
be sealed after consumption; per-chunk integrity is verified before use.
|
||||||
|
- Integer nanoseconds use protobuf integer fields; any JSON projection uses
|
||||||
|
decimal strings for 64-bit times rather than lossy JavaScript numbers.
|
||||||
|
|
||||||
|
Maximum payload fragment: 1 MiB; total application inflight bytes: 16 MiB;
|
||||||
|
pending decoded camera frames: 2. Fragment reassembly is included in that budget,
|
||||||
|
with a deadline and incomplete-chunk accounting. Decoded image/tensor, cloud,
|
||||||
|
costmap and archive sinks need their own measured bounds inside the RSS budget.
|
||||||
|
Transport flow control alone is not a memory bound or a freshness policy.
|
||||||
|
|
||||||
|
gRPC bidirectional streaming is the first transport candidate, not an already
|
||||||
|
measured implementation. HTTP control-plane operations remain. The browser does
|
||||||
|
not connect directly to model RPCs. One authenticated data-plane endpoint feeds
|
||||||
|
the supervised profile; model processes have no arbitrary external network.
|
||||||
|
Protocol/codec selection must be measured on actual payload sizes in stage 2;
|
||||||
|
changing an archive POST to gRPC without changing execution is not acceptance.
|
||||||
|
Existing `missioncore.live-perception-wire/v1` and result wire v2 are migration
|
||||||
|
inputs: reuse their semantics and raw-first producer hooks. Their modality count
|
||||||
|
caps alone permit more than the proposed 16 MiB aggregate inflight budget; an
|
||||||
|
explicit byte bound is required. No duplicate new scanner feed is introduced.
|
||||||
|
|
||||||
|
## Time and lifecycle
|
||||||
|
|
||||||
|
Open → validate bounded metadata/claim → warm models → Ready → start the replay
|
||||||
|
clock → observations and incremental scenes → stop/drain bounded state → close
|
||||||
|
and asynchronously seal the immutable receipt. A live source already producing
|
||||||
|
data does not queue its entire warmup history: readiness begins at a current
|
||||||
|
decodable keyframe, with the skipped interval recorded.
|
||||||
|
|
||||||
|
Replay release uses original source intervals, not a convenient fixed 12 Hz and
|
||||||
|
not the processing speed. A slow consumer must not stretch source time to make
|
||||||
|
inference look real-time. Overload may drop bounded work to preserve liveness,
|
||||||
|
but the dropped observations remain in the ledger and fail the strict initial
|
||||||
|
performance target. Initial baseline is every camera frame, stride 1. Choosing
|
||||||
|
multirate later changes the explicit profile contract; a retained mask is not a
|
||||||
|
new inference and cannot receive a fresh capture timestamp.
|
||||||
|
|
||||||
|
UTC identifies the run; monotonic clocks measure local durations. Cross-host
|
||||||
|
age requires a clock mapping and its uncertainty. No direct subtraction of
|
||||||
|
unrelated host monotonic clocks. The common source timeline is separate from
|
||||||
|
worker wall-clock time. Causality is bounded by the released-observation
|
||||||
|
watermark at decision time, not by whatever later samples exist in the file.
|
||||||
|
Each layer retains its own channel/sequence/time; camera anchors and pose/cloud
|
||||||
|
association times remain separately visible. Future file look-ahead and offline
|
||||||
|
nearest-pose lookup across unreleased data are forbidden.
|
||||||
|
|
||||||
|
Lease expiry, cancellation and epoch changes fence the previous producer. No
|
||||||
|
new profile may take the GPU until old processes and work have stopped. A
|
||||||
|
reconnect creates a new epoch, discards stale backlog, resets temporal/rolling
|
||||||
|
state and reacquires codec initialization/keyframe. It never resends a stale
|
||||||
|
motor action; this profile has no motor actions at all.
|
||||||
|
|
||||||
|
## Outputs and interpretation
|
||||||
|
|
||||||
|
Every scene accounts for segmentation, objects, geometry, motion, costmap and
|
||||||
|
policy exactly once, with current/held/stale/unavailable state and current-run
|
||||||
|
payload identity. Existing source/object/obstacle/temporal/map/threat contracts
|
||||||
|
remain the domain vocabulary. `LayerEvidence` adds freshness/completeness checks,
|
||||||
|
not a second semantic ontology. In stage 2, layer manifests also carry their full
|
||||||
|
input reference sets; a single anchor does not replace camera/cloud/pose lineage.
|
||||||
|
|
||||||
|
DDRNet currently crops the center 600×600 to 512×512; outside that ROI is undefined,
|
||||||
|
not hard_surface/free. RF-DETR accepts the full 800×600 native raster with its
|
||||||
|
pinned valid-FOV handling. Their coordinates must be related explicitly.
|
||||||
|
|
||||||
|
RF-DETR's existing filter emits person/cat/dog, but minimum box area 64 px,
|
||||||
|
maximum box fraction 0.5, FOV fraction 0.5 and required valid center create known
|
||||||
|
small-animal/close-large-object edge cases. They are retained and documented,
|
||||||
|
not silently retuned or presented as proven field quality.
|
||||||
|
|
||||||
|
Detected-object range is the median camera-Z of owned current support points;
|
||||||
|
geometry-only range is nearest Euclidean distance from the sensor. Neither is
|
||||||
|
automatically clearance from the physical vehicle body. Missing/ambiguous
|
||||||
|
support produces unavailable range, not zero/infinity. Generic static obstacles
|
||||||
|
survive absence of a detector class name.
|
||||||
|
|
||||||
|
TGS keeps ground/occupied/rejected/unobserved separate. Ground support alone is
|
||||||
|
not a traversability or actuation decision. Policy can produce an advisory
|
||||||
|
allowed-candidate/high-cost/blocked/unknown outcome with explanation. No planner,
|
||||||
|
physical motor command, autonomous driving acceptance or mission configurator
|
||||||
|
implementation is introduced.
|
||||||
|
|
||||||
|
## Package/dependency decision
|
||||||
|
|
||||||
|
The candidate manifest is
|
||||||
|
`config/perception/k1-perception-ddrnet39-rfdetr-tgs-prototype-v1.json`.
|
||||||
|
It is not installed into the active portable registry and has no invented image
|
||||||
|
digest. Model/checkpoint/config identities are pinned; source session IDs and old
|
||||||
|
derived output paths in reference experiments are not inherited requirements.
|
||||||
|
|
||||||
|
Select process/environment isolation inside one future image: Python 3.12
|
||||||
|
supervisor and geometry, RF-DETR TensorRT 11 runtime, existing Python 3.9 / Torch
|
||||||
|
1.13.1 cu117 / super-gradients 3.2.0 environment, and CPU C++ TGS. Exchange bounded
|
||||||
|
shared-memory/IPC payload references; one supervisor serializes GPU work. This
|
||||||
|
avoids a forced dependency upgrade or checkpoint conversion in stage 1. Image
|
||||||
|
assembly of the final standalone package and the full schedule pilot remain
|
||||||
|
explicit implementation evidence. A temporary common-base image passed separate
|
||||||
|
DDRNet, TensorRT, Python 3.12 geometry and C++ TGS execution probes; DDRNet masks
|
||||||
|
matched on 64 frames. This proves bounded ABI/execution compatibility in that
|
||||||
|
image, not jointly resident models, the supervisor/IPC or a complete profile.
|
||||||
|
The probes still mount pinned assets explicitly; they are not standalone proof.
|
||||||
|
|
||||||
|
The temporary Triton base lacks Python grpc/protobuf, cv2 and TensorRT bindings;
|
||||||
|
native trtexec/server are present. The actual supervisor/transport environment
|
||||||
|
must explicitly include and validate its dependencies. Numeric-library thread
|
||||||
|
limits are pinned to one after the bounded synthetic local-surface comparison
|
||||||
|
(mean 198.0 ms default versus 63.2 ms with limits); algorithm thresholds were not
|
||||||
|
changed. Real-cloud timing, output parity and whole-graph scheduling remain gates.
|
||||||
|
|
||||||
|
The initial DDRNet image-only probe failed before inference: the installed image
|
||||||
|
does not contain the checkpoint at its logical asset path. The bounded baseline
|
||||||
|
therefore uses an explicit read-only pinned checkpoint and runner mount. This is
|
||||||
|
valid component measurement, but fails the target's standalone packaging claim.
|
||||||
|
Super-gradients also needs a writable log directory; a bounded temporary log
|
||||||
|
mount was required. The new image must declare scratch areas explicitly without
|
||||||
|
requiring a writable host home, code checkout or implicit weight cache.
|
||||||
|
|
||||||
|
## Preregistered engineering acceptance
|
||||||
|
|
||||||
|
Owner clarification, 2026-09-02 MSK: bounded laboratory overload is an admissible
|
||||||
|
experimental outcome. Keep useful profiles that fail the current 4090 target;
|
||||||
|
do not block reusable runtime/packaging work solely on that performance result.
|
||||||
|
Functional execution, experimental availability, quality and real-time
|
||||||
|
qualification are separate dimensions. Qualification belongs to a measured
|
||||||
|
profile/config/hardware/source/transport combination, not permanently to a
|
||||||
|
model name. More powerful Worker/onboard placement is a future retest target,
|
||||||
|
not a claim that existing latency or internal IPC disappears automatically.
|
||||||
|
The original budgets and failed measurements below remain unchanged. No slowed
|
||||||
|
source clock, hidden drops, stale-as-current evidence or actuation is authorized.
|
||||||
|
|
||||||
|
The manifest freezes an initial engineering candidate: p95/p99 full output age
|
||||||
|
≤125 ms, required-layer age ≤250 ms, release lag ≤25 ms, first incremental result
|
||||||
|
≤1 s after source admission, warmup ≤120 s, stop ≤5 s, VRAM ≤22000 MiB, RSS ≤8192
|
||||||
|
MiB. First/last-window backlog growth ≤25 ms and no capacity drops, failures,
|
||||||
|
expired selected frames or unaccounted observations. These are prototype targets,
|
||||||
|
not physical braking/safety limits or claims of achieved performance.
|
||||||
|
|
||||||
|
`ReplayMeasurements`/`realtime_failures` reject full-source preload, EOF-only
|
||||||
|
results, slowed replay, incomplete accounting, hidden missing layers and budget
|
||||||
|
violations. Declared source gaps must be verified from the input ledger; they
|
||||||
|
produce explicit degraded scenes and are not counted as fully fresh perception.
|
||||||
|
At least one fully evaluable scene is required. A component FPS figure cannot
|
||||||
|
populate this whole-path receipt. A quality comparison or successful export is
|
||||||
|
not a substitute for the real-time gate.
|
||||||
|
|
||||||
|
Every observation receives a terminal ledger outcome. Track ingress/release,
|
||||||
|
selection, decode, inference, completion, emission, drop/expiry/failure and source
|
||||||
|
gaps separately. Store startup separately from steady state; record payload bytes,
|
||||||
|
queue high-water marks, clock error, RSS/VRAM, image/weights/config/source/equipment
|
||||||
|
identities. Export and UI encoding cannot block inference through an unlimited
|
||||||
|
queue. A receiver-side render/receipt timestamp, not just Worker completion, ends
|
||||||
|
the end-to-end interval.
|
||||||
|
|
||||||
|
## Evidence and remaining stage-1 work
|
||||||
|
|
||||||
|
See `experiments/perception/PERCEPTION_STREAM_STAGE1_2026-09-01.md` for measured
|
||||||
|
component results, bounded validation, Worker maintenance and remaining gates.
|
||||||
|
Neither this ADR nor passing synthetic contract tests marks the new runtime ready.
|
||||||
@@ -0,0 +1,354 @@
|
|||||||
|
"""Stage-1, transport-neutral contract for stream-first perception.
|
||||||
|
|
||||||
|
These executable invariants do not start models, replace the legacy queue, or
|
||||||
|
claim that a stream transport exists. Replay and live must implement the same
|
||||||
|
contract in stage 2. Existing perception objects remain the domain vocabulary.
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import math
|
||||||
|
import re
|
||||||
|
from dataclasses import asdict, dataclass
|
||||||
|
from typing import Final, cast
|
||||||
|
|
||||||
|
STREAM_START_SCHEMA: Final = "missioncore.perception-stream-start/v1"
|
||||||
|
REALTIME_CONTRACT_SCHEMA: Final = "missioncore.perception-realtime-contract/v1"
|
||||||
|
REQUIRED_CHANNELS: Final = ("camera", "point-cloud", "pose")
|
||||||
|
REQUIRED_LAYERS: Final = ("segmentation", "objects", "geometry", "motion", "costmap", "policy")
|
||||||
|
_ID: Final = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,159}$")
|
||||||
|
_SHA: Final = re.compile(r"^[a-f0-9]{64}$")
|
||||||
|
|
||||||
|
|
||||||
|
class RealtimeContractError(ValueError):
|
||||||
|
"""The caller attempted an ambiguous, unbounded or non-causal contract."""
|
||||||
|
|
||||||
|
|
||||||
|
def _integer(value: object, name: str, *, minimum: int = 0) -> int:
|
||||||
|
if type(value) is not int or value < minimum:
|
||||||
|
raise RealtimeContractError(f"{name} must be an integer >= {minimum}")
|
||||||
|
return value
|
||||||
|
|
||||||
|
|
||||||
|
def _number(value: object, name: str, *, minimum: float = 0.0) -> float:
|
||||||
|
if type(value) not in (int, float):
|
||||||
|
raise RealtimeContractError(f"{name} must be a finite number")
|
||||||
|
number = float(cast(int | float, value))
|
||||||
|
if not math.isfinite(number) or number < minimum:
|
||||||
|
raise RealtimeContractError(f"{name} must be finite and >= {minimum}")
|
||||||
|
return number
|
||||||
|
|
||||||
|
|
||||||
|
def _identifier(value: object, name: str) -> None:
|
||||||
|
if not isinstance(value, str) or _ID.fullmatch(value) is None:
|
||||||
|
raise RealtimeContractError(f"{name} is invalid")
|
||||||
|
|
||||||
|
|
||||||
|
def _digest(value: object, name: str) -> None:
|
||||||
|
if not isinstance(value, str) or _SHA.fullmatch(value) is None:
|
||||||
|
raise RealtimeContractError(f"{name} must be a SHA-256 identity")
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True, slots=True)
|
||||||
|
class StreamStart:
|
||||||
|
"""Bounded handshake; deliberately no source duration, EOF or file inventory.
|
||||||
|
|
||||||
|
The epoch is reset on reconnect. Source hashes belong to chunk admission
|
||||||
|
and the asynchronous final receipt, not a full-file startup verification.
|
||||||
|
Calibration/config references resolve to bounded, authenticated metadata.
|
||||||
|
"""
|
||||||
|
|
||||||
|
run_id: str
|
||||||
|
source_id: str
|
||||||
|
worker_id: str
|
||||||
|
epoch_id: str
|
||||||
|
lease_generation: int
|
||||||
|
profile_sha256: str
|
||||||
|
image_sha256: str
|
||||||
|
effective_config_sha256: str
|
||||||
|
calibration_sha256: str
|
||||||
|
clock_domain_id: str
|
||||||
|
input_mode: str
|
||||||
|
channels: tuple[str, ...] = REQUIRED_CHANNELS
|
||||||
|
|
||||||
|
def __post_init__(self) -> None:
|
||||||
|
for name in ("run_id", "source_id", "worker_id", "epoch_id", "clock_domain_id"):
|
||||||
|
_identifier(getattr(self, name), name)
|
||||||
|
_integer(self.lease_generation, "lease_generation", minimum=1)
|
||||||
|
for name in (
|
||||||
|
"profile_sha256",
|
||||||
|
"image_sha256",
|
||||||
|
"effective_config_sha256",
|
||||||
|
"calibration_sha256",
|
||||||
|
):
|
||||||
|
_digest(getattr(self, name), name)
|
||||||
|
if self.input_mode not in ("recorded-source-paced", "live"):
|
||||||
|
raise RealtimeContractError("only source-paced replay and live are admitted")
|
||||||
|
if self.channels != REQUIRED_CHANNELS:
|
||||||
|
raise RealtimeContractError("the full profile requires camera, point-cloud and pose")
|
||||||
|
|
||||||
|
def to_dict(self) -> dict[str, object]:
|
||||||
|
value = asdict(self)
|
||||||
|
value["schema_version"] = STREAM_START_SCHEMA
|
||||||
|
value["channels"] = list(self.channels)
|
||||||
|
return value
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
def from_dict(cls, value: object) -> StreamStart:
|
||||||
|
if not isinstance(value, dict):
|
||||||
|
raise RealtimeContractError("stream start must be an object")
|
||||||
|
fields = set(cls.__dataclass_fields__)
|
||||||
|
if set(value) != fields | {"schema_version"}:
|
||||||
|
raise RealtimeContractError("stream start fields changed; full-source fields forbidden")
|
||||||
|
if value["schema_version"] != STREAM_START_SCHEMA:
|
||||||
|
raise RealtimeContractError("stream start schema changed")
|
||||||
|
if not isinstance(value["channels"], list):
|
||||||
|
raise RealtimeContractError("channels must be an array")
|
||||||
|
arguments = {name: value[name] for name in fields}
|
||||||
|
arguments["channels"] = tuple(value["channels"])
|
||||||
|
return cls(**arguments)
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True, slots=True)
|
||||||
|
class RealtimeBudgets:
|
||||||
|
"""Preregistered engineering limits, never vehicle-safety thresholds."""
|
||||||
|
|
||||||
|
maximum_start_metadata_bytes: int
|
||||||
|
maximum_chunk_bytes: int
|
||||||
|
maximum_inflight_bytes: int
|
||||||
|
maximum_pending_camera_frames: int
|
||||||
|
maximum_codec_preroll_ms: float
|
||||||
|
maximum_pose_age_ms: float
|
||||||
|
maximum_clock_uncertainty_ms: float
|
||||||
|
maximum_release_lag_ms: float
|
||||||
|
maximum_output_age_p95_ms: float
|
||||||
|
maximum_output_age_p99_ms: float
|
||||||
|
maximum_layer_age_ms: float
|
||||||
|
maximum_first_result_ms: float
|
||||||
|
maximum_warmup_seconds: float
|
||||||
|
maximum_stop_seconds: float
|
||||||
|
maximum_vram_mib: int
|
||||||
|
maximum_rss_mib: int
|
||||||
|
maximum_backlog_growth_ms: float
|
||||||
|
|
||||||
|
def __post_init__(self) -> None:
|
||||||
|
for name in (
|
||||||
|
"maximum_start_metadata_bytes",
|
||||||
|
"maximum_chunk_bytes",
|
||||||
|
"maximum_inflight_bytes",
|
||||||
|
"maximum_pending_camera_frames",
|
||||||
|
"maximum_vram_mib",
|
||||||
|
"maximum_rss_mib",
|
||||||
|
):
|
||||||
|
_integer(getattr(self, name), name, minimum=1)
|
||||||
|
for name in set(self.__dataclass_fields__) - {
|
||||||
|
"maximum_start_metadata_bytes",
|
||||||
|
"maximum_chunk_bytes",
|
||||||
|
"maximum_inflight_bytes",
|
||||||
|
"maximum_pending_camera_frames",
|
||||||
|
"maximum_vram_mib",
|
||||||
|
"maximum_rss_mib",
|
||||||
|
}:
|
||||||
|
_number(getattr(self, name), name, minimum=0.001)
|
||||||
|
if self.maximum_chunk_bytes > self.maximum_inflight_bytes:
|
||||||
|
raise RealtimeContractError("one chunk exceeds the inflight byte budget")
|
||||||
|
if not (
|
||||||
|
self.maximum_output_age_p95_ms
|
||||||
|
<= self.maximum_output_age_p99_ms
|
||||||
|
<= self.maximum_layer_age_ms
|
||||||
|
):
|
||||||
|
raise RealtimeContractError("output percentile and freshness budgets disagree")
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
def from_dict(cls, value: object) -> RealtimeBudgets:
|
||||||
|
if not isinstance(value, dict) or set(value) != set(cls.__dataclass_fields__):
|
||||||
|
raise RealtimeContractError("realtime budget fields changed")
|
||||||
|
return cls(**value)
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True, slots=True)
|
||||||
|
class LayerEvidence:
|
||||||
|
"""Freshness metadata wrapping existing domain payloads, not a new ontology.
|
||||||
|
|
||||||
|
source_time_ns is mapped into the run's common source timeline. It is not
|
||||||
|
a worker clock. A retained layer must keep its original timestamp/sequence.
|
||||||
|
Network end-to-end age is measured separately, with clock uncertainty.
|
||||||
|
"""
|
||||||
|
|
||||||
|
layer: str
|
||||||
|
epoch_id: str
|
||||||
|
source_sequence: int | None
|
||||||
|
source_time_ns: int | None
|
||||||
|
state: str
|
||||||
|
payload_sha256: str | None
|
||||||
|
|
||||||
|
def __post_init__(self) -> None:
|
||||||
|
if self.layer not in REQUIRED_LAYERS:
|
||||||
|
raise RealtimeContractError("unknown full-profile layer")
|
||||||
|
_identifier(self.epoch_id, "epoch_id")
|
||||||
|
if self.state not in ("current", "held", "stale", "unavailable"):
|
||||||
|
raise RealtimeContractError("unknown evidence currentness")
|
||||||
|
if self.state == "unavailable":
|
||||||
|
if any(
|
||||||
|
x is not None
|
||||||
|
for x in (self.source_sequence, self.source_time_ns, self.payload_sha256)
|
||||||
|
):
|
||||||
|
raise RealtimeContractError("unavailable evidence cannot claim a payload")
|
||||||
|
else:
|
||||||
|
_integer(self.source_sequence, "source_sequence")
|
||||||
|
_integer(self.source_time_ns, "source_time_ns")
|
||||||
|
_digest(self.payload_sha256, "payload_sha256")
|
||||||
|
|
||||||
|
|
||||||
|
def validate_scene_layers(
|
||||||
|
layers: tuple[LayerEvidence, ...],
|
||||||
|
*,
|
||||||
|
epoch_id: str,
|
||||||
|
source_time_ns: int,
|
||||||
|
maximum_layer_age_ms: float,
|
||||||
|
) -> None:
|
||||||
|
"""Reject missing layers, cross-epoch reuse, look-ahead and relabelled stale data.
|
||||||
|
|
||||||
|
Explicit unavailable/stale output remains valid evidence, not permission to
|
||||||
|
move. Deciding hard_surface/occupied precedence belongs to the existing
|
||||||
|
policy evaluator, whose results cannot grant actuation.
|
||||||
|
"""
|
||||||
|
_identifier(epoch_id, "epoch_id")
|
||||||
|
_integer(source_time_ns, "source_time_ns")
|
||||||
|
_number(maximum_layer_age_ms, "maximum_layer_age_ms", minimum=0.001)
|
||||||
|
if len(layers) != len(REQUIRED_LAYERS) or {x.layer for x in layers} != set(REQUIRED_LAYERS):
|
||||||
|
raise RealtimeContractError("a scene must account for every required layer exactly once")
|
||||||
|
for layer in layers:
|
||||||
|
if layer.epoch_id != epoch_id:
|
||||||
|
raise RealtimeContractError("layer belongs to another stream epoch")
|
||||||
|
if layer.source_time_ns is None:
|
||||||
|
continue
|
||||||
|
age_ns = source_time_ns - layer.source_time_ns
|
||||||
|
if age_ns < 0:
|
||||||
|
raise RealtimeContractError("future observations are not causal input")
|
||||||
|
if age_ns > maximum_layer_age_ms * 1_000_000 and layer.state in ("current", "held"):
|
||||||
|
raise RealtimeContractError("expired evidence cannot be current or held")
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True, slots=True)
|
||||||
|
class ReplayMeasurements:
|
||||||
|
"""Measured whole-path receipt; component timings alone cannot populate it.
|
||||||
|
|
||||||
|
All age figures include source release, transfer, decode, graph processing
|
||||||
|
and delivery to the application. The slowest required layer determines
|
||||||
|
full-scene age. Qualification is bound to identities by the caller.
|
||||||
|
"""
|
||||||
|
|
||||||
|
source_frames: int
|
||||||
|
declared_source_gap_frames: int
|
||||||
|
terminal_frames: int
|
||||||
|
fresh_complete_scenes: int
|
||||||
|
capacity_drops: int
|
||||||
|
expired_frames: int
|
||||||
|
failed_frames: int
|
||||||
|
unexpected_unavailable_layers: int
|
||||||
|
full_source_preloaded: bool
|
||||||
|
results_before_end_of_source: bool
|
||||||
|
replay_speed: float
|
||||||
|
maximum_release_lag_ms: float
|
||||||
|
output_age_p95_ms: float
|
||||||
|
output_age_p99_ms: float
|
||||||
|
maximum_layer_age_ms: float
|
||||||
|
first_result_ms: float
|
||||||
|
warmup_seconds: float
|
||||||
|
stop_seconds: float
|
||||||
|
peak_inflight_bytes: int
|
||||||
|
peak_pending_camera_frames: int
|
||||||
|
peak_vram_mib: int
|
||||||
|
peak_rss_mib: int
|
||||||
|
clock_uncertainty_ms: float
|
||||||
|
backlog_growth_ms: float
|
||||||
|
computed_layers: tuple[str, ...]
|
||||||
|
|
||||||
|
def __post_init__(self) -> None:
|
||||||
|
integer_fields = {
|
||||||
|
"source_frames",
|
||||||
|
"declared_source_gap_frames",
|
||||||
|
"terminal_frames",
|
||||||
|
"fresh_complete_scenes",
|
||||||
|
"capacity_drops",
|
||||||
|
"expired_frames",
|
||||||
|
"failed_frames",
|
||||||
|
"unexpected_unavailable_layers",
|
||||||
|
"peak_inflight_bytes",
|
||||||
|
"peak_pending_camera_frames",
|
||||||
|
"peak_vram_mib",
|
||||||
|
"peak_rss_mib",
|
||||||
|
}
|
||||||
|
boolean_fields = {"full_source_preloaded", "results_before_end_of_source"}
|
||||||
|
for name in integer_fields:
|
||||||
|
_integer(getattr(self, name), name)
|
||||||
|
for name in boolean_fields:
|
||||||
|
if type(getattr(self, name)) is not bool:
|
||||||
|
raise RealtimeContractError(f"{name} must be boolean")
|
||||||
|
for name in (
|
||||||
|
set(self.__dataclass_fields__) - integer_fields - boolean_fields - {"computed_layers"}
|
||||||
|
):
|
||||||
|
_number(getattr(self, name), name)
|
||||||
|
if (
|
||||||
|
self.source_frames == 0
|
||||||
|
or self.declared_source_gap_frames > self.source_frames
|
||||||
|
or self.fresh_complete_scenes > self.terminal_frames
|
||||||
|
):
|
||||||
|
raise RealtimeContractError("measurement frame counts are invalid")
|
||||||
|
if self.output_age_p95_ms > self.output_age_p99_ms:
|
||||||
|
raise RealtimeContractError("measurement percentiles are invalid")
|
||||||
|
if not isinstance(self.computed_layers, tuple) or any(
|
||||||
|
not isinstance(layer, str) for layer in self.computed_layers
|
||||||
|
):
|
||||||
|
raise RealtimeContractError("computed layers must be an immutable tuple of names")
|
||||||
|
if len(set(self.computed_layers)) != len(self.computed_layers):
|
||||||
|
raise RealtimeContractError("computed layers are duplicated")
|
||||||
|
|
||||||
|
|
||||||
|
def realtime_failures(value: ReplayMeasurements, limits: RealtimeBudgets) -> tuple[str, ...]:
|
||||||
|
"""Return every failed strict replay gate, not a product-ready flag.
|
||||||
|
|
||||||
|
First baseline is every source camera frame, no silent stride. A later
|
||||||
|
multirate profile needs its own explicit contract and measured qualification.
|
||||||
|
Source gaps are bound to the source ledger, never inferred from model
|
||||||
|
failures. They must still produce explicit degraded scenes and terminal
|
||||||
|
accounting; no complete fresh-scene claim is allowed for those frames.
|
||||||
|
"""
|
||||||
|
failures: list[str] = []
|
||||||
|
for failed, reason in (
|
||||||
|
(value.full_source_preloaded, "full-source-preload"),
|
||||||
|
(not value.results_before_end_of_source, "no-incremental-result"),
|
||||||
|
(value.replay_speed != 1.0, "source-clock-not-1x"),
|
||||||
|
(value.terminal_frames != value.source_frames, "incomplete-input-accounting"),
|
||||||
|
(
|
||||||
|
value.fresh_complete_scenes != value.source_frames - value.declared_source_gap_frames,
|
||||||
|
"incomplete-fresh-scenes",
|
||||||
|
),
|
||||||
|
(value.fresh_complete_scenes == 0, "no-evaluable-scene"),
|
||||||
|
(value.capacity_drops != 0, "capacity-drops"),
|
||||||
|
(value.expired_frames != 0, "expired-frames"),
|
||||||
|
(value.failed_frames != 0, "failed-frames"),
|
||||||
|
(value.unexpected_unavailable_layers != 0, "required-layer-unavailable"),
|
||||||
|
(set(value.computed_layers) != set(REQUIRED_LAYERS), "full-profile-not-computed"),
|
||||||
|
):
|
||||||
|
if failed:
|
||||||
|
failures.append(reason)
|
||||||
|
for measurement, budget in (
|
||||||
|
("maximum_release_lag_ms", "maximum_release_lag_ms"),
|
||||||
|
("output_age_p95_ms", "maximum_output_age_p95_ms"),
|
||||||
|
("output_age_p99_ms", "maximum_output_age_p99_ms"),
|
||||||
|
("maximum_layer_age_ms", "maximum_layer_age_ms"),
|
||||||
|
("first_result_ms", "maximum_first_result_ms"),
|
||||||
|
("warmup_seconds", "maximum_warmup_seconds"),
|
||||||
|
("stop_seconds", "maximum_stop_seconds"),
|
||||||
|
("peak_inflight_bytes", "maximum_inflight_bytes"),
|
||||||
|
("peak_pending_camera_frames", "maximum_pending_camera_frames"),
|
||||||
|
("peak_vram_mib", "maximum_vram_mib"),
|
||||||
|
("peak_rss_mib", "maximum_rss_mib"),
|
||||||
|
("clock_uncertainty_ms", "maximum_clock_uncertainty_ms"),
|
||||||
|
("backlog_growth_ms", "maximum_backlog_growth_ms"),
|
||||||
|
):
|
||||||
|
if getattr(value, measurement) > getattr(limits, budget):
|
||||||
|
failures.append(measurement)
|
||||||
|
return tuple(failures)
|
||||||
@@ -0,0 +1,278 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import hashlib
|
||||||
|
import json
|
||||||
|
from dataclasses import asdict, replace
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
import pytest
|
||||||
|
|
||||||
|
from k1link.compute.live_perception import LivePerceptionIngress
|
||||||
|
from k1link.perception.realtime_contract import (
|
||||||
|
REQUIRED_LAYERS,
|
||||||
|
LayerEvidence,
|
||||||
|
RealtimeBudgets,
|
||||||
|
RealtimeContractError,
|
||||||
|
ReplayMeasurements,
|
||||||
|
StreamStart,
|
||||||
|
realtime_failures,
|
||||||
|
validate_scene_layers,
|
||||||
|
)
|
||||||
|
|
||||||
|
ROOT = Path(__file__).resolve().parents[1]
|
||||||
|
PROFILE = ROOT / "config/perception/k1-perception-ddrnet39-rfdetr-tgs-prototype-v1.json"
|
||||||
|
|
||||||
|
|
||||||
|
def _profile() -> dict:
|
||||||
|
return json.loads(PROFILE.read_text())
|
||||||
|
|
||||||
|
|
||||||
|
def _budgets() -> RealtimeBudgets:
|
||||||
|
return RealtimeBudgets.from_dict(_profile()["realtime_contract"]["budgets"])
|
||||||
|
|
||||||
|
|
||||||
|
def _start() -> StreamStart:
|
||||||
|
return StreamStart(
|
||||||
|
run_id="run-1",
|
||||||
|
source_id="source-a",
|
||||||
|
worker_id="worker-006",
|
||||||
|
epoch_id="epoch-1",
|
||||||
|
lease_generation=1,
|
||||||
|
profile_sha256="a" * 64,
|
||||||
|
image_sha256="b" * 64,
|
||||||
|
effective_config_sha256="c" * 64,
|
||||||
|
calibration_sha256="d" * 64,
|
||||||
|
clock_domain_id="source-monotonic",
|
||||||
|
input_mode="recorded-source-paced",
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def _measurements() -> ReplayMeasurements:
|
||||||
|
return ReplayMeasurements(
|
||||||
|
source_frames=100,
|
||||||
|
declared_source_gap_frames=0,
|
||||||
|
terminal_frames=100,
|
||||||
|
fresh_complete_scenes=100,
|
||||||
|
capacity_drops=0,
|
||||||
|
expired_frames=0,
|
||||||
|
failed_frames=0,
|
||||||
|
unexpected_unavailable_layers=0,
|
||||||
|
full_source_preloaded=False,
|
||||||
|
results_before_end_of_source=True,
|
||||||
|
replay_speed=1.0,
|
||||||
|
maximum_release_lag_ms=10.0,
|
||||||
|
output_age_p95_ms=80.0,
|
||||||
|
output_age_p99_ms=100.0,
|
||||||
|
maximum_layer_age_ms=110.0,
|
||||||
|
first_result_ms=500.0,
|
||||||
|
warmup_seconds=20.0,
|
||||||
|
stop_seconds=1.0,
|
||||||
|
peak_inflight_bytes=2_000_000,
|
||||||
|
peak_pending_camera_frames=2,
|
||||||
|
peak_vram_mib=12000,
|
||||||
|
peak_rss_mib=4000,
|
||||||
|
clock_uncertainty_ms=1.0,
|
||||||
|
backlog_growth_ms=0.0,
|
||||||
|
computed_layers=REQUIRED_LAYERS,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def _layers() -> tuple[LayerEvidence, ...]:
|
||||||
|
return tuple(
|
||||||
|
LayerEvidence(name, "epoch-1", 0, 0, "current", "f" * 64) for name in REQUIRED_LAYERS
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def test_handshake_needs_no_source_size_duration_or_end() -> None:
|
||||||
|
value = _start()
|
||||||
|
assert StreamStart.from_dict(value.to_dict()) == value
|
||||||
|
assert len(json.dumps(value.to_dict()).encode()) < _budgets().maximum_start_metadata_bytes
|
||||||
|
assert replace(value, input_mode="live").channels == value.channels
|
||||||
|
assert replace(value, worker_id="worker-007").worker_id == "worker-007"
|
||||||
|
|
||||||
|
|
||||||
|
def test_existing_raw_first_ingress_delivers_without_session_end() -> None:
|
||||||
|
ingress = LivePerceptionIngress()
|
||||||
|
try:
|
||||||
|
ingress.begin_session("synthetic-source")
|
||||||
|
ingress.open_consumer("synthetic-worker")
|
||||||
|
assert ingress.take_next("synthetic-worker", timeout=0).modality == "control"
|
||||||
|
assert ingress.publish(
|
||||||
|
modality="camera-frame",
|
||||||
|
source_id="camera",
|
||||||
|
source_sequence=0,
|
||||||
|
captured_at_epoch_ns=1,
|
||||||
|
received_monotonic_ns=1,
|
||||||
|
payload=b"synthetic-frame",
|
||||||
|
)
|
||||||
|
event = ingress.take_next("synthetic-worker", timeout=0)
|
||||||
|
assert event is not None and event.payload == b"synthetic-frame"
|
||||||
|
assert ingress.snapshot()["active"] is True
|
||||||
|
finally:
|
||||||
|
ingress.close()
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.parametrize(
|
||||||
|
"field",
|
||||||
|
[
|
||||||
|
"total_bytes",
|
||||||
|
"frame_count",
|
||||||
|
"source_duration_ns",
|
||||||
|
"source_bundle_sha256",
|
||||||
|
"source_archive",
|
||||||
|
"source_members",
|
||||||
|
"wait_for_eof",
|
||||||
|
"command",
|
||||||
|
],
|
||||||
|
)
|
||||||
|
def test_full_recording_and_execution_fields_are_not_start_requirements(field: str) -> None:
|
||||||
|
value = _start().to_dict()
|
||||||
|
value[field] = "not-an-input-to-the-stream-handshake"
|
||||||
|
with pytest.raises(RealtimeContractError, match="fields"):
|
||||||
|
StreamStart.from_dict(value)
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.parametrize(
|
||||||
|
"change",
|
||||||
|
[
|
||||||
|
{"lease_generation": 0},
|
||||||
|
{"lease_generation": True},
|
||||||
|
{"epoch_id": ""},
|
||||||
|
{"image_sha256": "latest"},
|
||||||
|
{"input_mode": "offline-batch"},
|
||||||
|
{"channels": ("camera",)},
|
||||||
|
{"calibration_sha256": None},
|
||||||
|
],
|
||||||
|
)
|
||||||
|
def test_invalid_handshakes_fail_closed(change: dict) -> None:
|
||||||
|
with pytest.raises(RealtimeContractError):
|
||||||
|
replace(_start(), **change)
|
||||||
|
|
||||||
|
|
||||||
|
def test_scene_reports_all_layers_before_any_end_marker_exists() -> None:
|
||||||
|
validate_scene_layers(_layers(), epoch_id="epoch-1", source_time_ns=0, maximum_layer_age_ms=250)
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.parametrize("layers", [_layers()[:-1], _layers()[:-1] + (_layers()[0],)])
|
||||||
|
def test_missing_or_duplicate_layer_is_not_a_complete_profile(layers: tuple) -> None:
|
||||||
|
with pytest.raises(RealtimeContractError, match="exactly once"):
|
||||||
|
validate_scene_layers(
|
||||||
|
layers, epoch_id="epoch-1", source_time_ns=0, maximum_layer_age_ms=250
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.parametrize(
|
||||||
|
"change,reason",
|
||||||
|
[
|
||||||
|
({"epoch_id": "epoch-old"}, "another stream epoch"),
|
||||||
|
({"source_time_ns": 2_000_000_000}, "future"),
|
||||||
|
({"source_time_ns": 0, "state": "held"}, "expired"),
|
||||||
|
],
|
||||||
|
)
|
||||||
|
def test_cross_epoch_future_and_expired_evidence_rejected(change: dict, reason: str) -> None:
|
||||||
|
layers = tuple(replace(x, source_time_ns=1_000_000_000) for x in _layers())
|
||||||
|
layers = (replace(layers[0], **change),) + layers[1:]
|
||||||
|
with pytest.raises(RealtimeContractError, match=reason):
|
||||||
|
validate_scene_layers(
|
||||||
|
layers, epoch_id="epoch-1", source_time_ns=1_000_000_000, maximum_layer_age_ms=250
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def test_explicit_missing_lidar_does_not_invent_geometry_or_distance() -> None:
|
||||||
|
missing = LayerEvidence("geometry", "epoch-1", None, None, "unavailable", None)
|
||||||
|
layers = tuple(missing if x.layer == "geometry" else x for x in _layers())
|
||||||
|
validate_scene_layers(layers, epoch_id="epoch-1", source_time_ns=0, maximum_layer_age_ms=250)
|
||||||
|
with pytest.raises(RealtimeContractError, match="cannot claim"):
|
||||||
|
replace(missing, payload_sha256="e" * 64)
|
||||||
|
|
||||||
|
|
||||||
|
def test_synthetic_receipt_passes_only_whole_path_limits() -> None:
|
||||||
|
assert realtime_failures(_measurements(), _budgets()) == ()
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.parametrize(
|
||||||
|
"change,reason",
|
||||||
|
[
|
||||||
|
({"full_source_preloaded": True}, "full-source-preload"),
|
||||||
|
({"results_before_end_of_source": False}, "no-incremental-result"),
|
||||||
|
({"replay_speed": 0.5}, "source-clock-not-1x"),
|
||||||
|
({"terminal_frames": 101}, "incomplete-input-accounting"),
|
||||||
|
({"fresh_complete_scenes": 50}, "incomplete-fresh-scenes"),
|
||||||
|
({"capacity_drops": 1}, "capacity-drops"),
|
||||||
|
({"expired_frames": 1}, "expired-frames"),
|
||||||
|
({"failed_frames": 1}, "failed-frames"),
|
||||||
|
({"unexpected_unavailable_layers": 1}, "required-layer-unavailable"),
|
||||||
|
({"computed_layers": ("segmentation",)}, "full-profile-not-computed"),
|
||||||
|
({"peak_pending_camera_frames": 3}, "peak_pending_camera_frames"),
|
||||||
|
({"peak_inflight_bytes": 20_000_000}, "peak_inflight_bytes"),
|
||||||
|
({"clock_uncertainty_ms": 6}, "clock_uncertainty_ms"),
|
||||||
|
({"backlog_growth_ms": 30}, "backlog_growth_ms"),
|
||||||
|
({"output_age_p99_ms": 130}, "output_age_p99_ms"),
|
||||||
|
({"maximum_layer_age_ms": 300}, "maximum_layer_age_ms"),
|
||||||
|
({"warmup_seconds": 121}, "warmup_seconds"),
|
||||||
|
({"stop_seconds": 6}, "stop_seconds"),
|
||||||
|
],
|
||||||
|
)
|
||||||
|
def test_fast_model_or_complete_archive_does_not_pass_realtime(change: dict, reason: str) -> None:
|
||||||
|
assert reason in realtime_failures(replace(_measurements(), **change), _budgets())
|
||||||
|
|
||||||
|
|
||||||
|
def test_source_gaps_stay_visible_and_are_not_model_capacity_drops() -> None:
|
||||||
|
value = replace(_measurements(), declared_source_gap_frames=10, fresh_complete_scenes=90)
|
||||||
|
assert realtime_failures(value, _budgets()) == ()
|
||||||
|
assert "incomplete-fresh-scenes" in realtime_failures(
|
||||||
|
replace(value, fresh_complete_scenes=100), _budgets()
|
||||||
|
)
|
||||||
|
assert "no-evaluable-scene" in realtime_failures(
|
||||||
|
replace(value, declared_source_gap_frames=100, fresh_complete_scenes=0), _budgets()
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.parametrize(
|
||||||
|
"change",
|
||||||
|
[
|
||||||
|
{"output_age_p99_ms": float("nan")},
|
||||||
|
{"clock_uncertainty_ms": float("inf")},
|
||||||
|
{"peak_vram_mib": -1},
|
||||||
|
{"source_frames": True},
|
||||||
|
{"full_source_preloaded": 0},
|
||||||
|
],
|
||||||
|
)
|
||||||
|
def test_non_finite_or_ambiguous_measurements_rejected(change: dict) -> None:
|
||||||
|
with pytest.raises(RealtimeContractError):
|
||||||
|
replace(_measurements(), **change)
|
||||||
|
|
||||||
|
|
||||||
|
def test_budget_schema_rejects_silent_fields_and_inconsistent_limits() -> None:
|
||||||
|
with pytest.raises(RealtimeContractError):
|
||||||
|
RealtimeBudgets.from_dict({**asdict(_budgets()), "allow_full_download": True})
|
||||||
|
with pytest.raises(RealtimeContractError):
|
||||||
|
replace(_budgets(), maximum_chunk_bytes=100_000_000)
|
||||||
|
|
||||||
|
|
||||||
|
def test_profile_pins_reused_assets_without_installing_a_fake_ready_executor() -> None:
|
||||||
|
profile = _profile()
|
||||||
|
assert profile["packaging"]["image_sha256"] is None
|
||||||
|
assert set(profile["components"]) == set(REQUIRED_LAYERS)
|
||||||
|
assert profile["stream_policy"]["inference_stride"] == 1
|
||||||
|
assert profile["input_contract"]["full_source_transfer_required"] is False
|
||||||
|
assert profile["authority"]["actuation_allowed"] is False
|
||||||
|
assert profile["components"]["geometry"]["generic_static_class"] == "static.unknown"
|
||||||
|
assert (
|
||||||
|
profile["components"]["policy"]["fine_road_sidewalk_bikeway_distinction_required"] is False
|
||||||
|
)
|
||||||
|
for ref in profile["reference_files"]:
|
||||||
|
assert hashlib.sha256((ROOT / ref["path"]).read_bytes()).hexdigest() == ref["sha256"]
|
||||||
|
registry = (ROOT / "config/observatory-portable-run-definitions.json").read_text()
|
||||||
|
assert profile["profile_id"] not in registry
|
||||||
|
|
||||||
|
|
||||||
|
def test_experimental_overload_does_not_become_realtime_qualification() -> None:
|
||||||
|
policy = _profile()["experiment_policy"]
|
||||||
|
assert policy["bounded_lab_overload_allowed"] is True
|
||||||
|
assert policy["retain_profiles_that_fail_current_hardware_realtime"] is True
|
||||||
|
assert policy["realtime_failure_blocks_experimental_packaging"] is False
|
||||||
|
assert policy["overload_is_realtime_pass"] is False
|
||||||
|
measurements = replace(_measurements(), output_age_p95_ms=150.0, output_age_p99_ms=200.0)
|
||||||
|
failures = realtime_failures(measurements, _budgets())
|
||||||
|
assert "output_age_p95_ms" in failures and "output_age_p99_ms" in failures
|
||||||
Reference in New Issue
Block a user