code-coordinator 0.5.46__py3-none-any.whl

coord/board_bool_guard.py

@@ -0,0 +1,72 @@
+"""Producer-side guard against the #632 blank-board class (#748).
+
+SQLite has no native boolean type — a column declared ``INTEGER DEFAULT 0``
+and used as a flag (e.g. ``is_interactive``) serializes on the `/board` wire
+as a raw JSON ``0``/``1``, not ``true``/``false``.  The Rust side
+(``tui/src/app/types.rs``) hand-mirrors DB columns into typed structs; if a
+*new* such column is ever typed as a plain ``bool`` there (instead of going
+through ``de_bool_from_int_or_bool`` or an equivalent coercing
+deserializer), that ONE field fails the parse of the **entire**
+``BoardPayload`` and blanks the whole TUI board (#632/#546/#628).
+
+This module is the producer-side (Python) half of the seam check: it reads
+the Rust struct definitions as text, finds `bool`-typed fields with no
+custom deserializer, and cross-references them against the live SQLite
+schema. ``tests/test_board_fixture.py`` wires this up against the real
+``tui/src/app/types.rs`` + a freshly-migrated DB so CI goes red the moment
+someone adds an unguarded INTEGER-backed bool field.
+"""
+
+from __future__ import annotations
+
+import re
+
+# Matches `#[attr] #[attr] ... pub(crate) <name>: bool,` — i.e. a struct
+# field typed as a plain `bool` (not `Option<bool>`, not some wrapper type).
+# `attrs` captures every `#[...]` attribute line directly above the field so
+# we can check it for a `deserialize_with` guard and/or a `rename`.
+_BOOL_FIELD_RE = re.compile(
+    r"(?P<attrs>(?:[ \t]*#\[[^\]]*\]\s*\n)*)"
+    r"[ \t]*pub\(crate\)\s+(?P<name>[A-Za-z_][A-Za-z0-9_]*):\s*bool,",
+)
+_RENAME_RE = re.compile(r'rename\s*=\s*"([^"]+)"')
+
+
+def find_unguarded_bool_fields(rust_src: str) -> dict[str, str]:
+    """Return ``{wire_key: field_name}`` for `bool` struct fields in *rust_src*
+    that have no `deserialize_with` attribute.
+
+    Such fields require the wire to send a literal JSON `true`/`false` — a
+    SQLite-style `0`/`1` integer fails the whole containing struct's parse.
+    """
+    out: dict[str, str] = {}
+    for m in _BOOL_FIELD_RE.finditer(rust_src):
+        attrs = m.group("attrs")
+        if "deserialize_with" in attrs:
+            continue  # guarded — e.g. de_bool_from_int_or_bool
+        name = m.group("name")
+        rename = _RENAME_RE.search(attrs)
+        wire_key = rename.group(1) if rename else name
+        out[wire_key] = name
+    return out
+
+
+def find_integer_bool_mismatches(
+    rust_src: str, schema_columns: dict[str, dict[str, str]]
+) -> list[str]:
+    """Cross-reference unguarded Rust `bool` fields against SQLite column types.
+
+    ``schema_columns`` maps table name -> ``{column_name: declared_type}``
+    (as ``PRAGMA table_info`` reports it, e.g. ``"INTEGER"``, ``"TEXT"``).
+
+    Returns ``"<table>.<column>"`` for every unguarded `bool` field whose
+    wire key matches a column declared ``INTEGER`` — the exact #632 trigger.
+    Empty list means the seam is safe.
+    """
+    unguarded = find_unguarded_bool_fields(rust_src)
+    mismatches: list[str] = []
+    for table, cols in sorted(schema_columns.items()):
+        for col, decl_type in sorted(cols.items()):
+            if col in unguarded and decl_type.upper().startswith("INTEGER"):
+                mismatches.append(f"{table}.{col}")
+    return mismatches

coord/board_service.py

