alphaboard 0.1.0__py3-none-any.whl

alphaboard/__init__.py

@@ -0,0 +1,30 @@
+"""alphaboard — Python SDK for AlphaBoard.
+
+Quick start:
+
+    from alphaboard import AlphaBoard
+
+    tracker = AlphaBoard(
+        strategy="momentum_eth",
+        broker="hyperliquid",
+        account="main",
+        # api_url and api_key fall back to ALPHABOARD_API_URL / ALPHABOARD_API_KEY
+    )
+
+    tracker.log_trade(symbol="ETH-PERP", side="buy", quantity=0.5, price=3800)
+    tracker.heartbeat(open_positions=1)
+
+The SDK is observation-path only. `log_trade()` enqueues and returns in
+microseconds — it never blocks the trading loop and never raises. A daemon
+background thread batches events, posts them with exponential backoff, and
+suppresses all exceptions.
+"""
+
+from alphaboard._backfill import BackfillError, BackfillResult
+
+# `StratOps` is the deprecated pre-rename alias (OPM-762), re-exported only so
+# the burn-in VPS keeps importing until it picks up the rename.
+from alphaboard.client import AlphaBoard, StratOps
+
+__version__ = "0.1.0"
+__all__ = ["AlphaBoard", "BackfillError", "BackfillResult", "StratOps", "__version__"]

alphaboard/_backfill.py

