bioxpClient.ts

import { useEffect, useRef, useState } from 'react';
import { useMutation, useQuery, useQueryClient, skipToken, type QueryClient } from '@tanstack/react-query';

import { api } from './api.js';
import { bioXpProviderFailure } from './bioxpEvidencePresentation';
import { bioXpErrorBodyPreview, boundedBioXpText as boundedOperatorText } from './bioxpErrorPreview';

export interface BioXpConnectionSnapshot {
    configured: boolean;
    active: boolean;
    generation: number;
    target_url: string | null;
    reachable: boolean | null;
    runtime_ready: boolean | null;
    hardware_ready: boolean | null;
    hardware_observed_at: string | null;
    hardware_fresh: boolean | null;
    hardware_stale: boolean;
    hardware_evidence_error: string | null;
    capabilities: string[];
    observed_at: string | null;
    freshness_budget_seconds: number | null;
    fresh: boolean | null;
    last_error: string | null;
    maintenance_state: BioXpMaintenanceState | null;
    ownership: BioXpOwnership | null;
}

export interface BioXpOwnership {
    transport?: string | null;
    usb?: string | null;
    router?: string | null;
    camera?: string | null;
}

export interface BioXpMaintenanceState {
    motion_blocked?: boolean | null;
    recovery_required?: boolean | null;
    usb_owner?: string | null;
    blocked_by?: string | null;
    block_reason?: string | null;
    block_source?: string | null;
    recovery_hint?: string | null;
    blocked_at?: string | null;
    recovered_at?: string | null;
    last_recovery?: Record<string, unknown> | null;
}

export interface BioXpStatusResponse {
    connection: BioXpConnectionSnapshot;
    startup_warnings: string[];
    connection_access?: {
        enabled: boolean;
        server_setting: string;
        hardware_effects_authorized: false;
    };
    mutation_access?: {
        enabled: boolean;
        server_setting: string;
        secret_required: false;
    };
    legacy_job_migration: {
        migrated: number;
        quarantined: number;
    };
}

export interface BioXpCameraStatus {
    schema_version: 'bioxp.camera_status.v1';
    state: 'live' | 'stale' | 'unavailable';
    available: boolean;
    frame_sequence: number | null;
    frame_captured_at: string | null;
    frame_age_seconds: number | null;
    freshness_budget_seconds: number;
    provider_generation: number;
    dropped_frames: number;
    content_sha256: string | null;
    detail: string | null;
    connection_generation: number;
}

export interface BioXpCameraImage {
    blob: Blob;
    etag: string;
    sha256: string;
    connectionGeneration: number;
}

export type BioXpIlluminationChannel = 1 | 2 | 3;
export interface BioXpCameraIllumination {
    schema_version: 'bioxp.camera_illumination.v1';
    provider_generation: number;
    connection_generation: number;
    channels: { channel: BioXpIlluminationChannel; on: boolean | null }[];
    state_source: 'last_successful_command';
    physical_effect_verified: false;
}
export interface BioXpCameraIlluminationCommand extends BioXpCameraIllumination {
    ok: true;
    channel: BioXpIlluminationChannel;
    on: boolean;
    delivery_attempted: true;
}

export interface BioXpCameraRgbResult {
    ok: boolean;
    rgb: [number, number, number];
    tmcl: [number, number, number];
    acks: Record<'r' | 'g' | 'b', Record<string, unknown> | null>;
    sent: number;
    elapsed_ms: number;
    connection_generation: number;
}

export async function setBioXpCameraRgb(generation: number, rgb: readonly [number, number, number]): Promise<BioXpCameraRgbResult> {
    return (await api.post<BioXpCameraRgbResult>('/api/bioxp/camera/rgb', {
        expected_connection_generation: generation, r: rgb[0], g: rgb[1], b: rgb[2],
    })).data;
}

export async function getBioXpCameraIllumination(generation: number): Promise<BioXpCameraIllumination> {
    return (await api.get<BioXpCameraIllumination>('/api/bioxp/camera/illumination/state', {
        params: { expected_generation: generation },
    })).data;
}

export async function setBioXpCameraIllumination(
    generation: number, channel: BioXpIlluminationChannel, on: boolean,
): Promise<BioXpCameraIlluminationCommand> {
    return (await api.post<BioXpCameraIlluminationCommand>('/api/bioxp/camera/illumination', {
        expected_generation: generation, channel, on,
    })).data;
}

export interface BioXpCameraStream {
    schema_version: 'bioxp.camera_stream.v1';
    state: 'off' | 'starting' | 'live' | 'error';
    active: boolean;
    stream_id: string | null;
    camera_ownership_epoch: number;
    fps: number | null;
    quality: number | null;
    width: number | null;
    height: number | null;
    frames_emitted: number;
    dropped_frames: number;
    latest_frame_at: string | null;
    last_error: string | null;
    idempotent: boolean | null;
    connection_generation: number;
}

export const BIOXP_CAMERA_ENDPOINTS = Object.freeze({
    status: '/api/bioxp/camera/status',
    latest: '/api/bioxp/camera/frame/latest',
    snapshot: '/api/bioxp/camera/snapshot',
    streamStart: '/api/bioxp/camera/stream/start',
    streamState: '/api/bioxp/camera/stream/state',
    mjpeg: '/api/bioxp/camera/mjpeg',
    streamStop: '/api/bioxp/camera/stream/stop',
});


export type BioXpOperatorActionKind = 'primitive' | 'meta';
export type BioXpOperatorSafetyClass = 'read_only' | 'service' | 'motion' | 'stop' | 'emergency';

export interface BioXpOperatorDependency {
    key: string;
    label: string;
    met: boolean;
    reason: string | null;
}

export interface BioXpOperatorDashboardAxis {
    axis: string;
    reference: string;
    position_steps: number | null;
    position_reply_valid?: boolean | null;
    position_source?: string | null;
    position_observed_at?: number | null;
    speed_steps_s: number | null;
    run_current: number | null;
    standby_current: number | null;
    left_switch_state: number | null;
    right_switch_state: number | null;
    left_switch_raw_active: boolean | null;
    right_switch_raw_active: boolean | null;
    left_switch_active: boolean | null;
    right_switch_active: boolean | null;
    left_switch_disabled: boolean | null;
    right_switch_disabled: boolean | null;
    coordinate_contract: string | null;
    min_steps: number | null;
    max_steps: number | null;
    motor_temperature_c: number | null;
    motor_temperature_available: boolean;
    telemetry_authority?: string | null;
    physical_position_verified?: false | null;
}

export interface BioXpOperatorDashboardXPreparationAttempt {
    ok: boolean;
    observed_generation: number;
    board_lifecycle_generation: number | null;
    board_preparation_verified: boolean;
    initialize_without_motion_verified: boolean;
    board_lifecycle_reused?: boolean;
    physical_motion: false;
    motor_output_state: 'unknown';
    motor_torque_verified: false;
    receipt: BioXpJsonValue;
    axis: 'x';
    source_method?: 'ClassControlInterface.initializeMotorsWithoutMotion' | null;
    reference_state?: 'desynced' | null;
    source_anchor: 'ClassControlInterface.initializeMotorsWithoutMotion:3187-3195';
    source_exact: false;
    initializer_source_exact: true;
    literal_switch_mask_writes: [];
}

export interface BioXpOperatorDashboardXPreparationRejection {
    ok: false;
    observed_generation: number;
    physical_motion: false;
    blocker: 'ownership_generation_changed_before_preparation';
    axis: 'x';
    source_method?: 'ClassControlInterface.initializeMotorsWithoutMotion' | null;
    reference_state?: 'desynced' | null;
    source_anchor: 'ClassControlInterface.initializeMotorsWithoutMotion:3187-3195';
    source_exact: false;
    initializer_source_exact: true;
    literal_switch_mask_writes: [];
}

export interface BioXpOperatorDashboardXAxis {
    status: BioXpOperatorDashboardAxis | null;
    provider: {
        authority?: string | null;
        state?: string;
        reference_state?: string;
        source_min_steps?: number | null;
        source_max_steps?: number | null;
        effective_absolute_min_steps?: number | null;
        relative_limit_margin_steps?: number | null;
        current_generation?: number | null;
        current_board_lifecycle_generation?: number | null;
        board_generation_fresh?: boolean | null;
        lifecycle?: {
            state?: string;
            reference_state?: string;
            generation?: number | null;
            board_lifecycle_generation?: number | null;
            prepared_receipt?: BioXpOperatorDashboardXPreparationAttempt | BioXpOperatorDashboardXPreparationRejection | null;
            awaiting_observation_receipt_id?: string | null;
            last_failure?: unknown;
            latest_receipt?: Record<string, unknown> | null;
        };
        live_status?: {
            position_steps?: number | null;
            speed_steps_s?: number | null;
            max_speed?: number | null;
            max_acceleration?: number | null;
            max_current?: number | null;
            stall_guard?: number | null;
            left_switch_state?: number | null;
            right_switch_state?: number | null;
            left_switch_disabled?: boolean | null;
            right_switch_disabled?: boolean | null;
            profile_verified?: boolean;
            switch_mask_verified?: boolean | null;
            switch_mask_tuple?: Record<string, number | null>;
            switch_mask_policy?: 'observed_only_oem_source_omits_x_writes';
        };
        profile?: { verified?: boolean };
        switch_masks?: {
            expected?: Record<string, number>;
            verified?: boolean | null;
            observed?: Record<string, number | null> | null;
            policy?: 'observed_only_oem_source_omits_x_writes';
        };
        bound: boolean;
        physical_position_verified: false;
    };
    snapshot_freshness: Record<string, unknown>;
    last_failure: unknown;
    latest_receipt: Record<string, unknown> | null;
    authority: string;
    physical_position_verified: false;
}

export interface BioXpOperatorSuccessiveMoveQueueAxis {
    active_command_id: string | null;
    depth: number;
    head_action_id: string | null;
    state: 'running' | 'queued' | 'idle';
}

export interface BioXpOperatorDashboard {
    schema_version: 'bioxp.operator_dashboard.v1';
    ownership_generation: number;
    connection: { live: boolean; ownership: Record<string, unknown> };
    motion: { enabled: boolean; reason: string | null };
    operation: { state: string | null; reason: string | null };
    enclosure: { door_closed: boolean | null; latch_closed: boolean | null };
    axes: BioXpOperatorDashboardAxis[];
    x_axis: BioXpOperatorDashboardXAxis | null;
    z_axis: {
        status: BioXpOperatorDashboardAxis | null;
        provider: {
            bound?: boolean;
            current_minimum_steps?: 500 | 65000 | null;
            target_preview?: { requested_position_steps: number; effective_position_steps: number | null } | null;
            board?: 4;
            motor?: 1;
            state?: string;
            expected_startup_stage?: string | null;
            startup_terminal_state?: string | null;
            switch_mask_policy?: 'observed_only_oem_source_omits_z_writes' | null;
            switch_mask_tuple?: Record<'12' | '13', number | null> | null;
            terminal_state?: {
                switch_mask_policy?: 'observed_only_oem_source_omits_z_writes' | null;
                switch_mask_tuple?: Record<'12' | '13', number | null> | null;
                position_steps?: number | null;
                speed_steps_s?: number | null;
            } | null;
            reference_state?: string;
            awaiting_observation_receipt_id?: string | null;
            last_failure?: unknown;
        };
        snapshot_freshness: Record<string, unknown>;
        last_failure: unknown;
        authority: string;
    } | null;
    temperatures: Array<{ sensor: string; label: string; unit: '°C'; temperature_c: number | null; available: boolean }>;
    pipettes: BioXpPipettes | null;
    snapshot: { snapshot_id: string | null; freshness: { state?: string; age_s?: number | null; fresh_for_s?: number | null }; collection_triggered: false; observed_at?: number | null; domain_observed_at?: Record<string, number | null>; clock_skew_detected?: boolean };
    successive_move_queue: Record<string, BioXpOperatorSuccessiveMoveQueueAxis>;
}

export type BioXpOperatorReceiptV2Status =
    | 'queued'
    | 'dispatched'
    | 'issued_pending'
    | 'interrupting'
    | 'completed'
    | 'failed'
    | 'cleared'
    | 'interrupted'
    | 'ambiguous'
    | 'rejected'
    | 'stopped'
    | 'aborted'
    | 'cancelled';

export interface BioXpOperatorReceiptFailureDetailV2 {
    provider_failure: string;
    failure: string;
    axis: string;
    board: number;
    motor: number;
    source_return_code: number;
    controller_acknowledged: boolean;
    controller_terminal_state_verified: boolean;
    physical_effect_verified: boolean;
    lifecycle_state: string;
    reference_state: string;
}

export type BioXpJsonValue = null | boolean | number | string | BioXpJsonValue[] | { [key: string]: BioXpJsonValue };

export interface BioXpOperatorInterruptEvidenceV2 {
    source_call_completed: boolean | null;
    source_return_ok: boolean | null;
    first_stop_acknowledged?: boolean | null;
    second_stop_acknowledged?: boolean | null;
    controller_stop_acknowledged: boolean | null;
    controller_terminal_state_verified: boolean | null;
    physical_effect_verified: false;
    persistence_state: string;
    details: BioXpJsonValue;
}

export interface BioXpOperatorReceiptV2 {
    xy_failure?: Record<string, BioXpJsonValue> | null;
    z_move?: { requested_position_steps?: number | null; effective_position_steps?: number | null; before_position_steps?: number | null; after_position_steps?: number | null; target_clamped?: boolean | null; [key: string]: unknown } | null;
    schema_version: 'bioxp.operator_action_receipt.v2';
    interrupt_evidence?: BioXpOperatorInterruptEvidenceV2 | null;
    command_id: string;
    action_id: string;
    status: BioXpOperatorReceiptV2Status;
    terminal: boolean;
    sequence: number;
    method_id: string | null;
    ownership_generation: number;
    expected_board_epoch_by_board: Record<string, number>;
    state_version: number;
    status_path: string;
    accepted_at: number;
    queued_at: number;
    dispatched_at: number | null;
    finished_at: number | null;
    terminal_receipt_id: string | null;
    completion_class: string | null;
    physical_effect_verified: boolean;
    error: {
        code: string;
        message: string;
        retryable: boolean;
        detail?: BioXpOperatorReceiptFailureDetailV2 | null;
    } | null;
}

export type BioXpReceiptScalarV2 = number | string | boolean | null;

export interface BioXpOperatorReceiptDetailV2 extends BioXpOperatorReceiptV2 {
    source_receipt?: Record<string, unknown> | null;
    canonical_inputs: Record<string, unknown>;
    requested_values: Record<string, BioXpReceiptScalarV2>;
    effective_values: Record<string, BioXpReceiptScalarV2>;
    observed_values: Record<string, BioXpReceiptScalarV2>;
    raw_return_layers: Record<string, unknown>;
    controller_evidence: Record<string, unknown>;
    transport_artifacts: Array<{ sha256: string; path: string; bytes: number }>;
    child_receipts: BioXpOperatorReceiptV2[];
    transitions: Array<{
        transition_id: string;
        from_status: BioXpOperatorReceiptV2Status | null;
        to_status: BioXpOperatorReceiptV2Status | 'reconciled';
        at: number;
        reason: string | null;
    }>;
    deck_movement?: {
        target: string;
        target_label: string | null;
        source_branch: string | null;
        resolved_location_id: number | null;
        destination_catalog_revision: string | null;
        position_table_revision: string | null;
        authority_snapshot_digest: string | null;
        complete_authority_digest: string | null;
        plan_digest: string | null;
        source_anchors: string[];
        delivery_attempted: boolean | null;
        controller_command_acknowledged: boolean | null;
        controller_completion_verified: boolean | null;
        hardware_postcondition_verified: boolean | null;
        semantic_state_committed: boolean | null;
        physical_observation_verified: boolean | null;
        recovery_resolution?: {
            command_id: string;
            decision_id: string;
            semantic_state_revision: number;
            transition_sequence: number;
        } | null;
        transition_revision: number | null;
        ambiguity_state: 'none' | 'failed' | 'ambiguous' | 'recovery_required' | null;
        stages: Array<{
            order: number;
            operation: string;
            source_anchor: string;
            resources: string[];
            arguments: Record<string, unknown>;
            dependencies: number[];
            terminal_state: 'planned' | 'completed' | 'failed' | 'ambiguous' | 'stopped' | 'aborted';
            terminal_evidence: unknown | null;
        }>;
    } | null;
}

export interface BioXpYAxisV2 {
    axis: 'y';
    board_id: 4;
    motor_id: 0;
    ownership_generation: number;
    prior_board_epoch: number | null;
    active_board_epoch: number | null;
    prepared_board_epoch: number | null;
    lifecycle_state: 'unbound' | 'unprepared' | 'prepared_unreferenced' | 'referenced_ready' | 'generation_stale' | 'reconciliation_required' | 'faulted';
    reference_state: 'unreferenced' | 'referenced' | 'generation_stale' | 'reconciliation_required';
    position_steps: number | null;
    position_reply_valid?: boolean | null;
    position_source?: string | null;
    position_observed_at?: number | null;
    origin_position_steps?: number | null;
    requested_position_steps?: number | null;
    position_status_code: number | null;
    speed_steps_s: number | null;
    speed_reply_valid?: boolean | null;
    speed_status_code: number | null;
    left_switch_raw: number | null;
    left_switch_reply_valid?: boolean | null;
    left_switch_status_code: number | null;
    home_effective: boolean | null;
    profile_fingerprint: string | null;
    profile_readback_valid?: boolean | null;
    profile_mismatches: string[];
    active_command: BioXpOperatorReceiptV2 | null;
    interrupt_epoch: number;
    latest_compact_receipt: BioXpOperatorReceiptV2 | null;
    last_discrepancy_steps: number | null;
    state_version: number;
    updated_at: number;
    physical_position_verified: boolean;
}

