EvidenceResolver(receipts_dir, session_root=None, task_id=None) is the provider-independent receipt API. register(path, selection=None, task_id=None, source_artifact_id=None) writes the historical flightops.evidence-receipt/1 file and returns the same digest-bound receipt. restore(receipt_id) reopens the exact original and recomputes the derived facts; verify(artifact_id) checks its bound bytes; retrieve(request) reads a 32 KiB byte/line range or one bounded JSON pointer. Missing, changed, symlinked, or oversized originals are refused. Receipt creation stays under the existing session quota and pins referenced captures. ai.evidence.Evidence(store) is a compatibility constructor only; no provider or model is needed to use the Standard resolver. A historical receipt proves neither current availability nor current source-use permission.
select_recording(catalog_path, *, segment_id, topic, start_ns, end_ns, authorize, use='retain', field=None, reduction=None, unit=None, max_messages=10000, max_samples=0) selects one half-open MCAP log-time window. authorize(source_artifact_id, use) -> bool is the caller's current policy decision; it is required for each direct and upstream source and for retention even when another use is requested. The selector also checks the latest immutable source-use records, including upstream derivation links. Historical managed-recorder policy does not authorize inspection, inference, sharing, or training by itself.
Only a finalized segment with catalogued or restored availability and a resolved path can be selected. Its complete bytes are copied from a held descriptor into a bounded private snapshot while hashing against the catalog digest. The indexed query reads that snapshot, so a source path swapped during the query cannot substitute another bag. Snapshot bytes, original file identity, and policy are rechecked afterward. Active, interrupted, excluded, missing, and changed sources return an explicit evidence_state and no query window. Missing or denied permission is separate as permission_state='unknown' or 'denied'; bytes remain evidence_state='unverified' if policy stops the read. Restored segments never fall back to their original path. The selector holds a retention read lease (purpose selection) on the segment while it copies and queries it, so retention expiry cannot remove the bytes during the read; see recording retention.
A successful result has schema flightops.recording-selection/1, separate evidence_state='resolved', permission_state='allowed', and window fields, the segment ID and full SHA, source-use policy IDs, requested use, MCAP log-time basis, and omissions. An empty query window is an observation about the selected interval, not missing evidence. Numeric field decoding follows the embedded ros2msg schema; unsupported encodings or fields are explicit query refusals. No sensor-to-application clock relationship is inferred. Selection has a 512 MiB source cap, 20-second streaming digest cap per pass, 25-second disposable query process cap, a 128 MiB free-space reserve above the snapshot size, and Splashdown's 300-second window, 10,000-message, 200-sample, 64 MiB read, and 192 KiB output limits. It does not persist a derivative or send data to a model.
Public Standard commands
flightops evidence register FILE --task-id TASKcreates a receipt for the selected file.flightops evidence verify RECEIPT_IDverifies the original bytes again.flightops evidence read RECEIPT_ID --kind json --pointer /fieldreads an exact JSON field. Use--kind lines|bytes --start N --end Nfor a half-open range.flightops evidence recording SEGMENT_ID --topic /topic --start-ns N --end-ns N --allow-source recording-segment:SEGMENT_IDselects a finalized recording interval. Each upstream source needs its own--allow-source IDas well as current catalog retention permission.
Use --receipts DIRECTORY before the subcommand to select a receipt store, or recording --database PATH for a catalog. The public recording command only requests local retention use; it grants neither inference nor sharing. Permission, evidence availability and the query's findings are separate result fields.
For line reads, the current source command prints readable text before range and digest metadata. Add --json to retain the structured response, including the exact bytes as base64. The terminal display strips control sequences; the receipt's stored bytes remain unchanged.