@@ -0,0 +1,481 @@
+"""Backfill engine (OPM-729) — re-runnable historical ingestion.
+
+Reads a CSV export (a Zorro log, a broker statement, an engine's own journal)
+and feeds rows through the server's `/batch` endpoints with DETERMINISTIC
+idempotency keys — UUIDv5 of the row's business key — so re-running the same
+file or window is a no-op (`deduped`), never a duplicate.
+
+That no-op used to be unconditional, which made the tool useless for the one
+job an operator actually needs it for: fixing rows that were ingested wrong.
+A re-run carrying corrected numbers reported `deduped` — the same word as a
+re-run that changed nothing — so a fix that never landed was indistinguishable
+from a fix that was not needed. Since OPM-1309 a collision whose payload
+disagrees with the stored row is counted as `conflicts`, and `update_existing`
+moves the stored row and counts it as `updated`. The default is unchanged:
+without the flag, history is never rewritten.
+
+Business keys (per spec §3.6 / OPM-729):
+  trades    -> strategy + external_trade_id when present, else
+               strategy + symbol + executed_at + quantity + price + side
+  equity    -> strategy + snapshot_at
+  positions -> strategy + account + symbol + snapshot_at
+
+Unlike the live path this is a FOREGROUND operator tool: it runs
+synchronously, reports per-row outcomes, and raises on persistent transport
+failure (a re-run is cheap precisely because the keys are deterministic).
+
+Deliberately NO `Idempotency-Key` header on backfill batches: the record keys
+are deterministic, so the middleware's 24h response cache would replay the
+first run's "created" counts on a re-run and mask the real record-level
+"deduped" report — the signal that tells the operator the re-run was a no-op.
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import logging
+import time
+import uuid
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from alphaboard._config import Config
+
+logger = logging.getLogger("alphaboard")
+
+# UUIDv5 namespace for deterministic backfill keys. Fixed forever — changing
+# it would re-key history and duplicate every previously backfilled row.
+BACKFILL_NS = uuid.uuid5(uuid.NAMESPACE_URL, "https://alphaboard.dev/sdk/backfill")
+
+# Server-side cap on /batch items; our chunks must stay at or under it.
+SERVER_BATCH_CAP = 1000
+
+# Canonical fields per kind — anything else in the CSV is dropped (the batch
+# schemas are extra="forbid"; one stray column must not 422 a whole batch).
+_FIELDS: dict[str, frozenset[str]] = {
+    "trades": frozenset(
+        {
+            "strategy",
+            "broker",
+            "account",
+            "symbol",
+            "side",
+            "quantity",
+            "price",
+            "executed_at",
+            "idempotency_key",
+            "external_trade_id",
+            "external_order_id",
+            "external_exec_id",
+            "engine_trade_id",
+            "notional_value",
+            "currency",
+            "exec_type",
+            "order_status",
+            "cum_qty",
+            "leaves_qty",
+            "commission",
+            "fees",
+            "slippage",
+            "order_type",
+            "time_in_force",
+            "is_close",
+        }
+    ),
+    "equity": frozenset(
+        {
+            "strategy",
+            "equity",
+            "snapshot_at",
+            "cash",
+            "positions_value",
+            "unrealized_pnl",
+            "realized_pnl_day",
+            "currency",
+            "equity_usd",
+            "allocated_capital",
+            "utilization_pct",
+            "idempotency_key",
+        }
+    ),
+    "positions": frozenset(
+        {
+            "strategy",
+            "broker",
+            "account",
+            "symbol",
+            "quantity",
+            "snapshot_at",
+            "avg_entry_price",
+            "current_price",
+            "unrealized_pnl",
+            "realized_pnl",
+            "market_value",
+            "idempotency_key",
+        }
+    ),
+}
+
+_REQUIRED: dict[str, frozenset[str]] = {
+    # The timestamp is required even though the server would default it to
+    # NOW(): a backfill row without its original time can't have a stable
+    # key and would corrupt the curve with wall-clock-at-import.
+    "trades": frozenset(
+        {"strategy", "broker", "account", "symbol", "side", "quantity", "price", "executed_at"}
+    ),
+    "equity": frozenset({"strategy", "equity", "snapshot_at"}),
+    "positions": frozenset({"strategy", "broker", "account", "symbol", "quantity", "snapshot_at"}),
+}
+
+_TIME_FIELD = {"trades": "executed_at", "equity": "snapshot_at", "positions": "snapshot_at"}
+_ENDPOINT = {
+    "trades": "/api/v1/trades/batch",
+    "equity": "/api/v1/equity/batch",
+    "positions": "/api/v1/positions/batch",
+}
+
+# Fields the server parses as booleans; CSV gives us strings.
+_BOOL_FIELDS = frozenset({"is_close"})
+_TRUTHY = frozenset({"true", "1", "yes", "y", "t"})
+_FALSY = frozenset({"false", "0", "no", "n", "f", ""})
+
+
+class BackfillError(Exception):
+    """Unrecoverable backfill failure (bad input file, exhausted retries).
+    Re-running after the cause is fixed is safe — keys are deterministic."""
+
+
+@dataclass
+class BackfillResult:
+    """Aggregate outcome.
+
+    `created + updated + conflicts + deduped + server_errors == sent`;
+    `skipped` rows never left the client (time filter or validation).
+
+    `conflicts` is the one worth reading on a re-run: those rows exist on the
+    server carrying DIFFERENT values to the file you just fed it. Either the
+    file is now right and the server is stale (re-run with `update_existing`),
+    or the server is right and the file has drifted. Silence on that question
+    is what OPM-1309 fixed.
+    """
+
+    kind: str
+    rows_read: int = 0
+    filtered_out: int = 0  # outside [since, until]
+    invalid: int = 0  # failed client-side validation (see `row_errors`)
+    sent: int = 0
+    created: int = 0
+    updated: int = 0  # corrected in place (needs update_existing)
+    conflicts: int = 0  # stored row disagrees and was left alone
+    deduped: int = 0  # byte-identical re-send, nothing to do
+    server_errors: int = 0
+    batches: int = 0
+    row_errors: list[str] = field(default_factory=list)  # capped at 50
+    warnings: list[str] = field(default_factory=list)  # advisory, never fatal
+
+    @property
+    def ok(self) -> bool:
+        return self.invalid == 0 and self.server_errors == 0
+
+
+def derive_backfill_key(kind: str, row: Mapping[str, Any]) -> str:
+    """Deterministic UUIDv5 idempotency key from the row's business key.
+
+    Timestamps are normalised to UTC ISO before hashing so '...Z' and
+    '...+00:00' spellings of the same instant derive the same key.
+    """
+    if kind == "trades":
+        if row.get("external_trade_id"):
+            basis = f"trades|{row['strategy']}|{row['external_trade_id']}"
+        else:
+            ts = _norm_ts(row["executed_at"])
+            basis = (
+                f"trades|{row['strategy']}|{row['symbol']}|{ts}"
+                f"|{row['quantity']}|{row['price']}|{row['side']}"
+            )
+    elif kind == "equity":
+        basis = f"equity|{row['strategy']}|{_norm_ts(row['snapshot_at'])}"
+    elif kind == "positions":
+        basis = (
+            f"positions|{row['strategy']}|{row.get('account', '')}"
+            f"|{row['symbol']}|{_norm_ts(row['snapshot_at'])}"
+        )
+    else:
+        raise BackfillError(f"unknown kind: {kind!r}")
+    return str(uuid.uuid5(BACKFILL_NS, basis))
+
+
+def parse_dt(value: str) -> datetime:
+    """Parse an ISO-8601 timestamp ('Z' accepted). Naive values are taken as
+    UTC — the least-surprising reading for engine logs."""
+    dt = datetime.fromisoformat(value.strip().replace("Z", "+00:00"))
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt
+
+
+def _norm_ts(value: str) -> str:
+    return parse_dt(str(value)).astimezone(timezone.utc).isoformat()
+
+
+def _map_row(
+    raw: Mapping[str, str],
+    kind: str,
+    mapping: Mapping[str, str] | None,
+    defaults: Mapping[str, str | None],
+) -> dict[str, Any]:
+    """Rename headers via `mapping`, inject `defaults` for absent routing
+    fields, coerce booleans, and drop empty/unknown columns.
+
+    Values are `str` except the coerced booleans, hence `dict[str, Any]`."""
+    row: dict[str, Any] = {}
+    for col, value in raw.items():
+        if col is None:
+            continue  # ragged row — extra cells beyond the header
+        name = (mapping or {}).get(col, col).strip()
+        cell = (value or "").strip()
+        if name not in _FIELDS[kind] or not cell:
+            continue
+        if name in _BOOL_FIELDS:
+            lowered = cell.lower()
+            if lowered in _TRUTHY:
+                row[name] = True
+            elif lowered in _FALSY:
+                row[name] = False
+            else:
+                row[name] = cell  # let the server report it per-row
+        else:
+            row[name] = cell
+    for name, default_value in defaults.items():
+        if default_value and name in _FIELDS[kind]:
+            row.setdefault(name, default_value)
+    return row
+
+
+def run_backfill(
+    config: Config,
+    source: Path | str,
+    *,
+    kind: str,
+    mapping: Mapping[str, str] | None = None,
+    defaults: Mapping[str, str | None] | None = None,
+    since: datetime | None = None,
+    until: datetime | None = None,
+    batch_size: int = 500,
+    dry_run: bool = False,
+    update_existing: bool = False,
+    progress: Callable[[str], None] | None = None,
+) -> BackfillResult:
+    """Backfill one CSV file. Returns the aggregate result; raises
+    `BackfillError` on unreadable input or exhausted transport retries
+    (safe to re-run — deterministic keys make the retry a no-op).
+
+    With `update_existing`, a row that already exists under the same
+    deterministic key is CORRECTED to match the file rather than ignored. Off
+    by default, because the ordinary reason to re-run is to resume an
+    interrupted load, and that must not rewrite anything."""
+    if kind not in _FIELDS:
+        raise BackfillError(f"kind must be one of {sorted(_FIELDS)}, got {kind!r}")
+    if not 1 <= batch_size <= SERVER_BATCH_CAP:
+        raise BackfillError(f"batch_size must be 1..{SERVER_BATCH_CAP}")
+    if since and since.tzinfo is None:
+        since = since.replace(tzinfo=timezone.utc)
+    if until and until.tzinfo is None:
+        until = until.replace(tzinfo=timezone.utc)
+
+    result = BackfillResult(kind=kind)
+    time_field = _TIME_FIELD[kind]
+    rows: list[dict[str, Any]] = []
+
+    try:
+        with Path(source).open(newline="", encoding="utf-8-sig") as fh:
+            for line_no, raw in enumerate(csv.DictReader(fh), start=1):
+                result.rows_read += 1
+                row = _map_row(raw, kind, mapping, defaults or {})
+
+                missing = _REQUIRED[kind] - row.keys()
+                if missing:
+                    result.invalid += 1
+                    if len(result.row_errors) < 50:
+                        result.row_errors.append(f"row {line_no}: missing {sorted(missing)}")
+                    continue
+                try:
+                    ts = parse_dt(row[time_field])
+                except ValueError as exc:
+                    result.invalid += 1
+                    if len(result.row_errors) < 50:
+                        result.row_errors.append(f"row {line_no}: bad {time_field}: {exc}")
+                    continue
+
+                if (since and ts < since) or (until and ts > until):
+                    result.filtered_out += 1
+                    continue
+
+                row.setdefault("idempotency_key", derive_backfill_key(kind, row))
+                rows.append(row)
+
+        if kind == "equity":
+            _warn_on_non_positive_equity(rows, result)
+    except OSError as exc:
+        raise BackfillError(f"cannot read {source}: {exc}") from exc
+
+    if dry_run:
+        if progress:
+            progress(
+                f"dry-run: {len(rows)} row(s) would be sent in {_n_batches(rows, batch_size)} batch(es)"
+            )
+        return result
+
+    with httpx.Client(
+        base_url=config.api_url,
+        headers=_headers(config),
+        timeout=config.export_timeout_s,
+    ) as client:
+        for start in range(0, len(rows), batch_size):
+            chunk = rows[start : start + batch_size]
+            body = _post_batch(
+                client,
+                _ENDPOINT[kind],
+                chunk,
+                config,
+                result,
+                update_existing=update_existing,
+            )
+            result.batches += 1
+            result.sent += len(chunk)
+            result.created += body["created"]
+            result.deduped += body["deduped"]
+            result.server_errors += body["errors"]
+            # `.get` because `positions` predates OPM-1309 and its response
+            # body carries neither counter. Absent means zero, not an error.
+            result.updated += body.get("updated", 0)
+            result.conflicts += body.get("conflicts", 0)
+            for item in body["items"]:
+                if item["status"] == "error" and len(result.row_errors) < 50:
+                    result.row_errors.append(
+                        f"batch {result.batches} item {item.get('index', item.get('row'))}: {item.get('error')}"
+                    )
+            if progress:
+                # Only mention updated/conflicts once there are some: on the
+                # overwhelmingly common clean load both are zero, and two more
+                # always-zero counters is noise in front of the one that moves.
+                extra = ""
+                if result.updated:
+                    extra += f" updated={result.updated}"
+                if result.conflicts:
+                    extra += f" conflicts={result.conflicts}"
+                progress(
+                    f"batch {result.batches}: sent={result.sent}/{len(rows)} "
+                    f"created={result.created} deduped={result.deduped}{extra} "
+                    f"errors={result.server_errors}"
+                )
+
+    return result
+
+
+def _warn_on_non_positive_equity(rows: list[dict[str, Any]], result: BackfillResult) -> None:
+    """Flag an equity file that is really a PnL file (OPM-1302).
+
+    `equity` means *account equity* — capital base plus PnL — because every
+    ratio metric downstream is a percentage change off the previous point. A
+    realised-PnL series starts at 0.00 and can cross it, which makes those
+    returns undefined at best and sign-inverted at worst. The rows are still
+    sent (the curve itself is real and worth charting); the warning is so the
+    trader learns it here rather than from a Sharpe with the wrong sign.
+    """
+    zeros = 0
+    negatives = 0
+    for row in rows:
+        try:
+            value = float(row.get("equity", ""))
+        except (TypeError, ValueError):
+            continue  # let the server report an unparseable value per-row
+        if value == 0:
+            zeros += 1
+        elif value < 0:
+            negatives += 1
+    if not zeros and not negatives:
+        return
+    result.warnings.append(
+        f"{zeros} zero and {negatives} negative equity value(s): 'equity' means "
+        "account equity (capital base + PnL), not PnL. Percentage metrics "
+        "(Sharpe, CAGR, drawdown) will be hidden for this strategy until the "
+        "curve is strictly positive."
+    )
+
+
+def _headers(config: Config) -> dict[str, str]:
+    headers = {"User-Agent": "alphaboard-sdk/0.1 backfill"}
+    if config.api_key:
+        headers["Authorization"] = f"Bearer {config.api_key}"
+    return headers
+
+
+def _n_batches(rows: list[Any], batch_size: int) -> int:
+    return (len(rows) + batch_size - 1) // batch_size
+
+
+def _post_batch(
+    client: httpx.Client,
+    endpoint: str,
+    chunk: list[dict[str, Any]],
+    config: Config,
+    result: BackfillResult,
+    *,
+    update_existing: bool = False,
+) -> dict[str, Any]:
+    """POST one chunk with bounded retries on 5xx/transport errors. 4xx is
+    terminal — it means our payload is wrong and a retry can't fix it."""
+    # Sent only when set, so the request an older server sees is byte-for-byte
+    # the one it saw before this flag existed.
+    params = {"update_existing": "true"} if update_existing else None
+    last_error = ""
+    for attempt in range(config.max_retry_attempts):
+        try:
+            resp = client.post(endpoint, json={"items": chunk}, params=params)
+            if resp.status_code < 400:
+                body: dict[str, Any] = resp.json()
+                return body
+            if 400 <= resp.status_code < 500:
+                raise BackfillError(
+                    f"{endpoint} rejected the batch ({resp.status_code}): "
+                    f"{resp.text[:300]} — after {result.sent} row(s) accepted; "
+                    "fix the input and re-run (already-accepted rows will dedupe)"
+                )
+            last_error = f"{resp.status_code}: {resp.text[:200]}"
+        except httpx.HTTPError as exc:
+            last_error = repr(exc)
+        backoff = min(config.max_backoff_s, 2**attempt)
+        logger.warning(
+            "backfill %s attempt %d failed (%s); retrying in %.0fs",
+            endpoint,
+            attempt + 1,
+            last_error,
+            backoff,
+        )
+        time.sleep(backoff)
+    raise BackfillError(
+        f"{endpoint} unreachable after {config.max_retry_attempts} attempts ({last_error}) — "
+        f"{result.sent} row(s) were accepted before the failure; re-run to resume (no duplicates)"
+    )
+
+
+def parse_mapping(text: str | None) -> dict[str, str] | None:
+    """Parse the CLI's --mapping JSON (`{csv_column: canonical_field}`)."""
+    if not text:
+        return None
+    try:
+        mapping = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise BackfillError(f"--mapping is not valid JSON: {exc}") from exc
+    if not isinstance(mapping, dict) or not all(
+        isinstance(k, str) and isinstance(v, str) for k, v in mapping.items()
+    ):
+        raise BackfillError("--mapping must be a JSON object of {csv_column: canonical_field}")
+    return mapping