export interface BioXpBoard4AuthorityV2 {
    state: 'unknown' | 'inactive' | 'transitioning' | 'active' | 'faulted';
    prior_board_epoch: number | null;
    active_board_epoch: number | null;
    transition_phase: string;
    transition_evidence: Record<string, unknown>;
    member_motors: Record<string, number>;
    state_version: number;
    updated_at: number;
}

export interface BioXpOperatorQueueItemV2 {
    command_id: string;
    sequence: number;
    status: Extract<BioXpOperatorReceiptV2Status, 'queued' | 'dispatched' | 'issued_pending' | 'interrupting'>;
    method_id: string | null;
    resource_keys: string[];
    accepted_at: number;
}

export interface BioXpOperatorCommandQueueV2 {
    schema_version: 'bioxp.oem_command_queue.v1';
    generated_at: number;
    items: BioXpOperatorQueueItemV2[];
}

export interface BioXpOperatorActionHistory {
    schema_version: 'bioxp.operator_action_history.v2';
    items: BioXpOperatorHistoryReceipt[];
    next_cursor: string | null;
    limit: number;
}

export interface BioXpDeckHeadAlignment {
    tip_location: number | null;
    semantic_state_revision: number;
    producer_operation: string | null;
    producer_command_id: string | null;
    ownership_generation: number | null;
}

export interface BioXpOperatorDashboardV2 {
    schema_version: 'bioxp.operator_dashboard.v2';
    generated_at: number;
    ownership_generation: number;
    board4: BioXpBoard4AuthorityV2;
    y_axis: BioXpYAxisV2;
    active_commands: BioXpOperatorReceiptV2[];
    command_queue?: BioXpOperatorCommandQueueV2 | null;
    latest_receipts: BioXpOperatorReceiptV2[];
    telemetry: BioXpOperatorDashboard | null;
    deck?: {
        head_alignment?: BioXpDeckHeadAlignment | null;
        current_location: string | null;
        current_well: number | null;
        position_table_revision: string | null;
        destination_catalog_revision: string | null;
        semantic_state_revision: number;
        ambiguity_state: 'none' | 'ambiguous' | 'recovery_required';
    } | null;
}

export interface BioXpDeckDestinationV1 {
    target: string;
    label: string;
    aliases: string[];
    location_id: number;
    branch_kind: 'ordinary' | 'barcode' | 'park';
    camera_offset_option: boolean;
    source_anchors: string[];
    enabled: boolean;
    disabled_reason: string | null;
}

export interface BioXpOperatorControlCatalogV2 {
    schema_version: 'bioxp.operator_control_catalog.v2';
    dashboard: BioXpOperatorDashboardV2;
    actions: Array<{
        action_id: string;
        request_schema_version: 'bioxp.operator_action_request.v2' | 'bioxp.operator_interrupt_request.v1';
        response_schema_version: 'bioxp.operator_action_receipt.v2';
        interrupt: boolean;
        enabled: boolean;
        disabled_reason: string | null;
        destination_catalog_revision?: string | null;
        position_table_revision?: string | null;
        required_boards?: Array<4 | 5> | null;
        expected_board_epoch_by_board?: Record<string, number> | null;
        required_references?: Array<'x' | 'y' | 'z' | 'g'> | null;
        destination_options?: BioXpDeckDestinationV1[] | null;
    }>;
}

export type BioXpOperatorDashboardWire = BioXpOperatorDashboard | BioXpOperatorDashboardV2;
export type BioXpOperatorControlCatalogWire = BioXpOperatorControlCatalog | BioXpOperatorControlCatalogV2;

export interface BioXpPipetteHardwareEvidence {
    ok: boolean;
    hardware_truth_level?: 'hardware_query' | 'unparsed_hardware_reply' | 'no_readback' | null;
    reply_received?: boolean | null;
    semantic_ok?: boolean | null;
    tip_loaded?: boolean | null;
    pressure?: number | null;
    error?: string | null;
    [key: string]: unknown;
}

export interface BioXpPipetteReceipt {
    schema: 'bioxp.pipette.receipt.v1';
    receipt_id: string;
    created_at: string;
    operation: string;
    truth: {
        semantic_query_response_verified: boolean;
        delivery_verified: boolean;
        controller_acknowledged: boolean;
        completion_verified: boolean;
        hardware_precondition_verified: boolean;
        hardware_postcondition_verified: boolean;
        physical_effect_verified: false;
        physical_effect_claim_suppressed: true;
    };
}

export interface BioXpPipetteChannel {
    channel: 0 | 1 | 2 | 3;
    pipette_id: 0 | 1 | 2 | 3;
    available: boolean;
    initialized: boolean;
    software_initialized: boolean;
    tip_loaded: boolean;
    software_tip_loaded: boolean;
    hardware_truth_level: string;
    hardware_tip_status: BioXpPipetteHardwareEvidence | null;
    hardware_pressure: BioXpPipetteHardwareEvidence | null;
    oem_diagnosis: string | null;
    oem_error_queue: number[];
    liquid_level_ul: number;
    front_air_level_ul: number;
    rear_air_level_ul: number;
    last_command: string | null;
}

export interface BioXpPipettes {
    ok: boolean;
    transport: 'novo_usb_can';
    channels: BioXpPipetteChannel[];
    channel_count: 4;
    live_query_performed: false;
    /** Software-selected group tip type, not evidence of a physically loaded tip. */
    tip_type: number;
    allow_to_stop: boolean;
    last_error: { channel: 0 | 1 | 2 | 3; error_code: number; source: 'ClassPipetteCollection.handlePipetteMessage' } | null;
    last_group_transaction: Record<string, unknown> | null;
    latest_receipt?: BioXpPipetteReceipt | null;
    application?: BioXpPipetteApplicationStatus | null;
    physical_effect_verified: false;
}

export interface BioXpPipetteReadbackRequest {
    include_data?: boolean;
}

export interface BioXpPipetteReadbackChannel {
    channel: 0 | 1 | 2 | 3;
    semantic_ok: boolean;
    firmware: Record<string, unknown>;
    status: Record<string, unknown>;
    tip: Record<string, unknown>;
    pressure: Record<string, unknown> | null;
    data: Record<string, unknown> | null;
}

export interface BioXpPipetteReadback {
    hardware_truth_level: 'hardware_query';
    ok: boolean;
    semantic_ok: boolean;
    available: boolean;
    channel_count: 4;
    channels_constructed_unconditionally: [0, 1, 2, 3];
    channels: [BioXpPipetteReadbackChannel, BioXpPipetteReadbackChannel, BioXpPipetteReadbackChannel, BioXpPipetteReadbackChannel];
    include_data: boolean;
    live_query_performed: true;
    truth_source: 'live_hardware_queries';
    delivery_verified: false;
    controller_acknowledged: false;
    completion_verified: false;
    hardware_postcondition_verified: false;
    physical_effect_verified: false;
    oem_source_anchor: 'ClassPipetteCollection constructor/readback; ClassPipette QueryFirmware/Q1/?31/?57/getData';
    receipt_id: string;
    receipt_truth: BioXpPipetteReceipt['truth'];
}

export type BioXpPipetteApplicationOperation = 'load_tip' | 'move_to_waste' | 'detect_fluid' | 'plunger_up' | 'plunger_down';
export type BioXpPipetteApplicationDependencyName = 'deck' | 'gantry' | 'z' | 'pressure' | 'pipette' | 'machine_state';

export interface BioXpPipetteApplicationDependency {
    bound: boolean;
    authority: string | null;
    generation: number;
    state: Record<string, unknown>;
    blockers: string[];
}

export interface BioXpPipetteApplicationStatus {
    ok: boolean;
    mode: 'plan_only';
    execution_admitted: false;
    physical_effect_verified: false;
    operations: BioXpPipetteApplicationOperation[];
    dependencies: Record<BioXpPipetteApplicationDependencyName, BioXpPipetteApplicationDependency>;
    required_dependencies: BioXpPipetteApplicationDependencyName[];
    missing_dependencies: BioXpPipetteApplicationDependencyName[];
    dependency_blockers: string[];
    dependencies_satisfied: boolean;
    blocker: 'physical_pipette_execution_not_authorized';
}

export type BioXpPipetteApplicationPlanRequest =
    | {
        operation: 'load_tip';
        tip_tray: string;
        tip_well: string;
        tip_type: number;
        tip_location: 0 | 1 | 2 | 3;
        home_z_after?: boolean;
    }
    | { operation: 'move_to_waste' }
    | { operation: 'detect_fluid'; fluid_class: 'TC' | 'MS' | 'OC' | 'RC' | 'STRIP' }
    | { operation: 'plunger_up' }
    | { operation: 'plunger_down' };

export interface BioXpPipetteApplicationPlan {
    ok: boolean;
    operation: BioXpPipetteApplicationOperation;
    mode: 'plan_only';
    execution_admitted: false;
    motion_commanded: false;
    liquid_mutation_commanded: false;
    controller_acknowledged: false;
    completion_verified: false;
    physical_effect_verified: false;
    state_reconciled: false;
    requested_inputs: Record<string, unknown>;
    effective_inputs: null;
    steps: Array<Record<string, unknown> & { owner: BioXpPipetteApplicationDependencyName }>;
    dependencies: Partial<Record<BioXpPipetteApplicationDependencyName, BioXpPipetteApplicationDependency>>;
    required_dependencies: BioXpPipetteApplicationDependencyName[];
    missing_dependencies: BioXpPipetteApplicationDependencyName[];
    dependency_blockers: string[];
    dependencies_satisfied: boolean;
    required_completion_evidence: string[];
    constants: Record<string, unknown>;
    oem_source_anchor: string;
    blocker: 'physical_pipette_execution_not_authorized' | 'application_dependencies_unbound';
    receipt_id: string;
    receipt_truth: BioXpPipetteReceipt['truth'];
}

export interface BioXpOperatorAdmission {
    action_id: string;
    ownership_generation: number;
    enabled: boolean;
    disabled_reason: string | null;
    dependencies: BioXpOperatorDependency[];
}

/** Robot-published, locally resolved JSON Schema for structured input controls. */
export interface BioXpOperatorJsonSchema {
    $ref?: string;
    $defs?: Record<string, BioXpOperatorJsonSchema>;
    discriminator?: { propertyName: string; mapping?: Record<string, string> };
    type?: string | string[];
    title?: string;
    description?: string;
    default?: unknown;
    /** Documentary native value; applied only by an explicit operator edit. */
    source_default?: unknown;
    enum?: unknown[];
    const?: unknown;
    properties?: Record<string, BioXpOperatorJsonSchema>;
    required?: string[];
    items?: BioXpOperatorJsonSchema;
    additionalProperties?: boolean | BioXpOperatorJsonSchema;
    anyOf?: BioXpOperatorJsonSchema[];
    oneOf?: BioXpOperatorJsonSchema[];
    minimum?: number;
    maximum?: number;
    exclusiveMinimum?: number;
    exclusiveMaximum?: number;
    minLength?: number;
    maxLength?: number;
    minItems?: number;
    maxItems?: number;
    [key: string]: unknown;
}

export interface BioXpOperatorInputSpec {
    name: string;
    wire_name: string | null;
    label: string;
    value_type: 'string' | 'integer' | 'number' | 'boolean' | 'enum' | 'json';
    location: 'path' | 'query' | 'body';
    required: boolean;
    description: string;
    unit: string | null;
    enum_values: string[];
    minimum: number | null;
    maximum: number | null;
    exclusive_minimum: number | null;
    exclusive_maximum: number | null;
    default: unknown;
    json_schema?: BioXpOperatorJsonSchema | null;
}

export interface BioXpOperatorActionSpec {
    action_id: string;
    label: string;
    subsystem: string;
    category: string;
    kind: BioXpOperatorActionKind;
    safety_class: BioXpOperatorSafetyClass;
    description: string;
    source_anchor: string | null;
    informational_method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
    informational_path: string;
    provider_available: boolean;
    provider_unavailable_reason: string | null;
    available: boolean;
    unavailable_reason: string | null;
    enabled: boolean;
    disabled_reason: string | null;
    dependencies: BioXpOperatorDependency[];
    requires_confirmation: boolean;
    /** Robot-owned presentation age, not a client-side admission token. */
    snapshot_freshness?: { state: string; age_s: number | null; fresh_for_s: number | null } | null;
    timeout_seconds: number;
    required_provider_capability: string | null;
    inputs: BioXpOperatorInputSpec[];
    stages: string[];
    aggregate_abort?: true;
    physical_scope?: 'aggregate_oem_all_present_boards';
    x_only?: false;
}

export interface BioXpOperatorControlCatalog {
    canonical: BioXpOperatorControlCatalogV2;
    schema_name: 'bioxp.operator_control_catalog';
    schema_version: 'bioxp.operator_control_catalog.v1';
    machine_serial: string;
    ownership_generation: number;
    registry_sha256: string;
    evidence_lock_sha256: string;
    source_authority_verified: boolean;
    dashboard: BioXpOperatorDashboard;
    actions: BioXpOperatorActionSpec[];
}

export interface BioXpOperatorActionReceipt {
    schema_version: 'bioxp.operator_action_receipt.v1';
    command_id: string;
    action_id: string;
    kind: BioXpOperatorActionKind;
    safety_class: BioXpOperatorSafetyClass;
    status: 'acknowledged' | 'admission_pending' | 'queued' | 'completed' | 'observed' | 'failed' | 'blocked' | 'rejected' | 'reconciliation_required';
    idempotency_key: string;
    idempotency_replay_enabled: boolean;
    ownership_generation: number;
    started_at: string;
    finished_at: string | null;
    duration_ms: number | null;
    request_received_at: number | null;
    lock_acquired_at: number | null;
    admission_completed_at: number | null;
    provider_entry_at: number | null;
    provider_returned_at: number | null;
    receipt_persist_started_at: number | null;
    remote_acknowledged: boolean;
    controller_acknowledged: boolean;
    controller_terminal_state_verified: boolean;
    physical_effect_verified: boolean;
    automatic_retry: boolean | null;
    physical_outcome: string | null;
    persistence_fallback: Record<string, unknown> | null;
    machine_assessment: 'pass' | 'fail' | 'unverified';
    completion_class?: string | null;
    operator_assessment: 'pass' | 'fail' | null;
    operator_note: string | null;
    operator_assessment_idempotency_key: string | null;
    operator_assessed_at: number | null;
    inputs: Record<string, unknown>;
    requested_inputs: Record<string, unknown> | null;
    response: Record<string, unknown> | null;
    authority_receipt_id: string | null;
    authority_receipt_status: BioXpOperatorActionReceipt['status'] | { omitted: string } | null;
    authority_fingerprint: string | null;
    observation_receipt_id: string | null;
    observes_command_id: string | null;
    error: string | null;
    stage_receipts: Record<string, unknown>[];
}

export interface BioXpOperatorSourceIdentity {
    robot_identity: string;
    release_id: string;
    source_manifest_sha256: string;
    source_aggregate_sha256: string;
    release_verified: boolean;
    registry_sha256: string;
    evidence_lock_sha256: string;
    evidence_lock_identity_verified: boolean;
}

export interface BioXpOperatorRecordedActionReceipt extends Omit<BioXpOperatorActionReceipt, 'status'> {
    status: BioXpOperatorActionReceipt['status'] | 'outcome_unknown';
    completion_ambiguous: boolean;
    completion_verified: boolean;
    delivery_verified: boolean;
    hardware_postcondition_verified: boolean;
    hardware_precondition_verified: boolean;
    reconciliation_required: boolean;
    retry_forbidden: boolean;
    interrupt_evidence?: BioXpOperatorInterruptEvidenceV2 | null;
    source_identity: BioXpOperatorSourceIdentity;
}

export interface BioXpOperatorLiveSourceActionReceipt extends BioXpOperatorActionReceipt {
    interrupt_evidence?: BioXpOperatorInterruptEvidenceV2 | null;
    source_identity: BioXpOperatorSourceIdentity;
}

export interface BioXpOperatorLiveTimeoutActionReceipt extends Omit<BioXpOperatorActionReceipt, 'status'> {
    status: 'outcome_unknown';
    interrupt_evidence?: BioXpOperatorInterruptEvidenceV2 | null;
    source_identity: BioXpOperatorSourceIdentity;
    automatic_retry: false;
    physical_outcome: 'ambiguous';
    completion_ambiguous: true;
    reconciliation_required: true;
    retry_forbidden: true;
}

export type BioXpOperatorLiveActionReceipt = BioXpOperatorActionReceipt
    | BioXpOperatorLiveSourceActionReceipt
    | BioXpOperatorRecordedActionReceipt
    | BioXpOperatorLiveTimeoutActionReceipt;

