BEGIN;

-- Proving a camera works, from an office somewhere else.
--
-- The engine already knows how to answer both questions - `probe_source` says
-- whether a stream can be opened and hands back a frame, `CommissionRun` says
-- whether a person walking past produces a view worth enrolling - and both
-- already phrase their answers for an installer. Neither was reachable from
-- head office, so onboarding a camera meant typing an address and hoping.
--
-- A check is therefore a JOB the shop PC picks up on its next sync, not a call
-- head office makes: a PC behind a router has no inbound route, and the
-- placement check takes 25 seconds of somebody walking about, which is far
-- longer than an HTTP request should live.
ALTER TABLE site_cameras
    -- What has been asked for, and when. NULL means nothing is pending.
    ADD COLUMN IF NOT EXISTS check_kind         text,
    ADD COLUMN IF NOT EXISTS check_requested_at timestamptz,
    ADD COLUMN IF NOT EXISTS check_seconds      integer NOT NULL DEFAULT 25,
    -- Claimed by the agent, so a request is not run twice by a PC that synced
    -- while the first attempt was still going.
    ADD COLUMN IF NOT EXISTS check_started_at   timestamptz,
    ADD COLUMN IF NOT EXISTS check_finished_at  timestamptz,
    -- The engine's own answer, stored whole rather than unpacked into columns.
    --
    -- Deliberate: `verdict`, `headline` and `advice` are written for the person
    -- standing next to the camera, and re-wording them in the server and again
    -- in the browser is how three descriptions of one failure drift apart. The
    -- engine says it once; everything above passes it through.
    ADD COLUMN IF NOT EXISTS check_result       jsonb,
    -- A frame captured during the check. Separate from snapshot_key: that one
    -- is the routine picture refreshed every minute, this one is the evidence
    -- for a specific check and must not be overwritten by the next refresh.
    ADD COLUMN IF NOT EXISTS check_image_key    text NOT NULL DEFAULT '';

-- Partial index: the agent asks "is anything pending for my site" on every
-- sync, and almost always the answer is no.
CREATE INDEX IF NOT EXISTS site_cameras_pending_check_idx
    ON site_cameras (site_id)
 WHERE check_requested_at IS NOT NULL AND check_finished_at IS NULL;

COMMIT;