cctally 1.91.0 → 1.92.1

package/bin/_cctally_config.py

@@ -307,6 +307,7 @@ ALLOWED_CONFIG_KEYS = (
     "dashboard.expose_transcripts",
     "dashboard.cache_failure_markers",
     "dashboard.live_tail",
+    "dashboard.lan_auth",
     "update.check.enabled",
     "update.check.ttl_hours",
     "update.channel",
@@ -1028,6 +1029,22 @@ def _config_known_value(config: dict, key: str) -> "object":
             except ValueError:
                 return True
         return True
+    if key == "dashboard.lan_auth":
+        # Boolean opt-OUT (issue #282). Default TRUE — non-loopback dashboard
+        # runs require their per-run access token unless the user explicitly
+        # disables the gate. Invalid hand edits fail safe to authentication ON.
+        block = config.get("dashboard") if isinstance(config, dict) else None
+        if not isinstance(block, dict):
+            block = {}
+        stored = block.get("lan_auth")
+        if stored is None:
+            return True
+        if isinstance(stored, bool):
+            return stored
+        # The config command normalizes accepted text spellings before write.
+        # A persisted string is therefore a hand edit, not an explicit opt-out;
+        # accept only the JSON boolean false at this security boundary.
+        return True
     if key == "telemetry.enabled":
         # Boolean opt-OUT (anonymous install-count telemetry, spec 2026-07-07).
         # Default TRUE — absence is ON. A hand-edited junk value surfaces the
@@ -1623,6 +1640,34 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
         else:
             print(f"dashboard.live_tail={'true' if canonical else 'false'}")
         return 0
+    if key == "dashboard.lan_auth":
+        try:
+            canonical = c._normalize_alerts_enabled_value(raw)
+        except ValueError:
+            print(
+                f"cctally: invalid boolean value for dashboard.lan_auth: "
+                f"{raw!r} (expected true|false|yes|no|1|0|on|off)",
+                file=sys.stderr,
+            )
+            return 2
+        with config_writer_lock():
+            config = _load_config_unlocked()
+            existing = config.get("dashboard")
+            if existing is not None and not isinstance(existing, dict):
+                print(
+                    "cctally: dashboard config error: dashboard must be an object",
+                    file=sys.stderr,
+                )
+                return 2
+            block = dict(existing or {})
+            block["lan_auth"] = canonical
+            config["dashboard"] = block
+            save_config(config)
+        if getattr(args, "emit_json", False):
+            print(json.dumps({"dashboard": {"lan_auth": canonical}}, indent=2))
+        else:
+            print(f"dashboard.lan_auth={'true' if canonical else 'false'}")
+        return 0
     if key == "telemetry.enabled":
         # Anonymous install-count telemetry opt-out (spec 2026-07-07). Mirror
         # dashboard.live_tail exactly: validate the bool first, then
@@ -2237,6 +2282,18 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
                 save_config(config)
             # idempotent: silent on missing key
         return 0
+    if key == "dashboard.lan_auth":
+        # Restart-only opt-out. Removing the leaf restores the safe True
+        # default while preserving all sibling dashboard preferences.
+        with config_writer_lock():
+            config = _load_config_unlocked()
+            block = config.get("dashboard")
+            if isinstance(block, dict) and "lan_auth" in block:
+                del block["lan_auth"]
+                if not block:
+                    config.pop("dashboard", None)
+                save_config(config)
+        return 0
     if key == "telemetry.enabled":
         # Mirror the dashboard.live_tail unset branch: drop only the enabled
         # leaf; if the telemetry block ends up empty, drop the parent too.

package/bin/_cctally_core.py

@@ -364,9 +364,49 @@ STATS_WAL_SIZE_LIMIT_BYTES = 16 * 1024 * 1024  # 16777216
 # full pass is measured against. Same mechanical reason as 1005 — an
 # epoch-current open returns before any schema work — so it is a second bump
 # rather than an amendment to the first.
-STATS_INDEX_EPOCH = 1006
+# 1006 -> 1007 (#460): scheduled quota-alert ownership. Adds the per-root
+# future-capture schedule that lets a matured boundary widen to its owning root
+# instead of deferring forever on a quiet hook-only install.
+# 1007 -> 1008 (#496 S3): in-place transactional publication. Adds
+# `stats_publication_stamp`, the publication identity written inside the
+# publication transaction. It replaces the marker's `scratchPath` crash
+# discriminator, which an in-place publish inverts because it attaches the
+# scratch read-only and leaves it on disk whether the transaction committed or
+# rolled back. A stats schema change is an epoch bump and never a migration;
+# the 13-migration registry stays frozen. Each install pays one rebuild on
+# upgrade, deferred to the background worker by #453.
+STATS_INDEX_EPOCH = 1008
 LEGACY_STATS_HEAD = 13
 
+#: #496 S1 F1. A NEW branch, for a state that cannot occur before the
+#: publication transaction exists: a replacement index was published and then
+#: failed validation on a fresh connection. The existing corrupt-stats text
+#: says the database was "Not auto-recreated", which would be false here, so
+#: this path gets its own wording. It does not alter the heal message or any
+#: other corruption path.
+STATS_PUBLICATION_FAILED_MSG = (
+    "stats.db published a rebuilt index that then FAILED validation, so the "
+    "live index is known bad and cctally refuses to use it. path: {path}. "
+    "The rebuild record naming the failing check is at {record}. The damaged "
+    "predecessor was preserved under quarantine/ with a forensics bundle in "
+    "logs/. Recovery: run `cctally db rebuild --db stats`."
+)
+
+#: #496 S3. The text above describes PHYSICAL replacement, which is now the
+#: fallback. In-place publication drops the live generation and installs the
+#: scratch's inside one transaction, so it preserves nothing and allocates no
+#: quarantine directory — and the sentence about a preserved predecessor would
+#: send a user whose index is already known bad to a directory that does not
+#: exist. Selected by the mechanism the publication marker records.
+STATS_PUBLICATION_FAILED_IN_PLACE_MSG = (
+    "stats.db published a rebuilt index that then FAILED validation, so the "
+    "live index is known bad and cctally refuses to use it. path: {path}. "
+    "The rebuild record naming the failing check is at {record}. This index "
+    "was published in place, so no copy of the previous index was kept; every "
+    "row it holds is derived from the append-only journal, which the "
+    "publication did not touch. Recovery: run `cctally db rebuild --db stats`."
+)
+
 
 # === Telemetry constants (non-path; see spec 2026-07-07) =============
 #
@@ -705,18 +745,27 @@ def ensure_dirs() -> None:
 # before returning does not, and must not — see `stats_open_guarded`):
 #   bin/_cctally_journal.py  _acquire_maintenance_{shared,exclusive} / _release
 #   bin/_cctally_store.py    _heal_flock_blocking, reached through
-#                            _acquire_stats_maintenance_reentrant by the heal
-#                            hook and the epoch resolver
+#                            _acquire_stats_maintenance_reentrant by the epoch
+#                            resolver
+#   bin/_cctally_store.py    _acquire_stats_maintenance_for_heal, the corruption
+#                            heal's ownership-first BOUNDED acquire (#496 S3)
 #   bin/_cctally_db.py       cmd_db_rebuild, _acquire_db_admin_writer_flocks
 #                            (db skip / db unskip), _cmd_db_repair_exclusive,
 #                            _vacuum_one_db
 #   bin/_cctally_rederive.py _rederive_locks
+#   bin/_cctally_store.py    stats_open_guarded's interrupted-rebuild-recovery
+#                            branch, which upgrades to EXCLUSIVE and then calls
+#                            rebuild_stats_index (#496 S3)
 # Adding another acquisition site without noting it here reintroduces the hang.
 #
-# The opener (`_cctally_store.stats_open_guarded`) takes the lock SHARED and
-# releases it before handing the connection back, so it deliberately does NOT
-# note a hold — but it DOES consult `holds_stats_maintenance()` to skip the
-# acquire entirely when this context already owns the exclusive side.
+# The opener (`_cctally_store.stats_open_guarded`) takes the lock SHARED around
+# an ordinary open and releases it before handing the connection back, so that
+# acquire deliberately does NOT note a hold — but it DOES consult
+# `holds_stats_maintenance()` to skip the acquire entirely when this context
+# already owns the exclusive side. Its interrupted-rebuild-recovery branch is
+# the exception: that one upgrades to EXCLUSIVE and holds it across a rebuild,
+# whose in-place publisher opens the destination through `stats_open_guarded`
+# again, so it notes the hold like every other exclusive site.
 
 _STATS_MAINTENANCE_HELD = contextvars.ContextVar(
     "cctally_stats_maintenance_held", default=0
@@ -1369,6 +1418,9 @@ def _apply_quota_projection_schema(conn: sqlite3.Connection) -> None:
         -- that are not functions of window dirtiness — a delivery-gate
         -- transition, and a future-clocked observation that becomes eligible
         -- when wall time passes it with no row mutation at all.
+        -- `next_evaluation_by_root_json` owns that scalar minimum: one earliest
+        -- future capture per root, so a due hook tick can reconcile only the
+        -- roots whose instants matured.
         --
         -- `last_full_pass_at` is the periodic verification's deadline. Two
         -- cases a scoped sweep structurally cannot see — a block whose physical
@@ -1386,6 +1438,7 @@ def _apply_quota_projection_schema(conn: sqlite3.Connection) -> None:
             alerts_enabled         INTEGER,
             next_evaluation_at_utc TEXT,
             last_full_pass_at      TEXT,
+            next_evaluation_by_root_json TEXT NOT NULL DEFAULT '{}',
             PRIMARY KEY(source)
         );
 
@@ -1417,14 +1470,19 @@ def _apply_quota_projection_schema(conn: sqlite3.Connection) -> None:
     }
     if "account_key" not in _proj_cols:
         conn.execute("DROP TABLE quota_projection_state")