export interface BioXpOperatorLegacyReconciliationReceipt {
    action_id: string;
    automatic_retry: false;
    callback_session_id: string | null;
    caller_class: string;
    command_id: string;
    connection_generation: number | null;
    control_class: string;
    duration_ms: number;
    entrypoint_id: string;
    finished_at: string;
    idempotency_key: string;
    idempotency_replay_enabled: boolean;
    lifecycle_stage_id: string | null;
    operation: string;
    ownership_generation: number;
    physical_outcome: 'ambiguous';
    protocol_action_id: string | null;
    protocol_job_id: string | null;
    requested_inputs: Record<string, unknown>;
    response: Record<string, unknown>;
    stage_receipts: Record<string, unknown>[];
    status: 'reconciliation_required';
}

export interface BioXpOperatorLegacyUnindexedPipetteReceipt {
    error: string;
    failure_code: string;
    ok: false;
    outcome: string;
    response: Record<string, unknown>;
    runtime_binding: {
        callback_session_id: string;
        caller_class: string;
        control_class: string;
        entrypoint_id: string;
        lifecycle_stage_id: string;
        owner: string;
        transport_owner_bound: true;
    };
    stage_receipts: Record<string, unknown>[];
}

export type BioXpOperatorRecordedReceipt =
    | BioXpOperatorLiveActionReceipt
    | BioXpPipetteReceipt
    | BioXpOperatorLegacyReconciliationReceipt
    | BioXpOperatorLegacyUnindexedPipetteReceipt;

export interface BioXpOperatorHistoryReceipt extends BioXpOperatorReceiptV2 {
    history: {
        source: 'direct' | 'retained';
        source_schema: string | null;
        recorded_status: string;
        remote_acknowledged: boolean | null;
        controller_acknowledged: boolean | null;
        controller_terminal_state_verified: boolean | null;
        machine_assessment: 'pass' | 'fail' | 'unverified' | null;
        operator_assessment: 'pass' | 'fail' | null;
        operator_note: string | null;
    };
}

export function bioXpOperatorGenerationPayload(
    connectionGeneration: number,
    ownershipGeneration: number,
) {
    if (!Number.isSafeInteger(connectionGeneration) || connectionGeneration <= 0) {
        throw new Error('A positive safe BMS connection generation is required');
    }
    if (!Number.isSafeInteger(ownershipGeneration) || ownershipGeneration <= 0) {
        throw new Error('A positive safe robot ownership generation is required');
    }
    return {
        expected_connection_generation: connectionGeneration,
        expected_ownership_generation: ownershipGeneration,
    };
}


// Live workflows use robot custody.
export type BioXpWorkflowPhase = 'queued' | 'preparing' | 'starting' | 'executing' | 'waiting' | 'waking' | 'epilogue' | 'cleanup' | 'reconciling' | 'terminal';
export type BioXpWorkflowGate = 'ordinary_pause' | 'deferred_pause' | 'delaypoint' | 'review' | 'error_hold';
export type BioXpWorkflowAction =
    | { action: 'pause'; mode: 'ordinary' | 'deferred' }
    | { action: 'wake'; gate_id: string }
    | { action: 'continue'; gate: 'ordinary_pause' | 'deferred_pause' | 'delaypoint'; gate_id: string }
    | { action: 'safe_stop' | 'abort' };
export interface BioXpWorkflowState {
    command_id: string;
    phase: BioXpWorkflowPhase;
    gate: BioXpWorkflowGate | null;
    gate_id: string | null;
    source_occurrence_id: string | null;
    requested_control: BioXpWorkflowAction | null;
    last_control_id: string | null;
    reached_control_id: string | null;
    held_reason: string | null;
    child_command_ids: string[];
}
export interface BioXpWorkflowCommand {
    command_id: string;
    idempotency_key: string;
    ownership_generation: number;
    state_version: number;
    status: 'queued' | 'dispatched' | 'interrupting' | 'completed' | 'failed' | 'interrupted' | 'cleared' | 'ambiguous' | 'rejected';
    terminal: boolean;
    status_path: string;
}
export interface BioXpWorkflowSourceWell {
    content: string | null;
    volume: number;
    capacity: number;
    empty: boolean;
    zone_index: number | null;
}
export interface BioXpWorkflowSourceTray {
    tray_id: string;
    location: number;
    wells: BioXpWorkflowSourceWell[];
    tip_type: number | null;
    tray_empty: boolean | null;
    strip_color: string | null;
}
export interface BioXpWorkflowSourceModel {
    logical_tip_present: boolean | null;
    carried_plate_present: boolean | null;
    allow_to_stop: boolean | null;
    trays: Record<string, BioXpWorkflowSourceTray>;
    strips: BioXpWorkflowSourceTray[];
    tip_trays: BioXpWorkflowSourceTray[];
    pressure_baseline: number[];
    pressure_history: number[][];
    fluid_name: string | null;
    tip_zone_index: number | null;
    old_tip_well: string | null;
}
// Mirrors native calibration_measurements.MeasurementForm (generated producer contract).
export interface BioXpMeasurementForm {
    fields: { field_id: string; label: string; unit: 'degC' | 'uL' | 'mg' | 'g' | 'steps';
        module: 'rc' | 'oc' | 'tc' | 'pipette'; location?: string | null; zone?: string | null;
        target?: string | number | null; commanded?: string | number | null;
        controller_reported?: string | number | null; repetitions?: number; context?: Record<string, unknown> }[];
}
export interface BioXpPendingReview {
    stage_id: string | null; action_id: string | null; reason: string | null;
    source_occurrence_id?: string | null; measurement_form?: BioXpMeasurementForm | null;
}
export interface BioXpWorkflowJob {
    job_id: string;
    status: string;
    protocol?: { document?: Record<string, unknown> | null } | null;
    command?: BioXpWorkflowCommand | null;
    operator?: { manual_review_required: boolean; pending_review: BioXpPendingReview | null };
    execution?: {
        dry_run: boolean;
        runtime_state: {
            completed: boolean;
            current_stage_id: string | null;
            stage_states: Record<string, { current_action_id: string | null; pause_marker_action_id: string | null }>;
            workflow?: BioXpWorkflowState | null;
            source_model?: BioXpWorkflowSourceModel;
            action_results?: Record<string, unknown>[];
        };
    };
}
export interface BioXpWorkflowJobObservation {
    schema_version: 'bioxp.protocol_job_observation.v1';
    job_id: string;
    status: string;
    command: Omit<BioXpWorkflowCommand, 'idempotency_key' | 'status_path'>;
    execution: { dry_run: boolean; runtime_state: { workflow?: BioXpWorkflowState | null } };
    operator: { pending_review?: BioXpPendingReview | null };
}
// Discovery is intentionally not selected-job detail. Older robots may still
// return full rows; consumers select by identity and fetch detail separately.
export interface BioXpWorkflowJobSummary {
    job_id: string;
    status: string;
    dry_run: boolean;
    protocol_id: string;
    source_type: 'native' | 'oem_xml';
    created_at: string;
    updated_at: string;
    pending_review: BioXpPendingReview | null;
    command?: BioXpWorkflowCommand | null;
}
export interface BioXpWorkflowInput {
    source_type: 'native' | 'oem_xml';
    document?: Record<string, unknown> | null;
    xml_path?: string | null;
    live_execution?: Record<string, unknown> | null;
    live_execution_ack?: boolean;
    operator_id?: string | null;
    physical_console_verified?: boolean;
    deck_manifest?: Record<string, unknown> | null;
    preflight?: Record<string, unknown> | null;
    artifact_refs?: string[];
    snapshot_refs?: string[];
}
export type BioXpWorkflowSubmission = BioXpWorkflowInput & {
    expected_connection_generation: number;
    idempotency_key: string;
    dry_run: false;
};
export interface BioXpWorkflowBinding {
    expected_connection_generation: number;
    expected_ownership_generation: number;
    command_id: string;
    idempotency_key: string;
}
export type BioXpWorkflowControlRequest = BioXpWorkflowBinding & BioXpWorkflowAction;
export interface BioXpWorkflowControlResponse {
    control_command_id: string;
    idempotency_key: string;
    command_id: string;
    job_id: string;
    ownership_generation: number;
    state_version: number;
    accepted: boolean;
    reached: boolean;
    phase: BioXpWorkflowPhase;
    gate: BioXpWorkflowGate | null;
    gate_id: string | null;
    status_path: string;
}
export type BioXpWorkflowReviewRequest = BioXpWorkflowBinding & {
    source_occurrence_id?: string | null;
    measurements?: Record<string, (string | number)[]>;
    reviewer: string;
    note?: string | null;
    stage_id: string;
    action_id: string | null;
};


const statusKey = ['bioxp', 'status'] as const;

const operatorCatalogKey = ['bioxp', 'operator-controls', 'catalog'] as const;
const operatorHistoryKey = ['bioxp', 'operator-controls', 'history'] as const;

export interface BioXpOperatorReportFilters {
    status?: string;
    operation?: string;
    action?: string;
    event_kind?: string;
    channel?: number;
    entrypoint?: string;
    caller_class?: string;
    control_class?: string;
    protocol_job_id?: string;
    protocol_action_id?: string;
    lifecycle_stage_id?: string;
    lifecycle_attempt_id?: string;
    outcome?: string;
    event_source?: string;
    pressure_stream_id?: string;
    delivery_verified?: boolean;
    controller_acknowledged?: boolean;
    completion_verified?: boolean;
    hardware_postcondition_verified?: boolean;
    physical_effect_verified?: boolean;
    evidence_state?: string;
    command_id?: string;
    pipette_operation_id?: string;
    connection_generation?: number;
    ownership_generation?: number;
    start?: number;
    end?: number;
}

export type BioXpOperatorReportJsonValue = null | boolean | number | string | BioXpOperatorReportJsonValue[] | BioXpOperatorReportJsonObject;
export interface BioXpOperatorReportJsonObject { [key: string]: BioXpOperatorReportJsonValue }

export interface BioXpOperatorReportListener { host: string | null; port: number | null }
export interface BioXpOperatorReportReleaseSource { commit: string | null; tree: string | null; mode: string | null; manifest_sha256: string | null; aggregate_sha256: string | null }
export interface BioXpOperatorReportReleaseImage { id: string | null; inspection_receipt_sha256: string | null }
export interface BioXpOperatorReportReleaseDeployment { receipt_id: string | null; installed_at: number | string | null; receipt_sha256: string | null }
export interface BioXpOperatorReportReleaseBinding { service_unit: string | null; unit_sha256: string | null; launcher_sha256: string | null; configuration_sha256: string | null; oem_lock_sha256: string | null; udocker_sha256: string | null; udocker_tree_sha256: string | null; declared_listener: BioXpOperatorReportListener | null; observed_listener: BioXpOperatorReportListener | null }
export interface BioXpOperatorReportReleaseIdentity { schema?: string | null; status: string | null; verified: boolean; reason_code: string | null; release_id: string | null; source: BioXpOperatorReportReleaseSource; image: BioXpOperatorReportReleaseImage; deployment: BioXpOperatorReportReleaseDeployment; binding: BioXpOperatorReportReleaseBinding }
export interface BioXpOperatorReportUnavailableReleaseIdentity { status: string; verified: false; reason_code: string }
export interface BioXpOperatorReportSourceHighWaters { operator_commands: number; operator_transitions: number; pipette_operations: number; pipette_channel_observations: number; pipette_transport_exchanges: number; runtime_events: number; pipette_pressure_streams: number; pipette_pressure_chunks: number; runtime_evidence_objects: number; runtime_evidence_links: number | null; runtime_evidence_events: number; operator_plane_command_versions: number; operator_plane_pipette_versions: number; operator_plane_pressure_stream_versions: number; operator_plane_evidence_versions: number }
export interface BioXpOperatorReportSchemaIdentity { database_identity: 'robot_authoritative_sqlite'; schema_version: 5; identity_version: number | null; release_identity: BioXpOperatorReportReleaseIdentity }
export interface BioXpOperatorReportCurrentSnapshot {
    database_incarnation_id: string;
    schema_identity: BioXpOperatorReportSchemaIdentity;
    release_identity: BioXpOperatorReportReleaseIdentity;
    source_high_waters: BioXpOperatorReportSourceHighWaters;
    high_water_sequence?: number;
    high_water_rowid?: number;
    high_water_event_id?: number;
}

export interface BioXpOperatorReportLegacySnapshot {
    database_identity: 'robot_authoritative_sqlite';
    schema_version: 2;
    database_path_exposed: false;
    identity_version: 2;
    high_water_sequence?: number;
    high_water_rowid?: number;
    high_water_event_id?: number;
}

export type BioXpOperatorReportSnapshot = BioXpOperatorReportCurrentSnapshot | BioXpOperatorReportLegacySnapshot;

export interface BioXpOperatorReportSummary {
    scope?: string;
    filters?: BioXpOperatorReportFilters;
    snapshot?: BioXpOperatorReportSnapshot;
    commands?: { total?: number; by_status?: Record<string, number> };
    pipette_operations?: { total?: number; by_status?: Record<string, number> };
    runtime_events?: { total?: number; by_kind?: Record<string, number> };
    pressure?: { streams?: number; chunks?: number };
    rates?: { delivery_rate?: number; ack_rate?: number; completion_rate?: number; postcondition_rate?: number; physical_effect_rate?: number; failure_rate?: number };
    latency?: { average_ms?: number; maximum_ms?: number };
    errors?: { by_code?: Record<string, number> };
}

export interface BioXpOperatorReportCommandRow {
    sequence: number;
    command_id: string;
    idempotency_key: string;
    operation: string | null;
    command_kind: string | null;
    entrypoint_id: string | null;
    caller_class: string | null;
    control_class: string | null;
    action_id: string | null;
    status: string;
    outcome: string | null;
    failure_code: string | null;
    ownership_generation: number | null;
    connection_generation: number | null;
    started_at: number | string | null;
    admitted_at: number | string | null;
    dispatched_at: number | string | null;
    finished_at: number | string | null;
    duration_ms: number | null;
    delivery_verified: boolean;
    controller_acknowledged: boolean;
    completion_verified: boolean;
    semantic_query_response_verified: boolean;
    hardware_precondition_verified: boolean;
    hardware_postcondition_verified: boolean;
    physical_effect_verified: boolean;
    evidence_state: string | null;
}

export interface BioXpOperatorReportCommands { filters: BioXpOperatorReportFilters; snapshot: BioXpOperatorReportSnapshot; returned_count: number; filtered_total: number; commands: BioXpOperatorReportCommandRow[]; has_more: boolean; next_cursor: string | null }
export interface BioXpOperatorReportTransition { transition_id: number; state: string; observed_at: number | string; detail: BioXpOperatorReportJsonObject }
export interface BioXpOperatorReportLegalHoldAssessment { event_id: string; observed_at: number | string; legal_hold_requested: boolean; assessment: BioXpOperatorReportJsonValue; actor: string | null; retained_deadline: number | string | null; legal_hold_projection_updated: boolean }
export interface BioXpOperatorReportEvidence { evidence_artifact_id: string; sha256: string; byte_count: number; created_at: number | string; retention_deadline: number | string | null; legal_hold: boolean; latest_legal_hold_assessment: BioXpOperatorReportLegalHoldAssessment | null; expiry_state: string; expiry_receipt_id: string | null }
export interface BioXpOperatorReportChannel { observation_id: string; command_id: string; pipette_operation_id: string; channel: number; phase: string | null; observed_at: number | string; semantic_validity: string | null; truth_source: string | null; tip_loaded: boolean | null; pressure: number | null; pressure_units: string | null; status: string | number | null; error_code: string | number | null; firmware_class: string | null; detail: BioXpOperatorReportJsonObject }
export interface BioXpOperatorReportExchange { exchange_id: string; transaction_id: string | number | null; channel: number | null; transaction_phase: string | null; command_family: string | null; matcher_name: string | null; tx_id: number | null; expected_rx_id: number | null; observed_rx_id: number | null; tx_bytes: number[]; rx_bytes: number[]; delivery_verified: boolean; semantic_match: boolean; controller_acknowledged: boolean; completion_verified: boolean; completion_before_ack: boolean; sent_at: number | string | null; received_at: number | string | null; ack_at: number | string | null; completion_at: number | string | null }
export interface BioXpOperatorReportEvent { event_id: number; command_id: string | null; pipette_operation_id: string | null; event_source: string; event_kind: string; channel: number | null; observed_at: number | string; event: BioXpOperatorReportJsonObject; snapshot?: BioXpOperatorReportSnapshot | null }
export interface BioXpOperatorReportPressureStream { stream_session_id: string; pipette_operation_id: string | null; channels: number[]; sample_period_ms: number | null; started_at: number | string; stopped_at: number | string | null; source_generation: number | null; reader_generation: number | null; offset_identity: string | null; terminal_state: string | null; loss_count: number | null }
export interface BioXpOperatorReportPressureChunk { chunk_id: string; channel: number; chunk_sequence: number; sample_count: number; lost_sample_count: number; units: string; sha256: string; byte_count: number; evidence_artifact_id: string | null; summary: BioXpOperatorReportJsonObject | null }