@@ -0,0 +1,141 @@
+"""``BoardService`` facade (#749): decide local-vs-daemon ONCE, for both reads
+and writes, instead of re-implementing the ``resolve_board_service()`` +
+local-fallback dance at every call site.
+
+Before this module, ~30 call sites across ``coord/commands/*.py``,
+``coord/dashboard/server.py`` and ``coord/auto_loop.py`` each hand-rolled:
+
+    svc = resolve_board_service()
+    board = fetch_remote_board(svc) if svc else (load_board() or build_board())
+    ...mutate board...
+    save_board(board)  # silently a no-op on a thin client — the #749 bug
+
+``read_board()`` / ``write_board()`` below are the one place that decision is
+made. ``write_board()`` POSTs to the daemon's generic ``/board`` upsert
+endpoint when ``board_service`` is configured, so a thin client's mutation
+actually reaches the shared DB instead of vanishing into an empty local one.
+
+This module also hosts ``route_write()``, which centralizes the
+``resolve_board_service()`` + ``coord.client.post_record`` dance duplicated
+~13x across ``coord.state``'s per-mutation routing wrappers
+(``record_dispatched``, ``record_test_verdict``, ``update_issue_labels``,
+…) — so ``coord.state`` depends on this thin facade rather than importing
+``coord.client`` directly at over a dozen sites (#749's "reduce state.py's
+outward coupling toward a pure DAO").
+
+Whole-command re-routing (``coord merge``, ``coord reconcile-merges``,
+``coord diagnose``, ``coord housekeeping`` — where the ENTIRE command runs on
+the daemon and streams back its own textual/structured output, rather than a
+generic board upsert) is a different shape and stays in its own commands;
+``daemon_reroute_target()`` here only DRYs up the repeated
+"resolve + check the re-entrancy env guard" preamble those four call sites
+share.
+"""
+
+from __future__ import annotations
+
+import os
+
+from coord.models import Board
+
+
+def resolve():  # -> coord.client.ServiceConfig | None
+    """Resolve the configured board service, or ``None`` for local/host mode."""
+    from coord.client import resolve_board_service  # noqa: PLC0415
+
+    return resolve_board_service()
+
+
+def is_remote() -> bool:
+    """Whether this process is a thin client (``board_service`` configured)."""
+    return resolve() is not None
+
+
+def read_board() -> Board:
+    """Return the current board.
+
+    Daemon-configured → GET /board and reconstruct it. Otherwise → the local
+    DB (``load_board()``, falling back to ``build_board()`` when the board has
+    never been saved). This is the single place that decision is made; every
+    call site that used to duplicate
+    ``fetch_remote_board(svc) if svc else (load_board() or build_board())``
+    should call this instead.
+    """
+    svc = resolve()
+    if svc is not None:
+        from coord.client import fetch_remote_board  # noqa: PLC0415
+
+        return fetch_remote_board(svc)
+    from coord.state import build_board, load_board  # noqa: PLC0415
+
+    return load_board() or build_board()
+
+
+def write_board(board: Board) -> None:
+    """Persist *board*.
+
+    Daemon-configured → POST the full board to the daemon's ``/board`` upsert
+    endpoint (safe: upsert-only, never deletes — see
+    ``coord.client.serialize_board``). Otherwise → the local
+    ``coord.state.save_board``. Every call site that used to call
+    ``save_board(board)`` directly (and silently no-op on a thin client)
+    should call this instead.
+    """
+    svc = resolve()
+    if svc is not None:
+        from coord.client import post_board  # noqa: PLC0415
+
+        post_board(svc, board)
+        return
+    from coord.state import save_board  # noqa: PLC0415
+
+    save_board(board)
+
+
+def route_write(
+    svc,
+    endpoint: str,
+    payload: dict,
+    *,
+    timeout: float | None = None,
+) -> dict | None:
+    """POST *payload* to *endpoint* via *svc*, or ``None`` if *svc* is unset.
+
+    Centralizes the ``from coord.client import post_record`` + call dance
+    duplicated across ``coord.state``'s ``record_*`` / ``update_*`` routing
+    wrappers, so ``coord.state`` no longer needs its own deferred
+    ``coord.client`` import at each of those ~13 sites. Callers keep their own
+    ``svc = board_service.resolve()`` (they need the value regardless, to
+    decide whether to fall through to the local ``_*_local`` path) — this just
+    does the "POST it, or tell the caller there's nothing to POST to" part.
+
+    Returns ``None`` when *svc* is ``None`` (caller should run the local
+    path); otherwise returns the daemon's JSON response (never ``None``,
+    even for an empty ``{}`` body) so callers can distinguish "routed" from
+    "not routed" with a plain ``is not None`` check.
+    """
+    if svc is None:
+        return None
+    from coord.client import post_record  # noqa: PLC0415
+
+    if timeout is None:
+        return post_record(svc, endpoint, payload)
+    return post_record(svc, endpoint, payload, timeout=timeout)
+
+
+def daemon_reroute_target(env_var: str):  # -> coord.client.ServiceConfig | None
+    """Resolve the board service for a whole-command daemon re-route, or
+    ``None`` if the command should run locally.
+
+    Shared preamble for the four commands (``merge``, ``reconcile-merges``,
+    ``diagnose``, ``housekeeping``) that route their ENTIRE execution to the
+    daemon rather than doing a generic board upsert: each sets *env_var*
+    (e.g. ``COORD_MERGE_ON_DAEMON``) before re-invoking itself on the daemon
+    side, so the daemon's own execution doesn't try to re-route back out over
+    HTTP. Returns ``None`` (meaning "run locally") both when no board service
+    is configured AND when *env_var* is set (i.e. we ARE the daemon running
+    the re-routed-to invocation).
+    """
+    if os.environ.get(env_var):
+        return None
+    return resolve()