+        # SQLite stores `sqlite_schema.sql` verbatim apart from stripping
+        # `IF NOT EXISTS`, and `_stats_schema_fingerprint` hashes that text, so
+        # this body must stay character-for-character equal to the fresh-path
+        # definition above (#496 S1 F18).
         conn.execute(
-            "CREATE TABLE quota_projection_state ("
-            " source_root_key TEXT NOT NULL,"
-            " account_key TEXT NOT NULL DEFAULT 'unattributed',"
-            " generation TEXT NOT NULL,"
-            " physical_signature TEXT NOT NULL,"
-            " completed_at_utc TEXT NOT NULL,"
-            " PRIMARY KEY(source_root_key, account_key))"
+            "CREATE TABLE quota_projection_state (\n"
+            "            source_root_key    TEXT NOT NULL,\n"
+            "            account_key        TEXT NOT NULL DEFAULT 'unattributed',\n"
+            "            generation         TEXT NOT NULL,\n"
+            "            physical_signature TEXT NOT NULL,\n"
+            "            completed_at_utc   TEXT NOT NULL,\n"
+            "            PRIMARY KEY(source_root_key, account_key)\n"
+            "        )"
         )
     if add_column_if_missing is not None:
         for _tbl in ("quota_window_blocks", "quota_percent_milestones",
@@ -1445,6 +1503,11 @@ def _apply_quota_projection_schema(conn: sqlite3.Connection) -> None:
         # no-op over the table it already has.
         add_column_if_missing(
             conn, "quota_projection_ledger_state", "last_full_pass_at", "TEXT")
+        # Epoch 1007 / #460: same legacy-cutover seam. Current-epoch indexes
+        # rebuild; a legacy index cuts over in place and needs the column added.
+        add_column_if_missing(
+            conn, "quota_projection_ledger_state",
+            "next_evaluation_by_root_json", "TEXT NOT NULL DEFAULT '{}'")
 
 
 def open_db(*, _target_path=None) -> sqlite3.Connection:
@@ -2444,6 +2507,23 @@ def open_db(*, _target_path=None) -> sqlite3.Connection:
             "kind TEXT NOT NULL, "
             "violation_json TEXT NOT NULL)"
         )
+        # In-place publication identity (#496 S3 §5). An in-place publish
+        # attaches the scratch read-only and detaches it, so the scratch
+        # survives commit and rollback identically and the publication marker's
+        # `scratchPath` proxy inverts. This row is written INSIDE the
+        # publication transaction, so it commits atomically with the content
+        # and the `user_version` it describes and a crash before the commit
+        # rolls it back. The opener compares it against the marker's
+        # `recordPath` and knows without inference whether that publication
+        # committed. Holds at most one row; single-row-ness is deliberately not
+        # enforced structurally, because a duplicated row is one of the states
+        # that must resolve INDETERMINATE rather than be made impossible.
+        conn.execute(
+            "CREATE TABLE IF NOT EXISTS stats_publication_stamp ("
+            "record_path TEXT NOT NULL, "
+            "started_at_utc TEXT NOT NULL, "
+            "stamped_at_utc TEXT NOT NULL)"
+        )
 
         # §6.2 backfill gate (Task 8): stamp the one-shot marker AFTER the three
         # open-time backfills ran, so the next open skips them (and their probes)