export interface BioXpOperatorReportPipette {
    pipette_operation_id: string;
    command_id: string;
    operation: string | null;
    entrypoint_id: string | null;
    caller_class: string | null;
    control_class: string | null;
    action_id: string | null;
    protocol_job_id: string | null;
    protocol_action_id: string | null;
    lifecycle_stage_id: string | null;
    lifecycle_attempt_id: string | null;
    callback_session_id: string | null;
    status: string;
    outcome: string | null;
    failure_code: string | null;
    delivery_verified: boolean;
    controller_acknowledged: boolean;
    completion_verified: boolean;
    semantic_query_response_verified: boolean;
    hardware_postcondition_verified: boolean;
    physical_effect_verified: boolean;
    evidence_state: string | null;
    channels?: BioXpOperatorReportChannel[];
    exchanges?: BioXpOperatorReportExchange[];
    events?: BioXpOperatorReportEvent[];
    pressure_streams?: BioXpOperatorReportPressureStream[];
}

export interface BioXpOperatorReportPipettePage { filters: BioXpOperatorReportFilters; snapshot: BioXpOperatorReportSnapshot; returned_count: number; filtered_total: number; has_more: boolean; next_cursor: string | null; pipette: BioXpOperatorReportPipette[] }
export interface BioXpOperatorReportPageContinuation { returned_count: number; filtered_total: number; has_more: boolean; next_cursor: string | null }
export interface BioXpOperatorReportCommandDetail extends BioXpOperatorReportCommandRow { requested_inputs: BioXpOperatorReportJsonObject; effective_inputs: BioXpOperatorReportJsonObject; source_identity: BioXpOperatorReportJsonObject; transitions: BioXpOperatorReportTransition[]; evidence: BioXpOperatorReportEvidence[]; evidence_preview: BioXpOperatorReportEvidence[]; evidence_continuation: BioXpOperatorReportPageContinuation; pipette: BioXpOperatorReportPipette | null; snapshot: BioXpOperatorReportSnapshot; child_page_limit: number }
export interface BioXpOperatorReportEvents { event_kind: string | null; filters: BioXpOperatorReportFilters; snapshot: BioXpOperatorReportSnapshot; returned_count: number; filtered_total: number; has_more: boolean; next_cursor: string | null; events: BioXpOperatorReportEvent[] }
export interface BioXpOperatorReportPressureStreams { filters: BioXpOperatorReportFilters; snapshot: BioXpOperatorReportSnapshot; returned_count: number; filtered_total: number; has_more: boolean; next_cursor: string | null; pressure_streams: BioXpOperatorReportPressureStream[] }
export interface BioXpOperatorReportTransitionPage extends BioXpOperatorReportPageContinuation { command_id: string; filters: { command_id: string; limit: number }; snapshot: BioXpOperatorReportSnapshot; transitions: BioXpOperatorReportTransition[] }
export interface BioXpOperatorReportEvidencePage extends BioXpOperatorReportPageContinuation { command_id: string; filters: { command_id: string; limit: number }; snapshot: BioXpOperatorReportSnapshot; evidence: BioXpOperatorReportEvidence[] }
export interface BioXpOperatorReportChannelPage extends BioXpOperatorReportPageContinuation { pipette_operation_id: string; filters: { pipette_operation_id: string; limit: number }; snapshot: BioXpOperatorReportSnapshot; channels: BioXpOperatorReportChannel[] }
export interface BioXpOperatorReportExchangePage extends BioXpOperatorReportPageContinuation { pipette_operation_id: string; filters: { pipette_operation_id: string; limit: number }; snapshot: BioXpOperatorReportSnapshot; exchanges: BioXpOperatorReportExchange[] }
export interface BioXpOperatorReportPressureSamplePage extends BioXpOperatorReportPageContinuation { stream_session_id: string; filters: BioXpOperatorReportFilters; snapshot: BioXpOperatorReportSnapshot; samples: BioXpOperatorReportPressureChunk[] }
export interface BioXpOperatorReportEventDetail extends BioXpOperatorReportEvent { snapshot: BioXpOperatorReportSnapshot | null }
export interface BioXpOperatorReportPressureDetail { stream_session_id: string; pipette_operation_id: string | null; channels: number[]; sample_period_ms: number | null; started_at: number | string; stopped_at: number | string | null; terminal_state: string | null; loss_count: number | null; chunks: BioXpOperatorReportPressureChunk[]; child_page_limit: number; snapshot: BioXpOperatorReportSnapshot }

export interface BioXpOperatorReportExport {
    export_id: string;
    evidence_artifact_id: string;
    status: string;
    format: 'json' | 'csv';
    row_count: number;
    sha256: string;
    byte_count: number;
    release_identity: BioXpOperatorReportReleaseIdentity;
    download: string;
}

export interface BioXpOperatorReportExportList {
    items: Array<{
        export_id: string;
        format: string;
        row_count: number;
        sha256: string;
        byte_count: number;
        status: string;
        created_at: number | string;
        release_identity: BioXpOperatorReportReleaseIdentity | BioXpOperatorReportUnavailableReleaseIdentity;
        publication_state: string;
        evidence_state: string;
        legal_hold: boolean;
        evidence_available: boolean;
        download: string | null;
    }>;
    returned_count: number;
    limit: number;
    available: boolean;
    unavailable_reason: string | null;
}

const operatorReportSummaryKey = ['bioxp', 'operator-reports', 'summary'] as const;
const operatorReportCommandsKey = ['bioxp', 'operator-reports', 'commands'] as const;
const operatorReportParams = (filters?: BioXpOperatorReportFilters, limit?: number, cursor?: string | null) => ({
    ...(filters ?? {}),
    ...(limit === undefined ? {} : { limit }),
    ...(cursor ? { cursor } : {}),
});

function cameraImageFromResponse(response: {
    data: Blob;
    headers: Record<string, unknown>;
}): BioXpCameraImage {
    if (!(response.data instanceof Blob) || response.data.type !== 'image/jpeg' || response.data.size < 1) {
        throw new Error('BioXP camera proxy returned an invalid JPEG image');
    }
    const etag = String(response.headers.etag ?? '');
    const sha256 = String(response.headers['x-content-sha256'] ?? '');
    const generationText = String(response.headers['x-bioxp-connection-generation'] ?? '');
    const connectionGeneration = Number(generationText);
    if (!/^[0-9a-f]{64}$/.test(sha256)
        || (etag !== sha256 && etag !== `"${sha256}"`)
        || !Number.isSafeInteger(connectionGeneration)
        || connectionGeneration < 1) {
        throw new Error('BioXP camera proxy returned invalid image provenance');
    }
    return { blob: response.data, etag, sha256, connectionGeneration };
}

function nestedOperatorDetail(value: unknown, depth = 0, budget = { remaining: 128 }): string | null {
    if (--budget.remaining < 0 || depth > 8 || value === null || value === undefined) return null;
    if (typeof value === 'string') return boundedOperatorText(value) || null;
    if (Array.isArray(value)) {
        const normalized = value.slice(0, 16).map((entry) => {
            if (entry && typeof entry === 'object' && 'msg' in entry) {
                const item = entry as { loc?: unknown; msg?: unknown };
                const location = Array.isArray(item.loc) ? item.loc.slice(0, 16).map((part) => typeof part === 'string' ? boundedOperatorText(part, 128) : typeof part === 'number' ? String(part) : '?').join('.') : '';
                const message = typeof item.msg === 'string'
                    ? boundedOperatorText(item.msg)
                    : nestedOperatorDetail(item.msg, depth + 1, budget);
                return message ? (location ? `${location}: ${message}` : message) : null;
            }
            return nestedOperatorDetail(entry, depth + 1, budget);
        }).filter((entry): entry is string => Boolean(entry));
        const joined = normalized.length ? normalized.join('; ') : null;
        return joined ? boundedOperatorText(joined) : null;
    }
    if (typeof value !== 'object') return null;
    const record = value as Record<string, unknown>;
    for (const key of ['detail', 'message', 'reason', 'block_reason', 'startup_error', 'error']) {
        if (key in record) {
            const found = nestedOperatorDetail(record[key], depth + 1, budget);
            if (found) {
                const code = typeof record.code === 'string' ? record.code
                    : typeof record.error === 'string' ? record.error : null;
                return code && code !== found ? boundedOperatorText(`${found} (${boundedOperatorText(code)})`) : found;
            }
        }
    }
    return null;
}


export interface BioXpErrorPresentation {
    status: number | null;
    summary: string;
    /** Bounded selected-field preview, not a complete JSON evidence export. */
    rawJson: string;
}


function bioXpErrorParts(error: unknown) {
    const response = error && typeof error === 'object' && 'response' in error
        ? (error as { response?: { status?: unknown; data?: unknown } }).response
        : undefined;
    const status = typeof response?.status === 'number' && Number.isInteger(response.status)
        ? response.status
        : null;
    const summary = bioXpProviderFailure(response?.data) ?? nestedOperatorDetail(
        response?.data && typeof response.data === 'object' && 'detail' in response.data
            ? (response.data as { detail?: unknown }).detail
            : response?.data,
    ) ?? (
        error && typeof error === 'object' && 'message' in error && typeof error.message === 'string'
            ? boundedOperatorText(error.message)
            : typeof error === 'string' ? boundedOperatorText(error) : 'Unknown error'
    );
    return { status, summary, body: response?.data ?? null };
}

export function bioXpErrorPresentation(error: unknown): BioXpErrorPresentation {
    const { status, summary, body } = bioXpErrorParts(error);
    return { status, summary, rawJson: bioXpErrorBodyPreview(body) };
}

export function bioXpErrorText(error: unknown): string {
    // Summary-only consumers must not serialize a diagnostic they never render.
    return bioXpErrorParts(error).summary;
}

export const useBioXpStatus = (enabled = true) => useQuery({
    queryKey: statusKey,
    queryFn: async () => (await api.get<BioXpStatusResponse>('/api/bioxp/status')).data,
    enabled,
    refetchInterval: enabled ? 10_000 : false,
    retry: false,
});


type CatalogMetadata = {
    catalog_view: 'metadata'; metadata_revision: string;
    actions: Array<Record<string, unknown>>;
    canonical: Omit<CatalogMetadata, 'canonical'>;
};
type CatalogAssessment = Omit<BioXpOperatorControlCatalog, 'actions' | 'canonical'> & {
    catalog_view: 'assessment'; metadata_revision: string;
    action_states: Array<Record<string, unknown>>; action_state_indices: number[];
    canonical: Omit<BioXpOperatorControlCatalogV2, 'actions'> & {
        catalog_view: 'assessment'; metadata_revision: string;
        action_states: Array<Record<string, unknown>>; action_state_indices: number[];
    };
};

type CatalogUpdate = {
    catalog_view: 'assessment'; assessment_revision: string;
    assessment_base?: Record<string, unknown>;
    assessment_source_revision?: string;
    assessment_overlay?: CatalogUpdate['assessment_changes'];
    assessment_changes: Array<[(string | number)[], unknown?, (string | number)[]?]>;
};
type CatalogBase = { revision: string; body: Record<string, unknown> };
type CatalogObservation = BioXpOperatorControlCatalog & {
    assessmentBases?: { legacy: CatalogBase; canonical: CatalogBase };
};

export function applyBioXpCatalogUpdate(update: CatalogUpdate, previous?: CatalogBase) {
    if (!update.assessment_revision || !Array.isArray(update.assessment_changes)) {
        throw new Error('Robot catalog update release required');
    }
    const base = update.assessment_base !== undefined
        ? { revision: update.assessment_revision, body: update.assessment_base } : previous;
    if (!base || base.revision !== (update.assessment_source_revision ?? update.assessment_revision)) throw new Error('Robot catalog update baseline missing');
    const snapshot = applyCatalogChanges(base.body, update.assessment_changes);
    // Old immutable-baseline peers remain readable. Advancing peers explicitly
    // separate the immutable result snapshot from request/display-only fields.
    if (update.assessment_overlay === undefined) return { base, body: snapshot };
    return { base: { revision: update.assessment_revision, body: snapshot },
        body: applyCatalogChanges(snapshot, update.assessment_overlay) };
}

function applyCatalogChanges(sourceBody: Record<string, unknown>, changes: CatalogUpdate['assessment_changes']) {
    const body = structuredClone(sourceBody);
    for (const change of changes) {
        const path = change[0];
        if (!Array.isArray(path) || path.length === 0) throw new Error('Invalid robot catalog update path');
        let target: Record<string | number, unknown> = body;
        for (const key of path.slice(0, -1)) {
            if (!Object.hasOwn(target, key) || target[key] === null || typeof target[key] !== 'object') throw new Error('Invalid robot catalog update path');
            target = target[key] as Record<string | number, unknown>;
        }
        const key = path[path.length - 1];
        // Define own properties rather than invoking __proto__ setters.
        if (change.length === 1) {
            if (Array.isArray(target)) target.splice(Number(key), 1);
            else delete target[key];
        } else {
            let value = change[1];
            if (change.length === 3) {
                value = sourceBody;
                for (const source of change[2]!) {
                    if (value === null || typeof value !== 'object' || !Object.hasOwn(value, source)) throw new Error('Invalid robot catalog update source');
                    value = (value as Record<string | number, unknown>)[source];
                }
            }
            Object.defineProperty(target, key, { value: structuredClone(value), enumerable: true, configurable: true, writable: true });
        }
    }
    return body;
}

export function composeBioXpCatalog(metadata: CatalogMetadata, assessment: CatalogAssessment): BioXpOperatorControlCatalog {
    const compose = (definitions: Omit<CatalogMetadata, 'canonical'>, current: Pick<CatalogAssessment, 'metadata_revision' | 'action_states' | 'action_state_indices'>) => {
        if (definitions.metadata_revision !== current.metadata_revision || definitions.actions.length !== current.action_state_indices.length) {
            throw new Error('Robot catalog definitions changed during read');
        }
        return definitions.actions.map((definition, index) => {
            const stateIndex = current.action_state_indices[index];
            if (!Number.isInteger(stateIndex) || stateIndex < 0 || stateIndex >= current.action_states.length) throw new Error('Invalid robot catalog assessment index');
            return { ...definition, ...current.action_states[stateIndex] };
        });
    };
    return { ...assessment, actions: compose(metadata, assessment),
        canonical: { ...assessment.canonical, actions: compose(metadata.canonical, assessment.canonical) },
    } as unknown as BioXpOperatorControlCatalog;
}

export const useBioXpOperatorControlCatalog = (
    connectionGeneration: number,
    enabled = true,
    lifecycleState?: string | null,
    zTargetSteps?: number,
) => {
    const queryClient = useQueryClient();
    const queryKey = [...operatorCatalogKey, connectionGeneration, enabled, lifecycleState ?? null, zTargetSteps];
    // One generation-scoped baseline entry in the existing QueryClient survives
    // draft-key disposal. Not a per-draft history or an independent poll owner.
    const baselineKey = [...operatorCatalogKey, connectionGeneration, 'assessment-base'];
    return useQuery<CatalogObservation>({
        queryKey,
        placeholderData: (previous, previousQuery) => previousQuery?.queryKey[operatorCatalogKey.length] === connectionGeneration ? previous : undefined,
        queryFn: async ({ signal }) => {
            const previous = queryClient.getQueryData<CatalogObservation['assessmentBases']>(baselineKey)
                ?? queryClient.getQueryData<CatalogObservation>(queryKey)?.assessmentBases;
            const update = (await api.get<CatalogUpdate & { canonical: CatalogUpdate }>('/api/bioxp/operator-controls/catalog', {
                signal, timeout: 12_000,
                params: { view: 'assessment', assessment_base: previous?.legacy.revision ?? '',
                    canonical_assessment_base: previous?.canonical.revision ?? '',
                    ...(Number.isInteger(zTargetSteps) ? { z_target_steps: zTargetSteps } : {}) },
            })).data;
            if (update.catalog_view !== 'assessment' || update.canonical?.catalog_view !== 'assessment') throw new Error('Robot catalog split-view release required');
            const legacy = applyBioXpCatalogUpdate(update, previous?.legacy);
            const canonical = applyBioXpCatalogUpdate(update.canonical, previous?.canonical);
            const assessment = { ...legacy.body, canonical: canonical.body } as CatalogAssessment;
            const metadata = await queryClient.fetchQuery<CatalogMetadata>({
                queryKey: ['bioxp', 'operator-definitions', connectionGeneration, assessment.metadata_revision, assessment.canonical.metadata_revision],
                staleTime: Infinity, gcTime: Infinity, retry: false,
                queryFn: async () => (await api.get<CatalogMetadata>('/api/bioxp/operator-controls/catalog', {
                    signal, timeout: 12_000, params: { view: 'metadata' },
                })).data,
            });
            const composed = composeBioXpCatalog(metadata, assessment);
            const assessmentBases = { legacy: legacy.base, canonical: canonical.base };
            queryClient.setQueryData(baselineKey, assessmentBases);
            return { ...composed, assessmentBases };
        },
        enabled: enabled && connectionGeneration > 0,
        gcTime: 0,
        retry: false,
        // Unsupported peers may ignore view=assessment and send the old bulk.
        // Surface that protocol error once, rather than repeat megabyte reads.
        // This affects observation scheduling only, never mutation admission.
        refetchInterval: (query) => {
            const error = query.state.error as { message?: string; response?: { status?: number } } | null;
            if (error?.response?.status === 426 || error?.message === 'Robot catalog split-view release required' || error?.message === 'Robot catalog update release required') return false;
            return enabled && connectionGeneration > 0
                ? query.state.data?.actions.some(action => action.disabled_reason === 'cached_projection_stale') ? 1_000 : 5_000
                : false;
        },
        refetchIntervalInBackground: false,
    });
};