alphaboard/_cli.py

@@ -0,0 +1,184 @@
+"""`alphaboard` command-line interface (OPM-729, OPM-1218).
+
+    alphaboard doctor
+    alphaboard backfill trades.csv --kind trades --strategy momo --broker ib --account main
+    alphaboard backfill equity.csv --kind equity --strategy momo --since 2025-01-01
+    alphaboard backfill positions.csv --kind positions --mapping '{"Time": "snapshot_at"}' --dry-run
+
+`doctor` is the pre-flight: it checks that the API is reachable, that the key
+authenticates, that ingestion actually accepts a write, and then prints the
+coverage census so "am I being watched?" has an answer before anything is
+trusted. `backfill` reads a CSV export and replays it through the server's
+/batch endpoints with deterministic UUIDv5 idempotency keys — re-running the
+same file is a no-op. `--strategy/--broker/--account` fill in routing fields
+the CSV doesn't carry; columns present in the CSV win.
+
+If a re-run reports `conflicts=N`, N rows already on the server disagree with
+the file you just fed it. Re-run with `--update-existing` to make the server
+match the file.
+
+api_url/api_key resolve like the SDK does everywhere else
+(flags > ALPHABOARD_* env > ~/.alphaboard/config.toml).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import IO, Any
+
+from alphaboard._backfill import BackfillError, parse_dt, parse_mapping, run_backfill
+from alphaboard._config import resolve
+from alphaboard._doctor import render, run_doctor
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="alphaboard", description="AlphaBoard SDK utilities.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    bf = sub.add_parser(
+        "backfill",
+        help="Replay a historical CSV (trades/equity/positions) — safe to re-run.",
+    )
+    bf.add_argument("file", help="CSV file; first row is the header.")
+    bf.add_argument("--kind", required=True, choices=["trades", "equity", "positions"])
+    bf.add_argument("--strategy", help="Strategy name for rows without a strategy column.")
+    bf.add_argument("--broker", help="Broker name for rows without a broker column.")
+    bf.add_argument("--account", help="Account id for rows without an account column.")
+    bf.add_argument(
+        "--mapping",
+        help='JSON {csv_column: canonical_field} to rename headers, e.g. \'{"Time": "executed_at"}\'.',
+    )
+    bf.add_argument("--since", help="Only rows at/after this ISO timestamp.")
+    bf.add_argument("--until", help="Only rows at/before this ISO timestamp.")
+    bf.add_argument(
+        "--api-url", help="AlphaBoard server (default: ALPHABOARD_API_URL / config file)."
+    )
+    bf.add_argument("--api-key", help="API key (default: ALPHABOARD_API_KEY / config file).")
+    bf.add_argument("--batch-size", type=int, default=500, help="Rows per request (max 1000).")
+    bf.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Parse, validate and count rows without sending anything.",
+    )
+    bf.add_argument(
+        "--update-existing",
+        action="store_true",
+        help=(
+            "Correct rows that already exist so they match this file. Without "
+            "it a disagreeing row is counted as a conflict and left alone. Use "
+            "after fixing the source of a bad load — not to resume one."
+        ),
+    )
+
+    doc = sub.add_parser(
+        "doctor",
+        help="Check the API, the key, ingestion and coverage — then print the census.",
+    )
+    doc.add_argument(
+        "--api-url", help="AlphaBoard server (default: ALPHABOARD_API_URL / config file)."
+    )
+    doc.add_argument("--api-key", help="API key (default: ALPHABOARD_API_KEY / config file).")
+    doc.add_argument(
+        "--no-probe",
+        action="store_true",
+        help=(
+            "Skip the probe heartbeat. The probe is a strategy-less "
+            "infrastructure ping, so it cannot mask a silent strategy, but "
+            "read-only environments may want the checks without the write."
+        ),
+    )
+    return parser
+
+
+def _ascii_only(stream: IO[Any]) -> bool:
+    """Can this console print a tick?
+
+    Windows consoles still default to a legacy codepage, and a `doctor` that
+    dies with `UnicodeEncodeError` on the machine you are diagnosing is worse
+    than no doctor at all.
+    """
+    encoding = getattr(stream, "encoding", None) or "ascii"
+    try:
+        "✓✗·•".encode(encoding)
+    except (LookupError, UnicodeEncodeError):
+        return True
+    return False
+
+
+def _doctor(args: argparse.Namespace) -> int:
+    config = resolve(
+        # `doctor` inspects the deployment, not one strategy, so this name
+        # only satisfies config resolution. Nothing is ever posted under it —
+        # the probe heartbeat deliberately carries no strategy at all.
+        strategy="doctor",
+        api_url=args.api_url,
+        api_key=args.api_key,
+    )
+    report = run_doctor(config, probe=not args.no_probe)
+    print(render(report, ascii_only=_ascii_only(sys.stdout)))
+    return report.exit_code
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    if args.command == "doctor":
+        return _doctor(args)
+    try:
+        config = resolve(
+            # `strategy` here only satisfies config resolution (url/key/retry
+            # tuning); row routing comes from `defaults` + the CSV itself.
+            strategy=args.strategy or "backfill",
+            api_url=args.api_url,
+            api_key=args.api_key,
+        )
+        result = run_backfill(
+            config,
+            args.file,
+            kind=args.kind,
+            mapping=parse_mapping(args.mapping),
+            defaults={
+                "strategy": args.strategy,
+                "broker": args.broker,
+                "account": args.account,
+            },
+            since=parse_dt(args.since) if args.since else None,
+            until=parse_dt(args.until) if args.until else None,
+            batch_size=args.batch_size,
+            dry_run=args.dry_run,
+            update_existing=args.update_existing,
+            progress=print,
+        )
+    except BackfillError as exc:
+        print(f"backfill failed: {exc}", file=sys.stderr)
+        return 2
+    except ValueError as exc:  # bad --since/--until
+        print(f"backfill failed: {exc}", file=sys.stderr)
+        return 2
+
+    print(
+        f"{result.kind}: read={result.rows_read} sent={result.sent} "
+        f"created={result.created} updated={result.updated} "
+        f"conflicts={result.conflicts} deduped={result.deduped} "
+        f"filtered={result.filtered_out} invalid={result.invalid} "
+        f"server_errors={result.server_errors}"
+    )
+    if result.conflicts:
+        # Loud, on stderr, and last: a silent conflict count is the whole
+        # defect OPM-1309 exists to fix, and a number buried in a nine-field
+        # summary line is close enough to silent.
+        print(
+            f"  warning: {result.conflicts} row(s) already exist with DIFFERENT "
+            "values and were left unchanged. Re-run with --update-existing to "
+            "make the server match this file.",
+            file=sys.stderr,
+        )
+    for line in result.warnings:
+        print(f"  warning: {line}", file=sys.stderr)
+    for line in result.row_errors:
+        print(f"  {line}", file=sys.stderr)
+    return 0 if result.ok else 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())