cctv-stack 0.3.0__py3-none-any.whl

cctv/materialise.py

@@ -0,0 +1,488 @@
+"""Turning a review item into a canonical clip, on disk and in the database.
+
+This is the composition the rest of Phase 3 was built for. Everything subtle already lives
+somewhere tested — the fetch range, the coverage decision, the atomic write, the probe
+parsing, the trigger verdict — so this module is mostly *ordering*. The ordering is the
+part that matters, though, and three of its rules are load-bearing:
+
+1. **Pin before downloading, unpin after.** [INV-9]. A failed pin is fatal for that review,
+   because downloading without a pin risks Frigate expiring the footage underneath us, and
+   a missing clip is worse than a late one. Unpinning is best-effort: a stuck pin wastes
+   Frigate's disk, it does not lose data, and the reaper collects it later.
+2. **A row exists only once the file does.** The database is the record of what is on disk,
+   so the insert happens after the rename. The reverse order would let a crash leave a row
+   pointing at nothing, and every consumer of that table would believe it.
+3. **A short clip is kept, not discarded.** [INV-14]. Attempts are ranked and the best one
+   is promoted; retrying improves the outcome and discarding cannot. Each attempt lands on
+   its own scratch path for exactly that reason — writing retries straight onto the
+   canonical path would let a worse second attempt overwrite a better first one, which is
+   the opposite of keeping the best.
+
+**No network or subprocess work happens inside a database transaction.** The claim in
+[`cctv.db`][cctv.db] commits before returning and the insert here opens its own short one,
+so a slow fetch cannot hold the write lock.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+import time
+from collections.abc import Callable, Sequence
+from contextlib import suppress
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Protocol
+from zoneinfo import ZoneInfo
+
+from . import atomic, db
+from .clip import (
+    DEFAULT_COVERAGE_POLICY,
+    DEFAULT_LONG_CLIP_WARN_S,
+    DEFAULT_SEGMENT_FLUSH_GRACE_S,
+    CoveragePolicy,
+    FetchPlan,
+    Verdict,
+    judge_coverage,
+    pick_best,
+    plan_fetch,
+)
+from .ffprobe import ClipFacts, ProbeError, run_probe
+from .frigate import FrigateClient, FrigateError, FrigateUnavailable, NoRecordingsYet
+from .paths import candidate_relpaths, clip_cloud_key, sidecar_relpath
+from .reviews import ReviewCandidate
+from .timeutil import Instant
+from .timeutil import now as _now
+
+__all__ = [
+    "CREATED",
+    "DEFERRED",
+    "FAILED",
+    "SKIPPED",
+    "ClipMaterialiser",
+    "ClipSource",
+    "FrigateSource",
+    "MaterialiseOutcome",
+    "Prober",
+]
+
+CREATED = "created"
+SKIPPED = "skipped"
+#: Retryable — the caller should requeue this review rather than treat it as lost.
+DEFERRED = "deferred"
+FAILED = "failed"
+
+
+class ClipSource(Protocol):
+    """Where clips come from. Narrow on purpose, so a fake is three methods."""
+
+    def retain(self, event_id: str) -> None: ...
+
+    def unretain(self, event_id: str) -> None: ...
+
+    def download(
+        self,
+        camera: str,
+        start: Instant,
+        end: Instant,
+        sink: object,
+        *,
+        timeout_s: float,
+    ) -> int: ...
+
+
+class Prober(Protocol):
+    def __call__(self, path: Path) -> ClipFacts: ...
+
+
+@dataclass(frozen=True, slots=True)
+class FrigateSource:
+    """Adapts [`cctv.frigate.FrigateClient`][cctv.frigate.FrigateClient] to `ClipSource`.
+
+    The indirection exists so the materialiser can be tested without a network, and so
+    nothing in this module needs to know the client's exception hierarchy beyond
+    `FrigateError`.
+    """
+
+    client: FrigateClient
+
+    def retain(self, event_id: str) -> None:
+        self.client.retain_event(event_id)
+
+    def unretain(self, event_id: str) -> None:
+        self.client.unretain_event(event_id)
+
+    def download(
+        self,
+        camera: str,
+        start: Instant,
+        end: Instant,
+        sink: object,
+        *,
+        timeout_s: float,
+    ) -> int:
+        return self.client.download_range(camera, start, end, sink, timeout_s=timeout_s)
+
+
+@dataclass(frozen=True, slots=True)
+class MaterialiseOutcome:
+    """What happened, and why.
+
+    `status` distinguishes four things that a boolean would conflate: a clip was made; it
+    was deliberately not made; it could not be made and should be retried; it could not be
+    made and will not be.
+    """
+
+    review_id: str
+    status: str
+    reason: str
+    clip_id: int | None = None
+    path: str | None = None
+    coverage_ratio: float | None = None
+    degraded: bool = False
+    long_clip: bool = False
+    fetch_attempts: int = 0
+
+    @property
+    def materialised(self) -> bool:
+        return self.status == CREATED
+
+
+@dataclass(frozen=True, slots=True)
+class _Ranked:
+    """A finished attempt, shaped so `pick_best` can rank it.
+
+    Exists so the ranking rule lives in exactly one place. Re-deriving "best" here would
+    mean two implementations of INV-14 that could disagree.
+    """
+
+    coverage_ratio: float | None
+    duration_s: float | None
+    scratch: Path
+    facts: ClipFacts
+
+
+class ClipMaterialiser:
+    """Materialises review items into canonical clips."""
+
+    def __init__(
+        self,
+        *,
+        conn: sqlite3.Connection,
+        source: ClipSource,
+        data_dir: Path,
+        location: str,
+        zone: ZoneInfo,
+        prober: Prober = run_probe,
+        sleep: Callable[[float], None] = time.sleep,
+        clock: Callable[[], Instant] = _now,
+        policy: CoveragePolicy = DEFAULT_COVERAGE_POLICY,
+        flush_grace_s: float = DEFAULT_SEGMENT_FLUSH_GRACE_S,
+        long_clip_warn_s: float = DEFAULT_LONG_CLIP_WARN_S,
+        backoff_s: Sequence[float] = (5.0, 15.0, 45.0),
+        clips_dirname: str = "clips",
+    ) -> None:
+        self.conn = conn
+        self.source = source
+        self.data_dir = Path(data_dir)
+        self.location = location
+        self.zone = zone
+        self.prober = prober
+        self._sleep = sleep
+        self._clock = clock
+        self.policy = policy
+        self.flush_grace_s = flush_grace_s
+        self.long_clip_warn_s = long_clip_warn_s
+        self.backoff_s = tuple(backoff_s)
+        self.clips_dirname = clips_dirname
+
+    # -----------------------------------------------------------------------------------
+
+    def materialise(
+        self,
+        candidate: ReviewCandidate,
+        *,
+        pre_roll_s: float = 5.0,
+        post_roll_s: float = 10.0,
+    ) -> MaterialiseOutcome:
+        """Fetch, verify, and store one review as a canonical clip."""
+        if candidate.is_open:
+            return MaterialiseOutcome(candidate.review_id, SKIPPED, "review is still open")
+
+        plan = plan_fetch(
+            candidate.review_id,
+            start_time=candidate.start_time,
+            end_time=candidate.end_time,
+            pre_roll_s=pre_roll_s,
+            post_roll_s=post_roll_s,
+            segment_flush_grace_s=self.flush_grace_s,
+        )
+
+        delay = plan.seconds_until_ready(self._clock())
+        if delay > 0:
+            self._sleep(delay)
+
+        pinned: list[str] = []
+        try:
+            for event_id in candidate.event_ids:
+                try:
+                    self.source.retain(event_id)
+                except FrigateError as exc:
+                    # Fatal for this review. Downloading without a pin risks Frigate
+                    # expiring the footage first, and a missing clip beats a late one only
+                    # if it is deliberate — which this is.
+                    return MaterialiseOutcome(
+                        candidate.review_id,
+                        FAILED,
+                        f"could not pin event {event_id}: {exc}",
+                    )
+                pinned.append(event_id)
+
+            return self._fetch_and_store(candidate, plan, post_roll_s=post_roll_s)
+        finally:
+            for event_id in pinned:
+                with suppress(FrigateError):
+                    # Non-fatal by design: a stuck pin wastes disk, it does not lose data.
+                    self.source.unretain(event_id)
+
+    # -----------------------------------------------------------------------------------
+
+    def _fetch_and_store(
+        self, candidate: ReviewCandidate, plan: FetchPlan, *, post_roll_s: float
+    ) -> MaterialiseOutcome:
+        target = self._choose_target(candidate)
+        ranked: list[_Ranked] = []
+        last_error: str | None = None
+
+        for attempt in range(1, self.policy.max_attempts + 1):
+            scratch = target.with_name(f"{target.name}.tmp-attempt{attempt}")
+            try:
+                with atomic.atomic_writer(scratch) as handle:
+                    self.source.download(
+                        candidate.camera,
+                        plan.requested_start,
+                        plan.requested_end,
+                        handle,
+                        timeout_s=plan.timeout_s,
+                    )
+                facts = self.prober(scratch)
+            except (NoRecordingsYet, FrigateUnavailable) as exc:
+                # The flush race and transient outages. Both mean "ask again later".
+                atomic.discard(scratch)
+                last_error = str(exc)
+                if attempt < self.policy.max_attempts:
+                    self._sleep(self._backoff(attempt))
+                continue
+            except ProbeError as exc:
+                atomic.discard(scratch)
+                last_error = str(exc)
+                if attempt < self.policy.max_attempts:
+                    self._sleep(self._backoff(attempt))
+                continue
+            except FrigateError as exc:
+                atomic.discard(scratch)
+                return MaterialiseOutcome(candidate.review_id, FAILED, f"fetch failed: {exc}")
+
+            coverage = facts.coverage_against(plan.requested_s)
+            ranked.append(
+                _Ranked(
+                    coverage_ratio=coverage,
+                    duration_s=facts.duration_s,
+                    scratch=scratch,
+                    facts=facts,
+                )
+            )
+
+            verdict = judge_coverage(coverage, attempts_used=attempt, policy=self.policy)
+            if verdict is Verdict.ACCEPT:
+                break
+            if verdict is Verdict.ACCEPT_DEGRADED:
+                # Attempts exhausted and it is still short. Keep it, flag it, move on.
+                break
+            if attempt < self.policy.max_attempts:
+                self._sleep(self._backoff(attempt))
+
+        if not ranked:
+            return MaterialiseOutcome(
+                candidate.review_id,
+                DEFERRED,
+                last_error or "no attempt produced a clip",
+            )
+
+        chosen = pick_best(ranked)
+        assert isinstance(chosen, _Ranked)  # pick_best returns from the input sequence
+        for item in ranked:
+            if item.scratch != chosen.scratch:
+                atomic.discard(item.scratch)
+
+        atomic.promote(chosen.scratch, target)
+        return self._record(
+            candidate,
+            plan,
+            target,
+            chosen,
+            post_roll_s=post_roll_s,
+            fetch_attempts=len(ranked),
+        )
+
+    # -----------------------------------------------------------------------------------
+
+    def _record(
+        self,
+        candidate: ReviewCandidate,
+        plan: FetchPlan,
+        target: Path,
+        chosen: _Ranked,
+        *,
+        post_roll_s: float,
+        fetch_attempts: int,
+    ) -> MaterialiseOutcome:
+        # Two related-but-different paths. `relative` is relative to DATA_DIR, which is
+        # what the database stores. The cloud key is built from the path relative to the
+        # *clips* directory, because `clip_cloud_key` adds the `clips` segment itself —
+        # passing the DATA_DIR-relative form doubled it.
+        relative = PurePosixPath(self.clips_dirname) / self._relative(target)
+        relative_str = relative.as_posix()
+        below_clips = self._relative(target)
+
+        size_bytes = target.stat().st_size
+        digest = _sha256(target)
+        coverage = chosen.coverage_ratio
+        degraded = coverage is None or coverage < self.policy.ok
+        long_clip = (chosen.duration_s or 0.0) > self.long_clip_warn_s
+        cloud_key = clip_cloud_key(self.location, below_clips)
+
+        sidecar_payload = {
+            "review_id": candidate.review_id,
+            "camera": candidate.camera,
+            "severity": candidate.severity,
+            "review_start_time": candidate.start_time,
+            "review_end_time": candidate.end_time,
+            "requested_start_ts": plan.requested_start,
+            "requested_end_ts": plan.requested_end,
+            "requested_s": plan.requested_s,
+            "duration_s": chosen.facts.duration_s,
+            "coverage_ratio": coverage,
+            "max_gap_s": chosen.facts.max_packet_gap_s,
+            "has_gaps": False,  # see the note on ClipRecord below — the detector is unusable
+            "video_codec": chosen.facts.video_codec,
+            "audio_codec": chosen.facts.audio_codec,
+            "has_audio": chosen.facts.has_audio,
+            "event_ids": list(candidate.event_ids),
+            "objects": list(candidate.objects),
+            "zones": list(candidate.zones),
+            "sub_labels": list(candidate.sub_labels),
+            "post_roll_s": post_roll_s,
+            "degraded": degraded,
+            "long_clip": long_clip,
+            "path": relative_str,
+            "cloud_key": cloud_key,
+            "size_bytes": size_bytes,
+            "sha256": digest,
+        }
+
+        sidecar = sidecar_relpath(target)
+        atomic.write_atomic(
+            sidecar,
+            json.dumps(sidecar_payload, indent=2, sort_keys=True).encode("utf-8"),
+        )
+        sidecar_relative = (PurePosixPath(self.clips_dirname) / self._relative(sidecar)).as_posix()
+
+        clip_id, _created = db.insert_clip(
+            self.conn,
+            db.ClipRecord(
+                review_id=candidate.review_id,
+                camera=candidate.camera,
+                severity=candidate.severity,
+                start_time=candidate.start_time,
+                end_time=candidate.end_time or candidate.start_time,
+                path=relative_str,
+                event_ids=candidate.event_ids,
+                zones=candidate.zones,
+                label=candidate.objects[0] if candidate.objects else None,
+                duration_s=chosen.facts.duration_s,
+                requested_start_ts=plan.requested_start,
+                requested_end_ts=plan.requested_end,
+                pre_roll_s=candidate.start_time - plan.requested_start,
+                post_roll_s=post_roll_s,
+                # Recorded because the data is real and a future detector may want it.
+                # `has_gaps` stays false: packet-gap detection flags healthy clips on this
+                # stack (a measured 3.55 s gap in a 30 s clip with a 2.55 s keyframe
+                # interval), so setting it here would mark almost every clip as damaged and
+                # make the flag meaningless. ADR-0015.
+                max_gap_s=chosen.facts.max_packet_gap_s,
+                has_gaps=False,
+                has_audio=chosen.facts.has_audio,
+                video_codec=chosen.facts.video_codec,
+                audio_codec=chosen.facts.audio_codec,
+                fetch_attempts=fetch_attempts,
+                degraded=degraded,
+                long_clip=long_clip,
+                size_bytes=size_bytes,
+                sha256=digest,
+                sidecar_path=sidecar_relative,
+                materialised_at=_now(),
+            ),
+            now=_now(),
+        )
+
+        return MaterialiseOutcome(
+            review_id=candidate.review_id,
+            status=CREATED,
+            reason="ok" if not degraded else f"kept a short clip (coverage {coverage})",
+            clip_id=clip_id,
+            path=relative_str,
+            coverage_ratio=coverage,
+            degraded=degraded,
+            long_clip=long_clip,
+            fetch_attempts=fetch_attempts,
+        )
+
+    # -----------------------------------------------------------------------------------
+
+    def _relative(self, target: Path) -> PurePosixPath:
+        """`<camera>/YYYY/MM/DD/HH-MM-SS.mp4` — the part below the clips directory."""
+        return PurePosixPath(target.relative_to(self.data_dir / self.clips_dirname).as_posix())
+
+    def _choose_target(self, candidate: ReviewCandidate) -> Path:
+        """The path to write, resolving the collision case.
+
+        Two reviews on one camera can start in the same second, and a DST fallback makes it
+        certain rather than rare. The colliding form is used when the primary path belongs
+        to a *different* review, or when a file is there that no row accounts for — an
+        orphan from a crash. Overwriting either would destroy a clip to make room, which is
+        the one thing the design never does.
+        """
+        primary, colliding = candidate_relpaths(
+            candidate.camera, candidate.start_time, self.zone, candidate.review_id
+        )
+        chosen = primary
+
+        row = self.conn.execute(
+            "SELECT review_id FROM clips WHERE path = ?",
+            ((PurePosixPath(self.clips_dirname) / primary).as_posix(),),
+        ).fetchone()
+        if row is not None:
+            if row["review_id"] != candidate.review_id:
+                chosen = colliding
+        elif (self.data_dir / self.clips_dirname / primary).exists():
+            chosen = colliding
+
+        return self.data_dir / self.clips_dirname / chosen
+
+    def _backoff(self, attempt: int) -> float:
+        if not self.backoff_s:
+            return 0.0
+        return self.backoff_s[min(attempt - 1, len(self.backoff_s) - 1)]
+
+
+def _sha256(path: Path, *, chunk: int = 1024 * 1024) -> str:
+    digest = hashlib.sha256()
+    with open(path, "rb") as handle:
+        while True:
+            block = handle.read(chunk)
+            if not block:
+                break
+            digest.update(block)
+    return digest.hexdigest()

cctv/migrations/0001_init.sql

@@ -0,0 +1,199 @@
+-- Migration 0001 — the initial schema.
+--
+-- Forward-only. There are no down migrations: a bad migration is corrected by a new one
+-- (INV-8, docs/architecture/lld/03-state-store.md §4.1).
+--
+-- Two properties are enforced here rather than in application code, because a constraint
+-- cannot be forgotten:
+--
+--   * `UNIQUE(review_id)` is the idempotency mechanism. Materialising the same review
+--     twice cannot produce two rows, which is what makes INV-7 structural.
+--   * The `upload_state` CHECK is closed. A typo in a state name fails at write time
+--     instead of creating a row that no query will ever find again.
+--
+-- Timestamps are `REAL` epoch seconds — an instant, which carries no timezone (INV-12,
+-- ADR-0017). No column stores a rendered local time.
+
+CREATE TABLE cameras (
+    name            TEXT PRIMARY KEY,
+    display_name    TEXT NOT NULL,
+    enabled         INTEGER NOT NULL DEFAULT 1 CHECK (enabled IN (0, 1)),
+    first_seen_at   REAL NOT NULL,
+    retired_at      REAL,
+    config_hash     TEXT,
+    updated_at      REAL NOT NULL
+);
+
+CREATE TABLE clips (
+    id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+
+    -- Identity. The review id is Frigate's review item id and the dedup key
+    -- (ADR-0016). event_ids preserves event-level searchability for a per-visit file.
+    review_id           TEXT NOT NULL UNIQUE,
+    event_ids           TEXT NOT NULL DEFAULT '[]',
+    severity            TEXT NOT NULL CHECK (severity IN ('alert', 'detection')),
+    camera              TEXT NOT NULL REFERENCES cameras (name) ON UPDATE CASCADE,
+    label               TEXT,
+    zones               TEXT NOT NULL DEFAULT '[]',
+
+    -- What Frigate called the activity.
+    start_time          REAL NOT NULL,
+    end_time            REAL NOT NULL,
+
+    -- What we actually got. These are the columns that make INV-14 auditable: a
+    -- truncated clip, a clip with a hole, and a perfect clip are all valid MP4s that
+    -- play fine and upload fine, and are otherwise indistinguishable.
+    duration_s          REAL,
+    requested_start_ts  REAL,
+    requested_end_ts    REAL,
+    requested_s         REAL,
+    coverage_ratio      REAL,
+    pre_roll_s          REAL,
+    post_roll_s         REAL,
+    max_gap_s           REAL,
+    has_gaps            INTEGER NOT NULL DEFAULT 0 CHECK (has_gaps IN (0, 1)),
+    has_audio           INTEGER NOT NULL DEFAULT 0 CHECK (has_audio IN (0, 1)),
+    video_codec         TEXT,
+    audio_codec         TEXT,
+    fetch_attempts      INTEGER NOT NULL DEFAULT 0,
+    degraded            INTEGER NOT NULL DEFAULT 0 CHECK (degraded IN (0, 1)),
+    long_clip           INTEGER NOT NULL DEFAULT 0 CHECK (long_clip IN (0, 1)),
+
+    -- The artefact. `path` is relative to DATA_DIR, never absolute, so a restore to a
+    -- different mount point still works.
+    path                TEXT NOT NULL,
+    sidecar_path        TEXT,
+    size_bytes          INTEGER,
+    sha256              TEXT,
+
+    -- Upload state. See the contract §3 for the machine, and INV-1 for the one rule
+    -- that matters most: PENDING, UPLOADING, RETRY_WAIT and FAILED_PERMANENT all hold
+    -- the local file.
+    upload_state        TEXT NOT NULL DEFAULT 'PENDING'
+                        CHECK (upload_state IN (
+                            'PENDING', 'UPLOADING', 'RETRY_WAIT', 'UPLOADED',
+                            'FAILED_PERMANENT', 'SKIPPED_BY_POLICY',
+                            'DELETED_LOCAL', 'EXPIRED_CLOUD', 'FORCE_DELETED'
+                        )),
+    attempts            INTEGER NOT NULL DEFAULT 0,
+    next_attempt_at     REAL,
+    lease_owner         TEXT,
+    lease_expires_at    REAL,
+    last_error_class    TEXT CHECK (last_error_class IS NULL OR last_error_class IN (
+                            'transient', 'auth', 'not_found', 'quota', 'checksum',
+                            'unknown'
+                        )),
+    -- Truncated to 2000 characters on write. Never contains credentials (INV-2).
+    last_error          TEXT,
+
+    cloud_key           TEXT,
+    cloud_etag          TEXT,
+    cloud_size_bytes    INTEGER,
+    uploaded_at         REAL,
+    local_deleted_at    REAL,
+    cloud_deleted_at    REAL,
+
+    -- A pin protects Frigate's source footage until our copy is durable (INV-9).
+    pinned              INTEGER NOT NULL DEFAULT 0 CHECK (pinned IN (0, 1)),
+    pinned_at           REAL,
+
+    materialised_at     REAL,
+    created_at          REAL NOT NULL,
+    updated_at          REAL NOT NULL,
+
+    CHECK (last_error IS NULL OR length(last_error) <= 2000)
+);
+
+-- Each index serves one named query. No speculative indexes: every one costs write
+-- amplification on a table that is written on every clip.
+CREATE INDEX clips_claim_query ON clips (upload_state, next_attempt_at, id);
+CREATE INDEX clips_local_retention ON clips (upload_state, start_time);
+CREATE INDEX clips_cloud_retention ON clips (upload_state, uploaded_at);
+CREATE INDEX clips_camera_start ON clips (camera, start_time DESC);
+CREATE INDEX clips_pin_reaper ON clips (pinned, pinned_at);
+CREATE INDEX clips_by_checksum ON clips (sha256);
+
+CREATE TABLE upload_attempts (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    clip_id         INTEGER NOT NULL REFERENCES clips (id) ON DELETE CASCADE,
+    attempt_no      INTEGER NOT NULL,
+    started_at      REAL NOT NULL,
+    finished_at     REAL,
+    outcome         TEXT CHECK (outcome IS NULL OR outcome IN (
+                        'success', 'transient_error', 'permanent_error', 'checksum_mismatch'
+                    )),
+    http_status     INTEGER,
+    bytes_sent      INTEGER,
+    error_class     TEXT,
+    error_message   TEXT,
+    duration_ms     INTEGER
+);
+
+CREATE TABLE sweep_state (
+    name                    TEXT PRIMARY KEY,
+    watermark               REAL,
+    last_run_at             REAL,
+    last_success_at         REAL,
+    consecutive_failures    INTEGER NOT NULL DEFAULT 0,
+    notes                   TEXT
+);
+
+CREATE TABLE pinned_events (
+    event_id    TEXT PRIMARY KEY,
+    camera      TEXT NOT NULL,
+    pinned_at   REAL NOT NULL,
+    unpinned_at REAL,
+    reason      TEXT NOT NULL CHECK (reason IN ('materialisation', 'manual')),
+    state       TEXT NOT NULL CHECK (state IN ('held', 'released', 'expired', 'failed'))
+);
+
+CREATE INDEX pinned_events_open ON pinned_events (state, pinned_at);
+
+CREATE TABLE component_health (
+    component   TEXT PRIMARY KEY,
+    state       TEXT NOT NULL CHECK (state IN (
+                    'HEALTHY', 'DEGRADED', 'UNHEALTHY', 'UNKNOWN', 'DISABLED'
+                )),
+    detail      TEXT,
+    version     TEXT,
+    observed_at REAL NOT NULL
+);
+
+CREATE TABLE health_history (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    subject     TEXT NOT NULL,
+    state       TEXT NOT NULL,
+    observed_at REAL NOT NULL
+);
+
+CREATE INDEX health_history_subject ON health_history (subject, observed_at DESC);
+
+CREATE TABLE reconciliation_findings (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    run_at      REAL NOT NULL,
+    kind        TEXT NOT NULL CHECK (kind IN (
+                    'orphan_object', 'dangling_row', 'checksum_mismatch',
+                    'unexpected_local_file'
+                )),
+    subject     TEXT NOT NULL,
+    detail      TEXT,
+    resolved_at REAL
+);
+
+CREATE INDEX reconciliation_open ON reconciliation_findings (resolved_at, run_at);
+
+CREATE TABLE system_events (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    at          REAL NOT NULL,
+    severity    TEXT NOT NULL CHECK (severity IN ('info', 'warning', 'error', 'critical')),
+    component   TEXT NOT NULL,
+    -- A stable machine API: alerting rules reference these, so changing one is a
+    -- breaking change.
+    code        TEXT NOT NULL,
+    message     TEXT,
+    detail      TEXT,
+    dedupe_key  TEXT
+);
+
+CREATE INDEX system_events_recent ON system_events (at DESC);
+CREATE INDEX system_events_dedupe ON system_events (dedupe_key, at DESC);