export const BIOXP_Y_RELATIVE_MIN_STEPS = -(2 ** 31);
export const BIOXP_Y_RELATIVE_MAX_STEPS = 2 ** 31 - 1;
export const BIOXP_Y_ABSOLUTE_MIN_STEPS = -(2 ** 31);
export const BIOXP_Y_ABSOLUTE_MAX_STEPS = 2 ** 31 - 1;

function assertCanonicalBoardEpochMap(value: Record<string, number>): void {
    for (const [key, epoch] of Object.entries(value)) {
        if (!/^(0|[1-9][0-9]*)$/.test(key) || !Number.isSafeInteger(epoch) || epoch < 0) {
            throw new Error('Board epoch keys must be canonical nonnegative decimal board IDs');
        }
    }
}

export function assertBioXpOperatorActionV2Request(request: BioXpOperatorActionV2Request): void {
    assertCanonicalBoardEpochMap(request.expected_board_epoch_by_board);
    if (request.action_id === 'oem.deck.move_to_well') {
        if (Object.keys(request.inputs).sort().join(',') !== 'location_id,position_flag,well'
            || !Number.isSafeInteger(request.inputs.location_id)
            || !(typeof request.inputs.well === 'string' || Number.isSafeInteger(request.inputs.well))
            || !Number.isSafeInteger(request.inputs.position_flag)
            || ![0, 1, 2].includes(request.inputs.position_flag)) {
            throw new Error('Well movement inputs must contain explicit location_id, well and position_flag only');
        }
    }
    if (request.action_id === 'oem.deck.move_to_location') {
        const keys = Object.keys(request.inputs).sort().join(',');
        if (keys !== 'camera_offset,target'
            || !/^[A-Z0-9][A-Z0-9_]*$/.test(request.inputs.target)
            || typeof request.inputs.camera_offset !== 'boolean') {
            throw new Error('Deck movement inputs must contain target and camera_offset only');
        }
        if (request.inputs.camera_offset && ['LOC_PARK', 'LOC_TC_BARCODE', 'LOC_RC_BARCODE'].includes(request.inputs.target)) {
            throw new Error('Optional camera offset is only valid for ordinary deck destinations');
        }
    }
    if ((request.action_id === 'oem.x.move_steps' || request.action_id === 'oem.y.move_steps' || request.action_id === 'oem.z.move_steps')
        && (!Number.isSafeInteger(request.inputs.steps)
            || request.inputs.steps < BIOXP_Y_RELATIVE_MIN_STEPS
            || request.inputs.steps > BIOXP_Y_RELATIVE_MAX_STEPS)) {
        throw new Error('Relative steps must fit signed int32');
    }
    if (request.action_id === 'oem.y.move_absolute'
        && (!Number.isSafeInteger(request.inputs.target_steps)
            || request.inputs.target_steps < BIOXP_Y_ABSOLUTE_MIN_STEPS
            || request.inputs.target_steps > BIOXP_Y_ABSOLUTE_MAX_STEPS)) {
        throw new Error('Y absolute target must fit signed int32');
    }
    if ((request.action_id === 'oem.x.move_absolute' || request.action_id === 'oem.z.move_absolute')
        && (!Number.isSafeInteger(request.inputs.position_steps)
            || request.inputs.position_steps < BIOXP_Y_ABSOLUTE_MIN_STEPS
            || request.inputs.position_steps > BIOXP_Y_ABSOLUTE_MAX_STEPS)) {
        throw new Error('Absolute position must fit signed int32');
    }
    if (request.action_id === 'oem.xy.move_absolute'
        && (!Number.isSafeInteger(request.inputs.x)
            || !Number.isSafeInteger(request.inputs.y)
            || request.inputs.x < BIOXP_Y_ABSOLUTE_MIN_STEPS
            || request.inputs.x > BIOXP_Y_ABSOLUTE_MAX_STEPS
            || request.inputs.y < BIOXP_Y_ABSOLUTE_MIN_STEPS
            || request.inputs.y > BIOXP_Y_ABSOLUTE_MAX_STEPS)) {
        throw new Error('XY absolute positions must fit signed int32');
    }
}

interface BioXpOperatorActionV2Envelope {
    expected_connection_generation: number;
    schema_version: 'bioxp.operator_action_request.v2';
    expected_ownership_generation: number;
    idempotency_key: string;
    expected_board_epoch_by_board: Record<string, number>;
}

export type BioXpOperatorActionV2Request =
    | (BioXpOperatorActionV2Envelope & { action_id: 'meta.activate_motion' | 'meta.recover_motion_non_homing'; inputs: Record<string, never> })
    | (BioXpOperatorActionV2Envelope & { action_id: 'oem.x.move_steps' | 'oem.z.move_steps'; inputs: { steps: number } })
    | (BioXpOperatorActionV2Envelope & { action_id: 'oem.x.move_absolute' | 'oem.z.move_absolute'; inputs: { position_steps: number } })
    | (BioXpOperatorActionV2Envelope & { action_id: 'oem.x.manual_panel_home' | 'oem.z.manual_home' | 'oem.z.diagnostic_home_axis' | 'oem.z.clear' | 'oem.xy.home' | 'oem.deck.collect_authority'; inputs: Record<string, never> })
    | (BioXpOperatorActionV2Envelope & { action_id: 'oem.xy.move_absolute'; inputs: { x: number; y: number } })
    | (BioXpOperatorActionV2Envelope & { action_id: 'oem.y.move_steps'; inputs: { steps: number } })
    | (BioXpOperatorActionV2Envelope & { action_id: 'oem.y.move_absolute'; inputs: { target_steps: number } })
    | (BioXpOperatorActionV2Envelope & { action_id: 'oem.y.manual_panel_home'; inputs: Record<string, never> })
    | (BioXpOperatorActionV2Envelope & { action_id: 'oem.deck.move_to_location'; inputs: { target: string; camera_offset: boolean } })
    | (BioXpOperatorActionV2Envelope & { action_id: 'oem.deck.move_to_well'; inputs: { location_id: number; well: string | number; position_flag: 0 | 1 | 2 } });

export interface BioXpOperatorInterruptV1Request {
    expected_connection_generation: number;
    schema_version: 'bioxp.operator_interrupt_request.v1';
    idempotency_key: string;
    reason: string;
    observed_ownership_generation: number | null;
    observed_board_epoch_by_board: Record<string, number>;
}

export interface BioXpOperatorInterruptReceiptV1 {
    schema_version: 'bioxp.operator_interrupt_receipt.v1';
    robot_identity: string;
    ownership_generation: number;
    observed_ownership_generation: number | null;
    observed_board_epoch_by_board: Record<string, number>;
    interrupt_attempt_id: string;
    interrupt_id: string;
    action_id: 'oem.x.stop' | 'oem.y.stop' | 'oem.z.stop' | 'oem.z.abort' | 'oem.abort_all';
    scope: 'x' | 'y' | 'z' | 'aggregate';
    cutoff: number | null;
    active_command_id: string | null;
    active_command_ids: string[];
    global_safety_epoch: number | null;
    x_safety_epoch: number | null;
    y_safety_epoch: number | null;
    z_safety_epoch: number | null;
    oem_abort_latched: boolean;
    controller_stop_attempted: true;
    source_call_completed: boolean;
    source_return_ok: boolean;
    controller_stop_acknowledged: boolean;
    controller_response: unknown;
    controller_response_evidence?: {
        evidence_id: string;
        evidence_kind: 'controller_response';
        content_sha256: string;
        payload_bytes: number;
    } | null;
    error: string | null;
    physical_effect_verified: false;
    persistence_state: 'committed' | 'recovery_required';
    recovery_hold: boolean;
    transition_sequence: number | null;
    terminal_transition_sequences: number[];
    idempotent_replay?: boolean;
}

const useInvokeBioXpOperatorActionV2Mutation = () => {
    const queryClient = useQueryClient();
    return useMutation({
        // Physical submissions must never inherit a retry/offline replay policy.
        gcTime: 0,
        retry: false,
        networkMode: 'always',
        mutationFn: async ({ request }: { request: BioXpOperatorActionV2Request }) => {
            assertBioXpOperatorActionV2Request(request);
            const { action_id: actionId, ...body } = request;
            const path = `/api/bioxp/operator-controls/v2/actions/${encodeURIComponent(actionId)}`;
            return (await ((actionId === 'oem.deck.move_to_location' || actionId === 'oem.deck.move_to_well')
                ? api.post<BioXpOperatorReceiptV2>(path, body, { timeout: 12000 })
                : api.post<BioXpOperatorReceiptV2>(path, body))).data;
        },
        onSettled: (_receipt, _error, variables) => {
            void queryClient.invalidateQueries({ queryKey: statusKey });
            void queryClient.invalidateQueries({ queryKey: operatorCatalogKey });
            void queryClient.invalidateQueries({ queryKey: [...operatorHistoryKey, variables.request.expected_connection_generation] });
        },
    });
};

export const useInvokeBioXpOperatorActionV2 = () => useInvokeBioXpOperatorActionV2Mutation();

export interface BioXpDeckSubmission {
    request: Extract<BioXpOperatorActionV2Request, { action_id: 'oem.deck.move_to_location' | 'oem.deck.move_to_well' }>;
    state: 'submitting' | 'accepted' | 'uncertain' | 'rejected' | 'not_sent';
    commandId?: string;
    receipt?: BioXpOperatorReceiptV2;
    error?: unknown;
}

// Short HTTP admission custody only. Nothing waits for physical completion,
// persists across reload, retries a POST, or claims unsent work is robot queued.
export const useInvokeBioXpDeckActionV2 = (generation = 0, active = false) => {
    const mutation = useInvokeBioXpOperatorActionV2Mutation();
    const [submissions, setSubmissions] = useState<BioXpDeckSubmission[]>([]);
    const scope = useRef({ generation, active });
    scope.current = { generation, active };
    const sending = useRef<string | null>(null);
    const reserved = useRef<string | null>(null);
    const pending = submissions.find(item => item.request.expected_connection_generation === generation
        && item.state === 'submitting') ?? submissions.find(item => item.request.expected_connection_generation === generation
        && item.state === 'uncertain');
    useBioXpOperatorUpdates(generation, active && pending?.state === 'uncertain');
    const lookup = useQuery({
        queryKey: ['bioxp', 'operator-controls', 'v2', 'request', generation, pending?.request.idempotency_key],
        enabled: active && pending?.state === 'uncertain',
        retry: false,
        queryFn: async ({ signal }) => {
            const receipt = (await api.get<BioXpOperatorReceiptV2>(
                `/api/bioxp/operator-controls/v2/requests/${encodeURIComponent(pending!.request.idempotency_key)}`,
                { signal, timeout: 12000, params: { expected_connection_generation: generation } },
            )).data;
            if (receipt.action_id !== pending!.request.action_id || !receipt.command_id)
                throw new Error('Command request identity mismatch; admission remains uncertain');
            return receipt;
        },
        // A committed update wakes identity lookup; never repeat a POST.
        staleTime: Infinity,
        gcTime: 0,
    });
    const update = (key: string, changes: Partial<BioXpDeckSubmission>) =>
        setSubmissions(items => items.map(item => item.request.idempotency_key === key ? { ...item, ...changes } : item));
    useEffect(() => {
        if (!active) return;
        if (pending?.state === 'uncertain' && lookup.data) {
            update(pending.request.idempotency_key, { state: 'accepted', receipt: lookup.data, error: undefined });
        }
    }, [active, pending, lookup.data]);
    useEffect(() => {
        // Never resume unsent requests after connection replacement/disconnect.
        if (sending.current === null) reserved.current = null;
        setSubmissions(items => items.map(item => item.state === 'submitting'
            && (!active || item.request.expected_connection_generation !== generation)
            ? { ...item, state: sending.current === item.request.idempotency_key ? 'uncertain' : 'not_sent' } : item));
    }, [active, generation]);
    useEffect(() => {
        if (!active || pending?.state !== 'submitting' || sending.current !== null) return;
        const request = pending.request;
        const key = request.idempotency_key;
        sending.current = key;
        void mutation.mutateAsync({ request }).then(receipt => {
            sending.current = null;
            if (reserved.current === key) reserved.current = null;
            if (scope.current.generation !== generation || !scope.current.active) {
                update(key, { state: 'uncertain', commandId: receipt?.command_id });
                return;
            }
            if (receipt == null || receipt.action_id !== request.action_id || !receipt.command_id) {
                update(key, { state: 'uncertain', error: new Error('Invalid admission receipt') });
            } else update(key, { state: 'accepted', receipt });
        }, error => {
            sending.current = null;
            if (reserved.current === key) reserved.current = null;
            if (scope.current.generation !== generation || !scope.current.active) {
                update(key, { state: 'uncertain', error, commandId: bioXpPostDispatchCommandIdentity(error)?.commandId });
                return;
            }
            const status = (error as { response?: { status?: number } })?.response?.status;
            // Only explicit client/validation refusals settle non-admission.
            const rejected = status != null && status >= 400 && status < 500 && status !== 408;
            update(key, { state: rejected ? 'rejected' : 'uncertain', error,
                commandId: bioXpPostDispatchCommandIdentity(error)?.commandId });
        });
    }, [active, generation, pending, mutation.mutateAsync]);
    return {
        ...mutation,
        submissions,
        retire: (key: string, receipt: BioXpOperatorReceiptV2) => {
            if (!receipt.terminal) return;
            setSubmissions(items => {
                const settled = items.find(item => item.request.idempotency_key === key
                    && item.state === 'accepted' && item.receipt?.command_id === receipt.command_id);
                if (!settled || settled.receipt === receipt) return items;
                // Success transfers to canonical history. Keep failure/ambiguity visible,
                // but retire its submission observer; selecting it still observes recovery.
                return receipt.status === 'completed'
                    ? items.filter(item => item !== settled)
                    : items.map(item => item === settled ? { ...item, receipt } : item);
            });
        },
        submit: (request: BioXpOperatorActionV2Request) => {
            if (!active || request.expected_connection_generation !== generation
                || (request.action_id !== 'oem.deck.move_to_location' && request.action_id !== 'oem.deck.move_to_well')) return false;
            if (reserved.current !== null || sending.current !== null) return false;
            assertBioXpOperatorActionV2Request(request);
            reserved.current = request.idempotency_key;
            // Capture values, not the mutable picker; no admission batch gate.
            const captured = structuredClone(request);
            setSubmissions(items => [...items, { request: captured, state: 'submitting' }]);
            return true;
        },
    };
};

export interface BioXpPostDispatchCommandIdentity {
    commandId: string;
    statusPath: string;
    retryGuidance: 'do_not_resubmit_reconcile_by_command_id';
}

export const bioXpPostDispatchCommandIdentity = (error: unknown): BioXpPostDispatchCommandIdentity | null => {
    const detail = (error as { response?: { data?: { detail?: unknown } } })?.response?.data?.detail;
    if (detail === null || typeof detail !== 'object' || Array.isArray(detail)) return null;
    const candidate = detail as Record<string, unknown>;
    if (candidate.error !== 'post_dispatch_receipt_validation_failed'
        || typeof candidate.command_id !== 'string'
        || candidate.command_id.length < 1
        || candidate.command_id.length > 160
        || typeof candidate.status_path !== 'string'
        || candidate.status_path.length < 1
        || candidate.status_path.length > 500
        || candidate.retry_guidance !== 'do_not_resubmit_reconcile_by_command_id') {
        return null;
    }
    return {
        commandId: candidate.command_id,
        statusPath: candidate.status_path,
        retryGuidance: candidate.retry_guidance,
    };
};

export const useInterruptBioXpOperatorActionV1 = () => {
    const queryClient = useQueryClient();
    return useMutation({
        mutationFn: async ({ actionId, request }: { actionId: 'oem.x.stop' | 'oem.y.stop' | 'oem.z.stop' | 'oem.abort_all'; request: BioXpOperatorInterruptV1Request }) => {
            assertCanonicalBoardEpochMap(request.observed_board_epoch_by_board);
            return (
                await api.post<BioXpOperatorReceiptV2>(
                    `/api/bioxp/operator-controls/v2/interrupts/${encodeURIComponent(actionId)}`,
                    request,
                )
            ).data;
        },
        onSettled: () => {
            void queryClient.invalidateQueries({ queryKey: operatorCatalogKey });
            void queryClient.invalidateQueries({ queryKey: operatorHistoryKey });
        },
    });
};

export const BIOXP_V2_PENDING_COMPLETION_CLASS = 'issued_pending' as const;

export const bioXpReceiptV2IsNonTerminal = (receipt: BioXpOperatorReceiptV2 | null | undefined): boolean =>
    receipt !== null && receipt !== undefined && receipt.terminal !== true;