coord/board_wire.py

@@ -0,0 +1,309 @@
+"""Wire-bounding policy for the ``/board`` collection payload (#1337).
+
+**Invariant 2 of the /board read path: no collection endpoint returns
+unbounded text.**  The #762 fix bounded the board's *row count* (retention
+cap) — and the payload kept growing anyway, because the growth was in
+per-row text size: ``assignments.review_findings`` + ``issues.body`` alone
+were ~46 % of a 5.5 MB payload polled every few seconds.  Bounding rows
+while text grows per-row is how this failure class (#762 → #715 → #1336)
+kept coming back.
+
+This module is the single place the per-field wire policy lives:
+
+* **Preview fields** — ``review_findings`` (body inside the JSON envelope),
+  ``test_reason``, ``smoke_test_reason`` — are cut to a preview and flagged
+  with ``<field>_truncated: true`` (+ ``<field>_len``).  Consumers that need
+  the full text (fix-worker briefings, the TUI findings pane) fetch the
+  single-resource detail endpoint ``GET /assignment/{id}``.
+* **Bounded documents** — ``issues.body``, ``test_plan`` — get a *high* hard
+  cap that today truncates nothing real (issue-body p99 ≈ 9 KB, cap 16 KB)
+  but bounds the pathological row, because clients parse these semantically
+  (work orders, ``## Files`` globs) and an aggressive prefix cut would break
+  those parses.  **Tracking (epic) issue bodies are exempt entirely** — the
+  TUI's Milestone DAG parses ``## Work order`` client-side out of the full
+  body (see :func:`bound_issue_row`); GitHub's own 64 KB issue-body limit ×
+  the handful of epics per board keeps the exemption bounded.  Full body:
+  ``GET /issue/{repo}/{number}``.
+
+Everything here is wire-only: the DB row, the detail endpoints, and local
+(non-daemon) reads are untouched.  The bounded fields are also excluded from
+the whole-board upsert's UPDATE clause (``coord.state._UPSERT_SQL``), so a
+bounded preview can never round-trip over the full stored text via
+``POST /board``.
+
+Enforced by tests/test_board_read_path.py — a payload-budget test fails the
+suite if a seeded board's wire exceeds its budget, so instance #4 of this
+class shows up as a red test, not a fleet incident.
+
+**#1791 (instance #4): bounding row WIDTH was not enough.** #762 added a
+day-based retention cutoff at the DAO layer (``COORD_BOARD_RETENTION_DAYS``,
+default 14 — see ``coord/dao.py``), but a normal ~2-week stretch of fleet
+throughput still produced 904 terminal (done/merged/failed/advisory)
+assignment rows inside that window — none of them "old" yet — and 904 small,
+individually-width-bounded rows landed at the same 5.30 MB payload 90 large
+ones did pre-#1337. ``bound_board_payload`` below adds the collection-
+CARDINALITY bound this class of fix has been missing: it caps the
+*count* of terminal assignment rows on the wire
+(:data:`MAX_TERMINAL_ASSIGNMENTS`) and drops the body of closed (terminal)
+issues outright, on top of the existing per-field width caps. Both cuts are
+flagged on the payload (``board_truncated`` + counts) so a client can tell
+it received a trimmed board rather than the whole history — see
+:func:`bound_board_payload`.
+"""
+
+from __future__ import annotations
+
+import json
+
+from coord.dao import TERMINAL_STATUSES
+
+# Preview size for operator-facing free text.  Large enough that a short
+# review / test reason arrives whole; everything longer is a preview + flag.
+PREVIEW_CHARS = 2000
+# Hard cap for semantically-parsed documents (issue bodies, test plans).
+DOCUMENT_CHARS = 16384
+
+# #1791: how many *terminal* assignment rows the /board wire carries. This is
+# a SECOND, tighter bound than #762's day-based DAO cutoff — that cap bounds
+# board AGE, not board THROUGHPUT, so a busy fortnight still puts every one
+# of its terminal rows on the wire because none of them are "old" yet. Only
+# the most recent MAX_TERMINAL_ASSIGNMENTS terminal rows (by finished_at,
+# falling back to dispatched_at) ride the wire; active (non-terminal) rows
+# and the latest assignment of a still-open issue are NEVER subject to this
+# cap, regardless of how many terminal rows exist. Full history stays
+# reachable via GET /assignment/{id}.
+MAX_TERMINAL_ASSIGNMENTS = 200
+
+# #1791: named byte budget for the WHOLE /board payload. #1337 bounded
+# per-row WIDTH only (``BOARD payload budget`` in tests/test_board_read_path.py
+# guards that), so row CARDINALITY could still blow the same ceiling that
+# broke `coord report-result`'s 5s prefetch timeout in #1336 — exactly what
+# recurred in #1791 (5.30 MB, 904 of 906 assignment rows terminal). Enforced
+# by tests/test_board_wire.py::test_board_payload_budget_holds_at_terminal_row_scale,
+# seeded with THOUSANDS of terminal rows, so a fifth recurrence fails a
+# test, not a fleet check.
+BOARD_PAYLOAD_BYTE_BUDGET = 2_500_000
+
+# Appended to truncated *plain-text* fields so a human reading the preview
+# (TUI pane, dialog) knows it is one — machine consumers use the flags.
+TRUNCATION_NOTICE = "\n… [truncated on the /board wire — full text: detail endpoint]"
+
+
+def _preview(text: str, cap: int) -> str:
+    return text[:cap] + TRUNCATION_NOTICE
+
+
+def _bound_text_field(row: dict, field: str, cap: int) -> None:
+    """Truncate ``row[field]`` to *cap* chars, stamping ``<field>_truncated``
+    and ``<field>_len`` when it was cut.  Flags are additive-only (absent when
+    nothing was cut) so old clients see an unchanged shape."""
+    val = row.get(field)
+    if not isinstance(val, str) or len(val) <= cap:
+        return
+    row[f"{field}_len"] = len(val)
+    row[f"{field}_truncated"] = True
+    row[field] = _preview(val, cap)
+
+
+def _bound_review_findings(row: dict, cap: int) -> None:
+    """Envelope-aware preview for ``review_findings``.
+
+    The column is a JSON envelope ``{"verdict": ..., "body": ...}`` kept as a
+    *raw string* on the wire (the TUI parses it).  Truncating the raw string
+    would corrupt the JSON, so parse, preview the body inside, and
+    re-serialize — the verdict always survives intact.  A legacy/unparseable
+    blob falls back to plain-text truncation.
+    """
+    raw = row.get("review_findings")
+    if not isinstance(raw, str) or len(raw) <= cap:
+        return
+    row["review_findings_len"] = len(raw)
+    row["review_findings_truncated"] = True
+    try:
+        env = json.loads(raw)
+    except (json.JSONDecodeError, TypeError):
+        env = None
+    if isinstance(env, dict) and isinstance(env.get("body"), str):
+        env["body"] = _preview(env["body"], cap)
+        env["truncated"] = True
+        row["review_findings"] = json.dumps(env)
+    else:
+        row["review_findings"] = raw[:cap]
+
+
+def _bound_test_plan(row: dict, cap: int) -> None:
+    """``test_plan`` is a decoded ``{"steps": [...]}`` object on the wire —
+    a prefix cut is meaningless, so a pathological plan is dropped whole
+    (flagged); the TUI's existing ``None`` handling shows its placeholder and
+    the detail endpoint serves the full plan."""
+    val = row.get("test_plan")
+    if val is None:
+        return
+    try:
+        size = len(json.dumps(val))
+    except (TypeError, ValueError):
+        return
+    if size <= cap:
+        return
+    row["test_plan_len"] = size
+    row["test_plan_truncated"] = True
+    row["test_plan"] = None
+
+
+def bound_assignment_row(row: dict) -> None:
+    """Apply the wire policy to one ``/board`` assignment row (mutates)."""
+    _bound_review_findings(row, PREVIEW_CHARS)
+    _bound_text_field(row, "test_reason", PREVIEW_CHARS)
+    _bound_text_field(row, "smoke_test_reason", PREVIEW_CHARS)
+    _bound_text_field(row, "failure_reason", PREVIEW_CHARS)
+    _bound_test_plan(row, DOCUMENT_CHARS)
+
+
+def _is_tracking_issue(row: dict) -> bool:
+    """True when the issue carries the milestone-tracking (epic) label."""
+    from coord.milestone_order import TRACKING_ISSUE_LABEL  # noqa: PLC0415
+
+    labels = row.get("labels")
+    return isinstance(labels, list) and TRACKING_ISSUE_LABEL in labels
+
+
+def _is_closed_issue(row: dict) -> bool:
+    state = row.get("state")
+    return isinstance(state, str) and state.strip().lower() == "closed"
+
+
+def bound_issue_row(row: dict) -> None:
+    """Apply the wire policy to one ``/board`` issue row (mutates).
+
+    **Tracking (epic) issues are exempt from the body cap.**  The TUI's
+    Milestone DAG parses ``## Work order`` out of the tracking issue's body
+    *client-side* (`milestone_dag.rs::milestones_with_work_orders` — it does
+    NOT consume the server-computed ``milestone_work_orders``, which drops
+    terminal nodes and carries no ``after``-edges), so a cap that cuts
+    work-order items past DOCUMENT_CHARS would silently drop DAG nodes on
+    thin clients — a regression in exactly the failure class #1337 exists to
+    close.  The exemption stays bounded in practice: an epic body is capped
+    at 65,536 chars by GitHub itself and boards carry few epics (~31 today,
+    0.19 MB total).
+
+    **Closed (non-epic) issues drop the body entirely** (#1791): a closed
+    issue is terminal — no pipeline decision, client-side or server-side,
+    reads its body once it's closed — and #1337's DOCUMENT_CHARS cap alone
+    still left 110 closed issues carrying 0.57 MB on every /board GET. Full
+    text stays on ``GET /issue/{repo}/{number}``. Open (non-epic) issue
+    bodies — the ones ``pipeline.rs``'s ``acceptance_for_path_arg`` and
+    ``dialogs.rs`` parse client-side — keep the DOCUMENT_CHARS cap
+    unchanged.
+    """
+    if _is_tracking_issue(row):
+        return
+    if _is_closed_issue(row):
+        _bound_text_field(row, "body", 0)
+        return
+    _bound_text_field(row, "body", DOCUMENT_CHARS)
+
+
+def _open_issue_keys(issues) -> set[tuple[str, int]]:
+    """``(repo_name, number)`` of every non-closed issue in the projection."""
+    keys: set[tuple[str, int]] = set()
+    for row in issues:
+        if not isinstance(row, dict) or _is_closed_issue(row):
+            continue
+        repo_name, number = row.get("repo_name"), row.get("number")
+        if repo_name is not None and number is not None:
+            keys.add((repo_name, number))
+    return keys
+
+
+def cap_terminal_assignments(
+    assignments: list[dict], open_issue_keys: set[tuple[str, int]]
+) -> int:
+    """Cap ``assignments`` (mutated in place) to :data:`MAX_TERMINAL_ASSIGNMENTS`
+    terminal rows (#1791).  Returns the number of rows dropped.
+
+    A row is PROTECTED — never dropped, regardless of how many terminal rows
+    exist — when it is active (status not in ``TERMINAL_STATUSES``) or is
+    tied to a still-open issue.  That mirrors
+    ``coord.dao.compute_board_keep_ids``'s "latest assignment of an open
+    issue" rule, so this second, tighter cut can never undo that guarantee.
+    Among the remaining terminal rows, the most recent
+    ``MAX_TERMINAL_ASSIGNMENTS`` (by ``finished_at``, falling back to
+    ``dispatched_at``) are kept; the cut is then closed over
+    ``review_of_assignment_id`` in both directions — same closure rule as
+    ``compute_board_keep_ids`` — so an in-flight review never loses its
+    target and a kept row never loses an in-flight review.
+    """
+    original_count = len(assignments)
+    protected: list[dict] = []
+    terminal: list[dict] = []
+    for row in assignments:
+        status = (row.get("status") or "").lower()
+        key = (row.get("repo_name"), row.get("issue_number"))
+        if status not in TERMINAL_STATUSES or key in open_issue_keys:
+            protected.append(row)
+        else:
+            terminal.append(row)
+
+    if len(terminal) <= MAX_TERMINAL_ASSIGNMENTS:
+        return 0
+
+    terminal.sort(
+        key=lambda r: r.get("finished_at") or r.get("dispatched_at") or 0.0,
+        reverse=True,
+    )
+    keep_ids = {
+        r.get("assignment_id")
+        for r in protected + terminal[:MAX_TERMINAL_ASSIGNMENTS]
+        if r.get("assignment_id")
+    }
+
+    by_id = {r.get("assignment_id"): r for r in assignments if r.get("assignment_id")}
+    reviews_of: dict[str, list[str]] = {}
+    for aid, r in by_id.items():
+        tgt = r.get("review_of_assignment_id")
+        if tgt:
+            reviews_of.setdefault(tgt, []).append(aid)
+    frontier = list(keep_ids)
+    while frontier:
+        aid = frontier.pop()
+        tgt = by_id.get(aid, {}).get("review_of_assignment_id")
+        if tgt and tgt in by_id and tgt not in keep_ids:
+            keep_ids.add(tgt)
+            frontier.append(tgt)
+        for rev in reviews_of.get(aid, ()):
+            if rev not in keep_ids:
+                keep_ids.add(rev)
+                frontier.append(rev)
+
+    assignments[:] = [r for r in assignments if r.get("assignment_id") in keep_ids]
+    return original_count - len(assignments)
+
+
+def bound_board_payload(projection: dict) -> None:
+    """Bound every unbounded free-text field AND the collection's row count
+    in a ``/board`` projection (#1337 bounded width; #1791 adds cardinality).
+
+    Called by the daemon's board builder AFTER the derived sections
+    (milestone work orders, plan roster, epic children) are computed — those
+    parse full issue bodies server-side and must see them unbounded.
+    """
+    issues = projection.get("issues")
+    assignments = projection.get("assignments")
+
+    dropped = 0
+    if isinstance(assignments, list) and isinstance(issues, (list, tuple)):
+        dropped = cap_terminal_assignments(assignments, _open_issue_keys(issues))
+
+    for row in projection.get("assignments", ()):
+        if isinstance(row, dict):
+            bound_assignment_row(row)
+    for row in projection.get("issues", ()):
+        if isinstance(row, dict):
+            bound_issue_row(row)
+
+    # #1791: truncation must be visible to clients — additive-only, same
+    # convention as the per-field ``<field>_truncated`` flags above, so a
+    # client that never received a trimmed board sees an unchanged shape.
+    if dropped:
+        projection["board_truncated"] = True
+        projection["board_truncated_assignments"] = dropped