/** Validate the additive native decision; it never changes historical outcome. */
export const bioXpDeckRecoveryResolution = (receipt: (BioXpOperatorReceiptV2 & Partial<BioXpOperatorReceiptDetailV2>) | undefined) => {
    const value = receipt?.deck_movement?.recovery_resolution;
    if (value == null) return null;
    if (typeof value !== 'object' || Array.isArray(value)
        || Object.keys(value).sort().join(',') !== 'command_id,decision_id,semantic_state_revision,transition_sequence'
        || typeof value.command_id !== 'string' || value.command_id.length < 1 || value.command_id.length > 160
        || typeof value.decision_id !== 'string' || value.decision_id.length < 1 || value.decision_id.length > 160
        || !Number.isSafeInteger(value.semantic_state_revision) || value.semantic_state_revision < 1
        || !Number.isSafeInteger(value.transition_sequence) || value.transition_sequence < 1
        || value.command_id !== receipt?.command_id || receipt.terminal !== true
        || !['failed', 'ambiguous', 'interrupted', 'stopped', 'aborted', 'cancelled'].includes(receipt.status)
        || !['oem.deck.move_to_location', 'oem.deck.move_to_well', 'oem.deck._mov_execution', 'oem.deck._finite_operation'].includes(receipt.action_id)) {
        throw new Error('Invalid deck recovery resolution');
    }
    return value;
};

export const decodeBioXpReceiptDetailV2 = (receipt: BioXpOperatorReceiptDetailV2, commandId: string) => {
    if (receipt.command_id !== commandId) throw new Error('Receipt command identity mismatch');
    bioXpDeckRecoveryResolution(receipt);
    return receipt;
};

export interface BioXpOperatorUpdates {
    schema_version: 'bioxp.operator_updates.v1';
    source_instance_id: string;
    ownership_generation: number;
    next_after_sequence: number;
    pose_sequence: number;
    changed_command_ids: string[];
    active_command_ids: string[];
    has_more: boolean;
    reset: boolean;
    pose: null | { ownership_generation: number; axes: Array<{
        axis: 'x' | 'y' | 'z'; position_steps: number; observed_at: number;
    }> };
}
export const bioXpOperatorUpdatesKey = (generation: number) => ['bioxp', 'operator-controls', 'updates', generation] as const;

// One cancellable long wait per QueryClient/connection, not one timer per observer.
// The cache owns the cursor; absence of demand stops transport, not retained history.
type OperatorFeed = { users: number; stop: () => void };
const operatorFeeds = new WeakMap<QueryClient, Map<number, OperatorFeed>>();
function subscribeOperatorUpdates(client: QueryClient, generation: number) {
    let feeds = operatorFeeds.get(client);
    if (!feeds) { feeds = new Map(); operatorFeeds.set(client, feeds); }
    let feed = feeds.get(generation);
    if (!feed) {
        const key = bioXpOperatorUpdatesKey(generation);
        let controller: AbortController | null = null;
        let retryTimer: ReturnType<typeof setTimeout> | undefined;
        let stopped = false;
        const finishingReads = new Set<object>();
        const run = async () => {
            if (stopped || document.visibilityState === 'hidden' || controller) return;
            const current = new AbortController();
            controller = current;
            let reconcile = client.getQueryData(key) !== undefined;
            try {
                while (!current.signal.aborted) {
                    const previous = client.getQueryData<BioXpOperatorUpdates>(key);
                    const next = (await api.get<BioXpOperatorUpdates>('/api/bioxp/operator-controls/updates', {
                        signal: current.signal, timeout: 30_000, params: {
                            expected_connection_generation: generation, wait_s: previous?.has_more ? 0 : 25,
                            ...(previous ? { after_sequence: previous.next_after_sequence, after_pose_sequence: previous.pose_sequence } : {}),
                        },
                    })).data;
                    if (current.signal.aborted) break;
                    if (next.schema_version !== 'bioxp.operator_updates.v1') throw new Error('Robot updates release required');
                    const replaced = !!previous && (previous.source_instance_id !== next.source_instance_id
                        || previous.ownership_generation !== next.ownership_generation);
                    const changed = !previous || replaced || next.reset || previous.next_after_sequence !== next.next_after_sequence;
                    client.setQueryData(key, next);
                    const ids = new Set(changed ? next.changed_command_ids : []);
                    // Reconnect/reset reconcile original identities by GET; never replay submissions.
                    const resync = reconcile || replaced || next.reset;
                    reconcile = false;
                    const affected = client.getQueryCache().findAll({ predicate: query => {
                        const q = query.queryKey;
                        if (q[0] !== 'bioxp' || q[1] !== 'operator-controls') return false;
                        if (q[2] === 'history') return q[3] === generation && (resync || ids.size > 0);
                        if (q[2] !== 'v2') return false;
                        if (q[3] === 'request') return q[4] === generation && (resync || ids.size > 0);
                        return (q[3] === 'receipt' || q[3] === 'receipt-detail') && q[5] === generation
                            && (ids.has(String(q[4])) || (resync && (query.state.data !== undefined || query.state.error !== null || query.state.fetchStatus === 'fetching')));
                    } });
                    for (const query of affected) {
                        const filter = { queryKey: query.queryKey, exact: true };
                        // React Query coalesces an initial (no data) GET even with
                        // cancelRefetch. Don't lose a commit arriving during that read.
                        if (query.state.data === undefined && query.state.fetchStatus === 'fetching' && query.promise && !finishingReads.has(query)) {
                            finishingReads.add(query);
                            void query.promise.catch(() => undefined).then(() => {
                                finishingReads.delete(query);
                                if (!current.signal.aborted) void client.invalidateQueries(filter);
                            });
                        }
                        void client.invalidateQueries(filter);
                    }
                }
            } catch (error) {
                if (!current.signal.aborted) {
                    client.getQueryCache().find({ queryKey: key })?.setState({ error: error as Error, status: 'error' });
                    retryTimer = setTimeout(() => { retryTimer = undefined; void run(); }, 2000);
                }
            } finally { if (controller === current) controller = null; }
        };
        const visibility = () => {
            if (document.visibilityState === 'hidden') {
                controller?.abort(); controller = null; finishingReads.clear();
                clearTimeout(retryTimer); retryTimer = undefined;
            } else void run();
        };
        feed = { users: 0, stop: () => {
            stopped = true; controller?.abort(); clearTimeout(retryTimer);
            document.removeEventListener('visibilitychange', visibility);
        } };
        feeds.set(generation, feed);
        document.addEventListener('visibilitychange', visibility);
        void run();
    }
    feed.users++;
    return () => { if (--feed.users === 0) { feed.stop(); feeds.delete(generation); } };
}
export function useBioXpOperatorUpdates(generation: number, enabled = true) {
    const client = useQueryClient();
    const observation = useQuery<BioXpOperatorUpdates>({
        queryKey: bioXpOperatorUpdatesKey(generation), queryFn: skipToken, enabled: false, staleTime: Infinity,
    });
    useEffect(() => {
        if (enabled && generation > 0) return subscribeOperatorUpdates(client, generation);
    }, [client, generation, enabled]);
    return observation;
}

export const useBioXpOperatorReceiptV2 = (
    commandId: string | null,
    connectionGeneration: number,
    enabled = true,
) => {
    useBioXpOperatorUpdates(connectionGeneration, enabled && Boolean(commandId));
    return useQuery({
        queryKey: ['bioxp', 'operator-controls', 'v2', 'receipt', commandId, connectionGeneration],
        queryFn: async ({ signal }) => {
            const receipt = (
            await api.get<BioXpOperatorReceiptV2>(
                `/api/bioxp/operator-controls/v2/receipts/${encodeURIComponent(commandId ?? '')}`,
                { signal, timeout: 12000, params: { detail: false, expected_connection_generation: connectionGeneration } },
            )
            ).data;
            if (receipt.command_id !== commandId) throw new Error('Receipt command identity mismatch');
            return receipt;
        },
        enabled: enabled && Boolean(commandId) && connectionGeneration > 0,
        gcTime: 0,
        retry: false,
        staleTime: Infinity,
        refetchOnWindowFocus: false,
        refetchOnReconnect: false,
    });
};


/** Retained evidence is read only for a mounted typed consumer or explicit request.
 * Compact status owns the cadence; unchanged observations never reread bulk evidence.
 */
export const useBioXpOperatorReceiptDetailV2 = (
    commandId: string | null, connectionGeneration: number, enabled = true, observe = true, detailOpen = true,
) => {
    const status = useBioXpOperatorReceiptV2(commandId, connectionGeneration, enabled && observe);
    const receipt = status.data;
    const detail = useQuery({
        queryKey: ['bioxp', 'operator-controls', 'v2', 'receipt-detail', commandId, connectionGeneration],
        queryFn: async ({ signal }) => decodeBioXpReceiptDetailV2((await api.get<BioXpOperatorReceiptDetailV2>(
            `/api/bioxp/operator-controls/v2/receipts/${encodeURIComponent(commandId ?? '')}`,
            { signal, timeout: 12000, params: { detail: true, expected_connection_generation: connectionGeneration } },
        )).data, commandId ?? ''),
        enabled: enabled && detailOpen && Boolean(commandId) && connectionGeneration > 0 && (!observe || receipt != null),
        gcTime: 0,
        staleTime: observe ? Infinity : 0,
        retry: false,
    });
    // Never hide current lifecycle/denials while retained evidence is loading.
    // No invented empty evidence or proof defaults stand in for an absent detail.
    const data: (BioXpOperatorReceiptV2 & Partial<BioXpOperatorReceiptDetailV2>) | undefined =
        detailOpen && detail.data ? { ...detail.data, ...receipt } : receipt;
    return { ...detail, data, error: (observe && status.error) || detail.error,
        isError: (observe && status.isError) || detail.isError };
};



type BioXpDirectLiquidKind = 'readback' | 'application_plan';
type BioXpDirectLiquidRequest = BioXpPipetteReadbackRequest | BioXpPipetteApplicationPlanRequest;
type BioXpDirectLiquidResult = BioXpPipetteReadback | BioXpPipetteApplicationPlan;
export type BioXpDirectLiquidSubmission = Readonly<{
    requestKind: BioXpDirectLiquidKind;
    idempotencyKey: string;
    request: Readonly<BioXpDirectLiquidRequest & { home_z_after?: boolean }>;
    expectedConnectionGeneration: number;
}>;
export interface BioXpDirectLiquidLookup {
    schema: 'bioxp.direct-liquid.lookup.v1';
    request_kind: BioXpDirectLiquidKind;
    idempotency_key: string;
    lookup_state: 'unknown' | 'pending' | 'incomplete' | 'resolved' | 'conflict' | 'unavailable';
    reason: 'identity_not_found' | 'nonterminal' | 'outcome_unresolved' | 'receipt_incomplete' | 'identity_scope_conflict' | 'store_unavailable' | 'stored_binding_invalid' | null;
    retry_forbidden: true;
    live_query_performed: false;
    record: null | {
        command_id: string; pipette_operation_id: string | null; canonical_request_sha256: string;
        operation: string; entrypoint_id: string; caller_class: string; control_class: string; action_id: string;
        command_status: string; pipette_status: string | null; outcome: string | null; failure_code: string | null;
        ownership_generation: number; connection_generation: number | null;
        requested_inputs: BioXpDirectLiquidSubmission['request']; result: BioXpDirectLiquidResult | null;
    };
}

const directLiquidNormalize = (kind: BioXpDirectLiquidKind, request: BioXpDirectLiquidRequest) => (
    kind === 'readback' ? { include_data: false, ...request } : { home_z_after: true, ...request }
);
const directLiquidEqual = (a: object, b: object) => {
    // All expected request maps are flat scalars; never stringify unknown values.
    const expected = Object.entries(b);
    return Object.keys(a).length === expected.length && expected.every(([key, value]) =>
        Object.hasOwn(a, key) && (a as Record<string, unknown>)[key] === value);
};

// Runtime checks for the existing public direct-liquid DTOs only. Private POST
// envelope metadata is neither required nor learned as browser authority.
const directLiquidObject = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v);
const directLiquidString = (v: unknown, max: number, min = 0): v is string => typeof v === 'string' && v.length >= min && v.length <= max;
const directLiquidStrings = (v: unknown, max: number, min = 0): v is string[] => Array.isArray(v) && v.length >= min && v.length <= max && v.every(x => typeof x === 'string');
const directLiquidKeys = (v: Record<string, unknown>, keys: string[]) => Object.keys(v).every(k => keys.includes(k));
const directLiquidInteger = (v: unknown): v is number => typeof v === 'number' && Number.isInteger(v);
const directLiquidNullableString = (v: unknown, max: number) => v === null || directLiquidString(v, max, 1);

function directLiquidResultValid(v: unknown, s: BioXpDirectLiquidSubmission): v is BioXpDirectLiquidResult {
    if (!directLiquidObject(v) || !directLiquidString(v.receipt_id, 32, 32) || !/^[0-9a-f]{32}$/.test(v.receipt_id)
        || typeof v.ok !== 'boolean' || !directLiquidObject(v.receipt_truth)) return false;
    const truth = v.receipt_truth;
    const truthBooleans = ['semantic_query_response_verified', 'delivery_verified', 'controller_acknowledged',
        'completion_verified', 'hardware_precondition_verified', 'hardware_postcondition_verified'];
    if (!directLiquidKeys(truth, [...truthBooleans, 'physical_effect_verified', 'physical_effect_claim_suppressed'])
        || !truthBooleans.every(k => typeof truth[k] === 'boolean')
        || truth.physical_effect_verified !== false || truth.physical_effect_claim_suppressed !== true) return false;
    if (s.requestKind === 'readback') {
        return typeof v.semantic_ok === 'boolean' && typeof v.available === 'boolean'
            && typeof v.include_data === 'boolean' && 'include_data' in s.request && v.include_data === s.request.include_data
            && v.hardware_truth_level === 'hardware_query' && v.live_query_performed === true
            && v.truth_source === 'live_hardware_queries' && v.channel_count === 4
            && v.oem_source_anchor === 'ClassPipetteCollection constructor/readback; ClassPipette QueryFirmware/Q1/?31/?57/getData'
            && ['delivery_verified', 'controller_acknowledged', 'completion_verified', 'hardware_postcondition_verified', 'physical_effect_verified'].every(k => v[k] === false)
            && Array.isArray(v.channels_constructed_unconditionally) && v.channels_constructed_unconditionally.length === 4
            && v.channels_constructed_unconditionally.every((id, i) => id === i)
            && Array.isArray(v.channels) && v.channels.length === 4 && v.channels.every((c, i) => directLiquidObject(c)
                && directLiquidKeys(c, ['channel', 'semantic_ok', 'firmware', 'status', 'tip', 'pressure', 'data'])
                && c.channel === i && typeof c.semantic_ok === 'boolean'
                && directLiquidObject(c.firmware) && directLiquidObject(c.status) && directLiquidObject(c.tip)
                && (c.pressure === null || directLiquidObject(c.pressure))
                && (v.include_data ? directLiquidObject(c.data) : c.data === null));
    }
    const request = s.request;
    if (!('operation' in request) || v.operation !== request.operation || v.mode !== 'plan_only'
        || !['execution_admitted', 'motion_commanded', 'liquid_mutation_commanded', 'controller_acknowledged',
            'completion_verified', 'physical_effect_verified', 'state_reconciled'].every(k => v[k] === false)
        || !directLiquidObject(v.requested_inputs) || (v.effective_inputs !== undefined && v.effective_inputs !== null)) return false;
    const expected = request.operation === 'load_tip'
        ? { tip_tray: request.tip_tray, tip_well: request.tip_well, tip_type: request.tip_type, tip_location: request.tip_location, home_z_after: request.home_z_after }
        : request.operation === 'detect_fluid' ? { fluid_class: request.fluid_class }
            : request.operation === 'plunger_up' ? { direction: 'up' }
                : request.operation === 'plunger_down' ? { direction: 'down' } : {};
    if (!directLiquidEqual(v.requested_inputs, expected)
        || !Array.isArray(v.steps) || v.steps.length < 1 || v.steps.length > 32
        || !v.steps.every(step => directLiquidObject(step)
            && directLiquidKeys(step, ['action', 'mutates', 'location_id', 'wire_command', 'current', 'owner'])
            && directLiquidString(step.action, 240, 1) && typeof step.mutates === 'boolean'
            && typeof step.owner === 'string' && ['deck', 'gantry', 'z', 'pressure', 'pipette', 'machine_state'].includes(step.owner)
            && ['location_id', 'current'].every(k => step[k] === undefined || step[k] === null || directLiquidInteger(step[k]))
            && (step.wire_command === undefined || step.wire_command === null || directLiquidString(step.wire_command, 120)))
        || !directLiquidObject(v.dependencies) || !directLiquidStrings(v.required_dependencies, 6, 1)
        || !directLiquidStrings(v.missing_dependencies, 6) || !directLiquidStrings(v.dependency_blockers, 64)
        || !directLiquidStrings(v.required_completion_evidence, 32) || !directLiquidObject(v.constants)
        || !directLiquidString(v.oem_source_anchor, 1000, 1)) return false;
    const required = v.required_dependencies;
    if (Object.keys(v.dependencies).length < 1 || Object.keys(v.dependencies).length > 6
        || Object.keys(v.dependencies).some(k => !required.includes(k))
        || required.some(k => !Object.hasOwn(v.dependencies as object, k))
        || v.missing_dependencies.some(k => !required.includes(k))
        || !Object.values(v.dependencies).every(d => directLiquidObject(d)
            && directLiquidKeys(d, ['bound', 'authority', 'generation', 'state', 'blockers'])
            && typeof d.bound === 'boolean' && directLiquidInteger(d.generation) && directLiquidObject(d.state)
            && (d.authority === undefined || d.authority === null || directLiquidString(d.authority, 240))
            && directLiquidStrings(d.blockers, 32))) return false;
    const satisfied = v.missing_dependencies.length === 0 && v.dependency_blockers.length === 0;
    return v.dependencies_satisfied === satisfied && v.ok === satisfied
        && v.blocker === (satisfied ? 'physical_pipette_execution_not_authorized' : 'application_dependencies_unbound');
}

function directLiquidLookupValid(v: unknown, status: number, s: BioXpDirectLiquidSubmission): v is BioXpDirectLiquidLookup {
    if (!directLiquidObject(v) || v.schema !== 'bioxp.direct-liquid.lookup.v1' || v.request_kind !== s.requestKind
        || v.idempotency_key !== s.idempotencyKey || v.live_query_performed !== false || v.retry_forbidden !== true
        || !directLiquidKeys(v, ['schema', 'request_kind', 'idempotency_key', 'lookup_state', 'reason', 'retry_forbidden', 'live_query_performed', 'record'])) return false;
    const reasons: Record<string, unknown[]> = { unknown: ['identity_not_found'], pending: ['nonterminal'],
        incomplete: ['outcome_unresolved', 'receipt_incomplete'], resolved: [null], conflict: ['identity_scope_conflict'],
        unavailable: ['store_unavailable', 'stored_binding_invalid'] };
    if (typeof v.lookup_state !== 'string' || !Object.hasOwn(reasons, v.lookup_state)
        || !reasons[v.lookup_state].includes(v.reason)
        || status !== (v.lookup_state === 'conflict' ? 409 : v.lookup_state === 'unavailable' ? 503 : 200)) return false;
    if (['unknown', 'conflict', 'unavailable'].includes(v.lookup_state)) return v.record === null;
    const r = v.record;
    if (!directLiquidObject(r) || !directLiquidKeys(r, ['command_id', 'pipette_operation_id', 'canonical_request_sha256',
        'operation', 'entrypoint_id', 'caller_class', 'control_class', 'action_id', 'command_status', 'pipette_status',
        'outcome', 'failure_code', 'ownership_generation', 'connection_generation', 'requested_inputs', 'result'])
        || !['command_id', 'operation', 'entrypoint_id', 'caller_class', 'control_class'].every(k => directLiquidString(r[k], 160, 1))
        || !directLiquidString(r.action_id, 240, 1) || !directLiquidString(r.command_status, 120, 1)
        || !directLiquidNullableString(r.pipette_operation_id, 160) || !directLiquidNullableString(r.pipette_status, 120)
        || !directLiquidNullableString(r.outcome, 120) || !directLiquidNullableString(r.failure_code, 240)
        || !directLiquidString(r.canonical_request_sha256, 64, 64) || !/^[0-9a-f]{64}$/.test(r.canonical_request_sha256)
        || !directLiquidInteger(r.ownership_generation) || r.ownership_generation < 0
        || !(r.connection_generation === null || (directLiquidInteger(r.connection_generation) && r.connection_generation >= 0))
        || !directLiquidObject(r.requested_inputs) || !directLiquidEqual(r.requested_inputs, s.request)
        || (r.result !== null && !directLiquidResultValid(r.result, s))) return false;
    const plan = s.requestKind === 'application_plan';
    const operation = plan && 'operation' in s.request ? 'application_plan:' + s.request.operation : 'live_readback';
    if (r.operation !== operation || r.action_id !== 'pipette.' + operation
        || r.entrypoint_id !== (plan ? 'legacy.record' : 'direct.liquid.readback')
        || r.caller_class !== (plan ? 'legacy' : 'direct_api') || r.control_class !== (plan ? 'pipette_state_command' : 'hardware_query')
        || (r.pipette_operation_id === null) !== (r.pipette_status === null)
        || (v.lookup_state !== 'resolved' && r.result !== null)) return false;
    const pending = ['reserved', 'queued', 'admitted', 'dispatched', 'acknowledged', 'executing', 'running', 'blocked'];
    const terminal = ['completed', 'observed', 'failed', 'rejected', 'cleared', 'cancelled'];
    if (v.lookup_state === 'pending' && (!pending.includes(r.command_status) || !pending.includes(String(r.pipette_status)))) return false;
    if (v.lookup_state === 'resolved' && (r.outcome === null || !terminal.includes(r.command_status)
        || r.command_status !== r.pipette_status || (['completed', 'observed'].includes(r.command_status) && r.result === null))) return false;
    return !(v.lookup_state === 'incomplete' && v.reason === 'receipt_incomplete' && r.pipette_operation_id !== null
        && !(terminal.includes(r.command_status) && r.command_status === r.pipette_status));
}

// Mounted owner only: no reload persistence or reconnect reassociation.
function useDirectLiquid<Request extends BioXpDirectLiquidRequest, Result extends BioXpDirectLiquidResult>(
    kind: BioXpDirectLiquidKind, path: string, generation: number, connected: boolean,
) {
    const [submission, setSubmission] = useState<BioXpDirectLiquidSubmission | null>(null);
    const [lookup, setLookup] = useState<BioXpDirectLiquidLookup | null>(null);
    const [data, setData] = useState<Result | undefined>();
    const [recover, setRecover] = useState(false);
    const [identityConflict, setIdentityConflict] = useState(false);
    const detachedOwners = useRef(new WeakSet<BioXpDirectLiquidSubmission>());
    const retainedKeys = useRef(new Set<string>());
    const [retainedHistory, setRetainedHistory] = useState<BioXpDirectLiquidSubmission[]>([]);
    const owner = useRef(submission);
    const context = useRef({ generation, connected });
    context.current = { generation, connected };
    const sent = useRef<BioXpDirectLiquidSubmission | null>(null);
    const learned = useRef<{ command?: string; pipette?: string; digest?: string; receipt?: string }>({});
    const mounted = useRef(true);
    useEffect(() => { mounted.current = true; return () => { mounted.current = false; }; }, []);
    // A disconnect is terminal for this owner, including same-generation reconnect.
    if (submission && (!connected || generation !== submission.expectedConnectionGeneration)) detachedOwners.current.add(submission);
    const detached = Boolean(submission && detachedOwners.current.has(submission));
    const owns = (s: BioXpDirectLiquidSubmission) => mounted.current && owner.current === s
        && context.current.connected && context.current.generation === s.expectedConnectionGeneration && !detachedOwners.current.has(s);
    const mutation = useMutation({
        mutationFn: async (s: BioXpDirectLiquidSubmission) => {
            // BMS POST union stays unchanged; home_z_after is a robot default for non-load plans.
            const body = { ...s.request };
            if ('operation' in body && body.operation !== 'load_tip') delete body.home_z_after;
            const result = (await api.post<unknown>(path, body, {
                headers: { 'Idempotency-Key': s.idempotencyKey },
                params: { expected_connection_generation: s.expectedConnectionGeneration },
            })).data;
            if (!directLiquidResultValid(result, s)) throw new Error('Invalid or mismatched direct-liquid result; reconcile stored evidence only');
            return result as Result;
        },
        retry: false,
        onSuccess: (result, s) => {
            if (!owns(s)) return;
            if (!result.receipt_id || (learned.current.receipt && learned.current.receipt !== result.receipt_id)) {
                setIdentityConflict(true); setData(undefined); setLookup(null); setRecover(true); return;
            }
            learned.current.receipt = result.receipt_id;
            setData(result);
        },
        onError: (_error, s) => { if (owns(s)) setRecover(true); },
    });
    // Publish the immutable owner in a committed render before transport starts.
    useEffect(() => {
        if (submission && sent.current !== submission && !detached) {
            sent.current = submission;
            mutation.mutate(submission);
        }
    }, [submission, detached]);
    const query = useQuery({
        queryKey: ['bioxp', 'direct-liquid-request', submission?.expectedConnectionGeneration, kind, submission?.idempotencyKey],
        queryFn: async () => {
            const s = submission!;
            const response = await api.get<unknown>('/api/bioxp/operator-controls/pipettes/requests', {
                params: { request_kind: s.requestKind, expected_connection_generation: s.expectedConnectionGeneration },
                headers: { 'Idempotency-Key': s.idempotencyKey },
                validateStatus: (status) => status === 200 || status === 409 || status === 503,
            });
            const value = response.data;
            if (!owns(s)) return null;
            if (!directLiquidLookupValid(value, response.status, s)) {
                setIdentityConflict(true); setData(undefined); setLookup(null); return null;
            }
            const r = value.record;
            const prior = learned.current;
            const mismatch = value.schema !== 'bioxp.direct-liquid.lookup.v1' || value.request_kind !== s.requestKind
                || value.idempotency_key !== s.idempotencyKey || value.live_query_performed !== false || value.retry_forbidden !== true
                || (r && (!directLiquidEqual(r.requested_inputs, s.request)
                    || (r.outcome === null ? !['pending', 'incomplete'].includes(value.lookup_state)
                        : typeof r.outcome !== 'string' || r.outcome.length < 1 || r.outcome.length > 120)
                    || (prior.command && prior.command !== r.command_id)
                    || (prior.pipette && prior.pipette !== r.pipette_operation_id)
                    || (prior.digest && prior.digest !== r.canonical_request_sha256)
                    || (prior.receipt && r.result && prior.receipt !== r.result.receipt_id)));
            if (mismatch) { setIdentityConflict(true); setData(undefined); setLookup(null); return null; }
            if (r) learned.current = { command: r.command_id, pipette: r.pipette_operation_id ?? prior.pipette,
                digest: r.canonical_request_sha256, receipt: r.result?.receipt_id ?? prior.receipt };
            setLookup(value);
            setData(value.lookup_state === 'resolved' && r?.result ? r.result as Result : undefined);
            return value;
        },
        enabled: Boolean(submission) && recover && !detached && !identityConflict,
        retry: false, gcTime: 0, refetchOnWindowFocus: false, refetchOnReconnect: false,
        refetchInterval: (q) => !detached && !identityConflict && q.state.data?.lookup_state === 'pending' ? 500 : false,
        refetchIntervalInBackground: false,
    });
    const start = (input: Request & { idempotencyKey?: string }, explicitlyNew = false) => {
        if (generation < 1 || !connected) return;
        if (owner.current && !explicitlyNew) return;
        const previousOwner = owner.current;
        const { idempotencyKey, ...body } = input;
        const key = idempotencyKey ?? crypto.randomUUID();
        if (!/^[A-Za-z0-9][A-Za-z0-9._:/-]{7,199}$/.test(key)) throw new Error('Invalid direct-liquid identity');
        if (retainedKeys.current.has(key)) throw new Error('Direct-liquid identity already retained');
        const request = Object.freeze(JSON.parse(JSON.stringify(directLiquidNormalize(kind, body as Request)))) as BioXpDirectLiquidSubmission['request'];
        const next = Object.freeze({ requestKind: kind, idempotencyKey: key, request, expectedConnectionGeneration: generation });
        retainedKeys.current.add(key);
        if (previousOwner) setRetainedHistory((previous) => [...previous, previousOwner]);
        owner.current = next; learned.current = {}; setLookup(null); setData(undefined);
        setRecover(false); setIdentityConflict(false); mutation.reset(); setSubmission(next);
    };
    return { isPending: mutation.isPending, error: mutation.error, data: detached || identityConflict ? undefined : data,
        mutate: (input: Request & { idempotencyKey?: string }) => start(input),
        newOperation: (input: Request & { idempotencyKey?: string }) => start(input, true),
        submission, retainedHistory, lookup, detached, identityConflict,
        recoveryError: query.error,
        refreshRecovery: async () => { if (submission && !detached && !identityConflict) await query.refetch({ cancelRefetch: false }); },
    };
}

export const useReadBioXpPipetteReadback = (generation = 0, connected = true) =>
    useDirectLiquid<BioXpPipetteReadbackRequest, BioXpPipetteReadback>('readback', '/api/bioxp/operator-controls/pipettes/readback', generation, connected);

export const useBioXpPipetteApplicationStatus = (connectionGeneration: number, enabled = true) => useQuery({
    queryKey: ['bioxp', 'operator-controls', 'pipettes', 'application-status', connectionGeneration, enabled],
    queryFn: async () => (
        await api.get<BioXpPipetteApplicationStatus>('/api/bioxp/operator-controls/pipettes/application/status')
    ).data,
    enabled: enabled && connectionGeneration > 0,
    gcTime: 0,
    retry: false,
});

export const usePlanBioXpPipetteApplication = (generation = 0, connected = true) =>
    useDirectLiquid<BioXpPipetteApplicationPlanRequest, BioXpPipetteApplicationPlan>('application_plan', '/api/bioxp/operator-controls/pipettes/application/plan', generation, connected);

export const useBioXpOperatorActionAdmission = (
    actionId: string | null,
    connectionGeneration: number,
    ownershipGeneration: number,
    inputs: Record<string, unknown> | null,
    enabled = true,
    lifecycleState?: string | null,
) => useQuery({
    queryKey: ['bioxp', 'operator-controls', 'admission', actionId, connectionGeneration, ownershipGeneration, inputs, lifecycleState ?? null],
    queryFn: async () => (
        await api.post<BioXpOperatorAdmission>(
            `/api/bioxp/operator-controls/actions/${encodeURIComponent(actionId ?? '')}/admission`,
            {
                ...bioXpOperatorGenerationPayload(connectionGeneration, ownershipGeneration),
                inputs: inputs ?? {},
            },
        )
    ).data,
    enabled: enabled && Boolean(actionId) && connectionGeneration > 0 && ownershipGeneration > 0 && inputs !== null,
    retry: false,
});

export const bioXpReceiptIsNonTerminal = (receipt: unknown): boolean => {
    if (!receipt || typeof receipt !== 'object' || !('status' in receipt)) return false;
    const status = receipt.status;
    return typeof status === 'string'
        && status !== 'completed'
        && status !== 'failed'
        && status !== 'rejected'
        && status !== 'blocked'
        && status !== 'cleared';
};

export const useBioXpOperatorActionHistory = (
    connectionGeneration: number,
    enabled = true,
    limit = 100,
    cursor: string | null = null,
) => {
    useBioXpOperatorUpdates(connectionGeneration, enabled);
    return useQuery({
    queryKey: [...operatorHistoryKey, connectionGeneration, limit, cursor],
    queryFn: async ({ signal }) => (
        await api.get<BioXpOperatorActionHistory>(`/api/bioxp/operator-controls/history?limit=${limit}`, {
            signal, params: cursor === null ? undefined : { cursor },
        })
    ).data,
    enabled: enabled && connectionGeneration > 0,
    gcTime: 0,
    retry: false,
    staleTime: Infinity,
    refetchOnWindowFocus: false,
    refetchOnReconnect: false,
});
};

export const useBioXpOperatorReportSummary = (
    connectionGeneration: number,
    enabled = true,
    filters?: BioXpOperatorReportFilters,
) => useQuery({
    queryKey: [...operatorReportSummaryKey, connectionGeneration, enabled, filters ?? null],
    queryFn: async () => (await api.get<BioXpOperatorReportSummary>('/api/bioxp/operator-controls/reports/summary', {
        params: operatorReportParams(filters),
    })).data,
    enabled: enabled && connectionGeneration > 0,
    retry: false,
    refetchInterval: enabled && connectionGeneration > 0 ? 15_000 : false,
});

export const useBioXpOperatorReportCommands = (
    connectionGeneration: number,
    enabled = true,
    limit = 25,
    cursor: string | null = null,
    filters?: BioXpOperatorReportFilters,
) => useQuery({
    queryKey: [...operatorReportCommandsKey, connectionGeneration, enabled, limit, cursor, filters ?? null],
    queryFn: async () => (await api.get<BioXpOperatorReportCommands>('/api/bioxp/operator-controls/reports/commands', {
        params: operatorReportParams(filters, limit, cursor),
    })).data,
    enabled: enabled && connectionGeneration > 0,
    retry: false,
    refetchInterval: enabled && connectionGeneration > 0 ? 15_000 : false,
});

export const useBioXpOperatorReportCommandDetail = (commandId: string | null, enabled = true) => useQuery({
    queryKey: ['bioxp', 'operator-reports', 'command-detail', commandId],
    queryFn: async () => (await api.get<BioXpOperatorReportCommandDetail>(
        `/api/bioxp/operator-controls/reports/commands/${encodeURIComponent(commandId ?? '')}`,
    )).data,
    enabled: enabled && Boolean(commandId),
    retry: false,
});

export const useBioXpOperatorReportCommandTransitions = (commandId: string | null, cursor: string | null = null, enabled = true) => useQuery({
    queryKey: ['bioxp', 'operator-reports', 'command-transitions', commandId, cursor],
    queryFn: async () => (await api.get<BioXpOperatorReportTransitionPage>(
        `/api/bioxp/operator-controls/reports/commands/${encodeURIComponent(commandId ?? '')}/transitions`,
        { params: operatorReportParams(undefined, 50, cursor) },
    )).data,
    enabled: enabled && Boolean(commandId),
    retry: false,
});

export const useBioXpOperatorReportCommandEvidence = (commandId: string | null, cursor: string | null = null, enabled = true) => useQuery({
    queryKey: ['bioxp', 'operator-reports', 'command-evidence', commandId, cursor],
    queryFn: async () => (await api.get<BioXpOperatorReportEvidencePage>(
        `/api/bioxp/operator-controls/reports/commands/${encodeURIComponent(commandId ?? '')}/evidence`,
        { params: operatorReportParams(undefined, 50, cursor) },
    )).data,
    enabled: enabled && Boolean(commandId),
    retry: false,
});

export const useBioXpOperatorReportPipetteDetail = (pipetteOperationId: string | null, enabled = true) => useQuery({
    queryKey: ['bioxp', 'operator-reports', 'pipette-detail', pipetteOperationId],
    queryFn: async () => (await api.get<BioXpOperatorReportPipette>(
        `/api/bioxp/operator-controls/reports/pipette/${encodeURIComponent(pipetteOperationId ?? '')}`,
    )).data,
    enabled: enabled && Boolean(pipetteOperationId),
    retry: false,
});

export const useBioXpOperatorReportPipetteChannels = (pipetteOperationId: string | null, cursor: string | null = null, enabled = true) => useQuery({
    queryKey: ['bioxp', 'operator-reports', 'pipette-channels', pipetteOperationId, cursor],
    queryFn: async () => (await api.get<BioXpOperatorReportChannelPage>(
        `/api/bioxp/operator-controls/reports/pipette/${encodeURIComponent(pipetteOperationId ?? '')}/channels`,
        { params: operatorReportParams(undefined, 50, cursor) },
    )).data,
    enabled: enabled && Boolean(pipetteOperationId),
    retry: false,
});

export const useBioXpOperatorReportPipetteExchanges = (pipetteOperationId: string | null, cursor: string | null = null, enabled = true) => useQuery({
    queryKey: ['bioxp', 'operator-reports', 'pipette-exchanges', pipetteOperationId, cursor],
    queryFn: async () => (await api.get<BioXpOperatorReportExchangePage>(
        `/api/bioxp/operator-controls/reports/pipette/${encodeURIComponent(pipetteOperationId ?? '')}/exchanges`,
        { params: operatorReportParams(undefined, 50, cursor) },
    )).data,
    enabled: enabled && Boolean(pipetteOperationId),
    retry: false,
});

export const useBioXpOperatorReportEventDetail = (eventId: number | null, enabled = true) => useQuery({
    queryKey: ['bioxp', 'operator-reports', 'event-detail', eventId],
    queryFn: async () => (await api.get<BioXpOperatorReportEventDetail>(
        `/api/bioxp/operator-controls/reports/events/${encodeURIComponent(String(eventId ?? ''))}`,
    )).data,
    enabled: enabled && eventId !== null,
    retry: false,
});

export const useBioXpOperatorReportPressureDetail = (streamSessionId: string | null, enabled = true) => useQuery({
    queryKey: ['bioxp', 'operator-reports', 'pressure-detail', streamSessionId],
    queryFn: async () => (await api.get<BioXpOperatorReportPressureDetail>(
        `/api/bioxp/operator-controls/reports/pressure-streams/${encodeURIComponent(streamSessionId ?? '')}`,
    )).data,
    enabled: enabled && Boolean(streamSessionId),
    retry: false,
});

export const useBioXpOperatorReportPressureSamples = (streamSessionId: string | null, cursor: string | null = null, enabled = true) => useQuery({
    queryKey: ['bioxp', 'operator-reports', 'pressure-samples', streamSessionId, cursor],
    queryFn: async () => (await api.get<BioXpOperatorReportPressureSamplePage>(
        `/api/bioxp/operator-controls/reports/pressure-streams/${encodeURIComponent(streamSessionId ?? '')}/samples`,
        { params: operatorReportParams(undefined, 50, cursor) },
    )).data,
    enabled: enabled && Boolean(streamSessionId),
    retry: false,
});

export const useBioXpOperatorReportPipette = (
    connectionGeneration: number,
    enabled = true,
    filters?: BioXpOperatorReportFilters,
) => useQuery({
    queryKey: ['bioxp', 'operator-reports', 'pipette', connectionGeneration, filters ?? null],
    queryFn: async () => (await api.get<BioXpOperatorReportPipettePage>('/api/bioxp/operator-controls/reports/pipette', {
        params: operatorReportParams(filters, 20),
    })).data,
    enabled: enabled && connectionGeneration > 0,
    retry: false,
});

export const useBioXpOperatorReportEvents = (
    connectionGeneration: number,
    enabled = true,
    filters?: BioXpOperatorReportFilters,
) => useQuery({
    queryKey: ['bioxp', 'operator-reports', 'events', connectionGeneration, filters ?? null],
    queryFn: async () => (await api.get<BioXpOperatorReportEvents>('/api/bioxp/operator-controls/reports/events', {
        params: operatorReportParams(filters, 20),
    })).data,
    enabled: enabled && connectionGeneration > 0,
    retry: false,
    refetchInterval: enabled && connectionGeneration > 0 ? 15_000 : false,
});

export const useBioXpOperatorReportPressureStreams = (
    connectionGeneration: number,
    enabled = true,
    filters?: BioXpOperatorReportFilters,
) => useQuery({
    queryKey: ['bioxp', 'operator-reports', 'pressure', connectionGeneration, filters ?? null],
    queryFn: async () => (await api.get<BioXpOperatorReportPressureStreams>('/api/bioxp/operator-controls/reports/pressure-streams', {
        params: operatorReportParams(filters, 20),
    })).data,
    enabled: enabled && connectionGeneration > 0,
    retry: false,
});

export const useCreateBioXpOperatorReportExport = () => useMutation({
    mutationFn: async ({ format, filters, limit = 1000 }: {
        format: 'json' | 'csv';
        filters?: BioXpOperatorReportFilters;
        limit?: number;
    }) => (await api.post<BioXpOperatorReportExport>('/api/bioxp/operator-controls/reports/exports', {
        format,
        limit,
        ...(filters ?? {}),
    })).data,
});

export const useBioXpOperatorReportExports = (
    connectionGeneration: number,
    enabled = true,
) => useQuery({
    queryKey: ['bioxp', 'operator-reports', 'exports', connectionGeneration],
    queryFn: async () => (await api.get<BioXpOperatorReportExportList>(
        '/api/bioxp/operator-controls/reports/exports',
        { params: { limit: 20 } },
    )).data,
    enabled: enabled && connectionGeneration > 0,
    retry: false,
});

export async function getBioXpCameraStatus(connectionGeneration: number) {
    const startedAt = performance.now();
    const data = (await api.get<BioXpCameraStatus>(BIOXP_CAMERA_ENDPOINTS.status, {
        params: { expected_generation: connectionGeneration },
    })).data;
    const receivedAtMonotonicMs = performance.now();
    return { ...data, requestConnectionGeneration: connectionGeneration,
        requestElapsedMs: Math.max(0, receivedAtMonotonicMs - startedAt), receivedAtMonotonicMs };
}

export const useBioXpCameraStatus = (
    connectionGeneration: number | null,
    enabled = true,
    interval: number | false = 2_000,
) => useQuery({
    queryKey: ['bioxp', 'camera', 'status', connectionGeneration],
    queryFn: async () => {
        if (connectionGeneration === null) throw new Error('An active BioXP connection generation is required');
        return getBioXpCameraStatus(connectionGeneration);
    },
    enabled: enabled && connectionGeneration !== null,
    retry: false,
    refetchInterval: enabled ? interval : false,
});

export const useBioXpCameraStreamState = (
    connectionGeneration: number | null,
    enabled = true,
) => useQuery({
    queryKey: ['bioxp', 'camera', 'stream', connectionGeneration],
    queryFn: async () => {
        if (connectionGeneration === null) throw new Error('An active BioXP connection generation is required');
        return (await api.get<BioXpCameraStream>(BIOXP_CAMERA_ENDPOINTS.streamState, {
            params: { expected_generation: connectionGeneration },
        })).data;
    },
    enabled: enabled && connectionGeneration !== null,
    retry: false,
    // Visible idle panes discover another client's stream without 2s idle polling.
    refetchInterval: query => enabled ? (query.state.data?.active ? 2_000 : 15_000) : false,
});

export async function startBioXpCameraStream(connectionGeneration: number): Promise<BioXpCameraStream> {
    return (await api.post<BioXpCameraStream>(BIOXP_CAMERA_ENDPOINTS.streamStart, {
        expected_generation: connectionGeneration,
    })).data;
}

export async function stopBioXpCameraStream(connectionGeneration: number): Promise<BioXpCameraStream> {
    return (await api.post<BioXpCameraStream>(BIOXP_CAMERA_ENDPOINTS.streamStop, {
        expected_generation: connectionGeneration,
    })).data;
}

export function buildBioXpCameraMjpegUrl(connectionGeneration: number, streamId?: string | null): string {
    const owner = streamId ? `&stream_id=${encodeURIComponent(streamId)}` : '';
    return `${BIOXP_CAMERA_ENDPOINTS.mjpeg}?expected_generation=${encodeURIComponent(String(connectionGeneration))}${owner}`;
}

export async function fetchBioXpCameraFrame(connectionGeneration: number): Promise<BioXpCameraImage> {
    const response = await api.get<Blob>(BIOXP_CAMERA_ENDPOINTS.latest, {
        params: { expected_generation: connectionGeneration },
        responseType: 'blob',
    });
    return cameraImageFromResponse(response);
}

export async function captureBioXpCameraSnapshot(connectionGeneration: number): Promise<BioXpCameraImage> {
    const response = await api.post<Blob>(
        BIOXP_CAMERA_ENDPOINTS.snapshot,
        { expected_generation: connectionGeneration },
        { responseType: 'blob' },
    );
    return cameraImageFromResponse(response);
}





const useRefreshMutation = <TVariables, TData>(
    mutationFn: (variables: TVariables) => Promise<TData>,
) => {
    const queryClient = useQueryClient();
    return useMutation({
        mutationFn,
        onSuccess: () => {
            void Promise.all([
                queryClient.invalidateQueries({ queryKey: statusKey }),

                queryClient.invalidateQueries({ queryKey: operatorCatalogKey }),
                queryClient.invalidateQueries({ queryKey: operatorHistoryKey }),
            ]);
        },
    });
};



export const useConnectBioXp = () => useRefreshMutation(
    async () => (await api.post<BioXpConnectionSnapshot>('/api/bioxp/connection/connect')).data,
);

export const useDisconnectBioXp = () => useRefreshMutation(
    async () => (await api.post<BioXpConnectionSnapshot>('/api/bioxp/connection/disconnect')).data,
);




const workflowJobsKey = ['bioxp', 'protocols', 'jobs'] as const;
export const useBioXpWorkflowJobs = (generation: number, enabled: boolean) => useQuery({
    queryKey: [...workflowJobsKey, generation],
    queryFn: async () => (await api.get<{ rows: (BioXpWorkflowJob | BioXpWorkflowJobSummary)[] }>('/api/bioxp/protocols/jobs', {
        params: { expected_connection_generation: generation },
    })).data.rows,
    enabled: enabled && generation > 0,
    retry: false,
    // Discovery must continue even when this browser has no active job.
    refetchInterval: enabled ? 10_000 : false,
    refetchIntervalInBackground: false,
});
export const useBioXpWorkflowJob = (jobId: string | null, generation: number, enabled: boolean) => useQuery({
    queryKey: [...workflowJobsKey, generation, jobId],
    queryFn: async () => (await api.get<BioXpWorkflowJob>(`/api/bioxp/protocols/jobs/${encodeURIComponent(jobId!)}`, {
        params: { expected_connection_generation: generation },
    })).data,
    enabled: enabled && generation > 0 && jobId !== null,
    retry: false,
    refetchInterval: (query) => {
        if (!enabled) return false;
        const job = query.state.data;
        const command = job?.command;
        const workflow = job?.execution?.runtime_state.workflow;
        const settled = command?.command_id === jobId && command.terminal
            && workflow?.command_id === jobId && workflow.phase === 'terminal';
        return settled ? false : 2_000;
    },
    refetchIntervalInBackground: false,
});
// The monitor consumes control/review truth, never source trays or retained
// action evidence. Explicit detail/clone and their query keys remain full.
export const useBioXpWorkflowJobObservation = (jobId: string | null, generation: number, enabled: boolean, facade = false) => useQuery({
    queryKey: [...workflowJobsKey, generation, jobId, 'observation'],
    queryFn: async () => (await api.get<BioXpWorkflowJobObservation | BioXpWorkflowJob>(`${facade ? '/api/bioxp/methods/runs' : '/api/bioxp/protocols/jobs'}/${encodeURIComponent(jobId!)}`, {
        params: { expected_connection_generation: generation, observation: true },
    })).data,
    enabled: enabled && generation > 0 && jobId !== null,
    retry: false,
    refetchInterval: (query) => {
        if (!enabled) return false;
        const job = query.state.data;
        // Older peers can ignore the projection selector. Preserve their
        // original outcome cadence; compactness never decides settlement.
        const command = job?.command;
        const workflow = job?.execution?.runtime_state.workflow;
        const settled = command?.command_id === jobId && command.terminal
            && workflow?.command_id === jobId && workflow.phase === 'terminal';
        return settled ? false : 2_000;
    },
    refetchIntervalInBackground: false,
});
export const useSubmitBioXpProtocol = () => useMutation({
    mutationFn: async (request: BioXpWorkflowSubmission) => (
        await api.post<BioXpWorkflowJob>('/api/bioxp/protocols/submit', request)
    ).data,
    retry: false,
});
export const useControlBioXpWorkflow = (facade = false) => useMutation({
    mutationFn: async ({ jobId, request }: { jobId: string; request: BioXpWorkflowControlRequest }) => (
        await api.post<BioXpWorkflowControlResponse>(`${facade ? '/api/bioxp/methods/runs' : '/api/bioxp/protocols/jobs'}/${encodeURIComponent(jobId)}/control`, request)
    ).data,
    retry: false,
});
export const useReviewBioXpWorkflow = (facade = false) => useMutation({
    mutationFn: async ({ jobId, request }: { jobId: string; request: BioXpWorkflowReviewRequest }) => (
        await api.post<BioXpWorkflowJob>(`${facade ? '/api/bioxp/methods/runs' : '/api/bioxp/protocols/jobs'}/${encodeURIComponent(jobId)}/review`, request)
    ).data,
    retry: false,
});


const refreshBioXpHistoryCaches = (queryClient: QueryClient, generation: number) => {
    // The robot alone creates history rows and cursors. Never splice a native
    // mutation receipt into a paginated history page or invent its ordering.
    void queryClient.invalidateQueries({ queryKey: [...operatorHistoryKey, generation] });
};

export const useInvokeBioXpOperatorAction = (lane: 'normal' | 'stop' = 'normal') => {
    const queryClient = useQueryClient();
    return useMutation({
        mutationKey: ['bioxp', 'operator-action', lane],
        mutationFn: async ({ actionId, connectionGeneration, ownershipGeneration, inputs }: {
            actionId: string;
            connectionGeneration: number;
            ownershipGeneration: number;
            inputs: Record<string, unknown>;
        }) => (
            await api.post<BioXpOperatorLiveActionReceipt>(
                `/api/bioxp/operator-controls/actions/${encodeURIComponent(actionId)}`,
                {
                    ...bioXpOperatorGenerationPayload(connectionGeneration, ownershipGeneration),
                    idempotency_key: crypto.randomUUID(),
                    inputs,
                },
            )
        ).data,
        onMutate: async () => {
            await queryClient.cancelQueries({ queryKey: operatorHistoryKey });
        },
        onSettled: () => {
            void queryClient.invalidateQueries({ queryKey: operatorCatalogKey });
        },
        onSuccess: (_receipt, variables) => {
            refreshBioXpHistoryCaches(queryClient, variables.connectionGeneration);
        },
    });
};

export const useAssessBioXpOperatorAction = () => {
    const queryClient = useQueryClient();
    return useMutation({
        mutationFn: async ({ commandId, connectionGeneration, ownershipGeneration, verdict, note }: {
            commandId: string;
            connectionGeneration: number;
            ownershipGeneration: number;
            verdict: 'pass' | 'fail';
            note: string;
        }) => (
            await api.post<BioXpOperatorLiveActionReceipt>(
                `/api/bioxp/operator-controls/receipts/${encodeURIComponent(commandId)}/assessment`,
                {
                    ...bioXpOperatorGenerationPayload(connectionGeneration, ownershipGeneration),
                    idempotency_key: crypto.randomUUID(),
                    verdict,
                    note,
                },
            )
        ).data,
        onMutate: async () => {
            await queryClient.cancelQueries({ queryKey: operatorHistoryKey });
        },
        onSuccess: (_receipt, variables) => {
            refreshBioXpHistoryCaches(queryClient, variables.connectionGeneration);
            void queryClient.invalidateQueries({ queryKey: operatorCatalogKey });
        },
    });
};