cctally 1.92.2 → 1.93.0

package/bin/_cctally_core.py

@@ -375,7 +375,16 @@ STATS_WAL_SIZE_LIMIT_BYTES = 16 * 1024 * 1024  # 16777216
 # 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
+# 1008 -> 1009 (#496 S5b): durable replay selection. Adds the three
+# `journal_selector_*` tables reproducing `resolve_effective_events`' six
+# accumulators, `stats_quota_projection_state` (reserved by Stage 1, set by
+# Stage 3), plus `journal_effective_events.winning_sequence` /
+# `.conflict_hashes_json` and `journal_protocol_violations.available_after`.
+# Same mechanical reason as every bump since 1005: an epoch-current open returns
+# before any schema work, so an `add_column_if_missing` would never run on an
+# upgraded install and the column would simply never appear. The registry stays
+# frozen at 13 and an epoch mismatch resolves by rebuild.
+STATS_INDEX_EPOCH = 1009
 LEGACY_STATS_HEAD = 13
 
 #: #496 S1 F1. A NEW branch, for a state that cannot occur before the
@@ -777,6 +786,43 @@ def holds_stats_maintenance() -> bool:
     return _STATS_MAINTENANCE_HELD.get() > 0
 
 
+# === #496 S5b §4.7 open-time quota-projection reconciliation (opt-in) ======
+#
+# A rebuild that published a valid index over a cache with an uncovered
+# remainder durably marks its quota projection incomplete, and some later open
+# has to resume that recovery or the gate never lifts. `open_db` is where that
+# resumption lives, but it is NOT something every open may pay: `open_db` runs
+# on `cctally statusline` and on every hook tick, and the resumption reads the
+# journal from zero to the current high water — the 1.64 GB working set the S4
+# measurements describe — before it can apply anything.
+#
+# So the trigger is armed per process rather than unconditional. A maintenance
+# command that is already doing journal-scale work arms it; the interactive
+# render paths never do, and pay only the one indexed flag SELECT that was
+# already there. A process global rather than a ContextVar deliberately: this
+# is a property of the COMMAND that is running, not of one thread inside it,
+# and the dashboard arms it once for the whole server.
+QUOTA_PROJECTION_RECONCILE_ENABLED = False
+
+
+def enable_quota_projection_reconciliation() -> None:
+    """Arm the open-time quota-projection reconciliation for this process.
+
+    A PROCESS global, deliberately, and not a ContextVar or a thread-local: the
+    two armers are `cmd_cache_sync` and `cmd_dashboard`, and the dashboard has
+    no dedicated maintenance thread to hang a thread-local on. So in the
+    dashboard whichever thread reaches `open_db` first runs the attempt, and one
+    attempt can stall that thread while it holds the maintenance flock. That is
+    accepted rather than overlooked: the attempt takes every lock
+    non-blocking and returns immediately when any is busy, the throttle bounds
+    the repeat to one per interval, and the alternative — routing this through a
+    worker the dashboard does not currently have — is a larger change than the
+    contention it would avoid.
+    """
+    global QUOTA_PROJECTION_RECONCILE_ENABLED
+    QUOTA_PROJECTION_RECONCILE_ENABLED = True
+
+
 # === stats.db sanctioned-write scope (#386) =========================
 #
 # The state behind `_cctally_store.stats_write_scope` / `in_stats_write_scope`
@@ -1537,6 +1583,35 @@ def open_db(*, _target_path=None) -> sqlite3.Connection:
     _reconcile_durable_applied_migration_errors = (
         c._reconcile_durable_applied_migration_errors
     )
+
+    def _reconcile_incomplete_quota_projection(_conn):
+        """#496 S5b §4.7's open-time gate, reached only on the steady-state path.
+
+        A rebuild that published a valid index over a cache with an uncovered
+        remainder durably marks its quota projection incomplete, and every
+        projection read is then gated. Some open has to be able to resume that
+        recovery, or the gate never lifts. Everything past the flag probe lives
+        in `_cctally_journal`, which owns the recovery leg and the lock order;
+        the reach is call-time for the same reason the opener policy's is.
+
+        ARMED PROCESSES ONLY. The resumption reads the whole journal, and this
+        function is reached by `cctally statusline` and by every hook tick. An
+        unarmed process returns here, before the `_cctally_journal` import — so
+        an interactive render pays neither the import nor the read. See
+        `enable_quota_projection_reconciliation`.
+
+        Any failure is swallowed. This runs on the hot open path, and a
+        reconciliation that cannot proceed must leave the flag set — the
+        fail-closed direction — rather than fail an unrelated command.
+        """
+        if not QUOTA_PROJECTION_RECONCILE_ENABLED:
+            return
+        try:
+            import importlib as _il
+            _il.import_module(
+                "_cctally_journal").reconcile_incomplete_quota_projection(_conn)
+        except Exception:
+            return
     # Unified opener policy (spec §6.1). Call-time import so the shared PRAGMA
     # policy applies without a module-load cycle (_cctally_store imports this
     # module). Routed through importlib.import_module rather than a bare
@@ -1663,6 +1738,7 @@ def open_db(*, _target_path=None) -> sqlite3.Connection:
                 _reconcile_durable_applied_migration_errors(
                     conn, _STATS_MIGRATIONS, "stats.db"
                 )
+                _reconcile_incomplete_quota_projection(conn)
             return conn
         if _target_path is None:
             if _uv > LEGACY_STATS_HEAD:
@@ -2488,6 +2564,15 @@ def open_db(*, _target_path=None) -> sqlite3.Connection:
         # the append-only journal; rebuild repopulates this table from the shared
         # pure selector. The table lets live replay detect completed corrections
         # without inventing family-specific inverse operations.
+        # `winning_sequence` and `conflict_hashes_json` (#496 S5b §3.2) complete
+        # this table into the selector's whole per-event accumulator, which is
+        # why S5b adds NO per-candidate table: same-revision containment needs
+        # only the winning revision, the lowest-sequence winner and the set of
+        # distinct content hashes observed at that revision, and this table is
+        # already keyed one row per event id. The columns are declared HERE
+        # rather than added by `add_column_if_missing`, because this is an epoch
+        # bump: an epoch-current open returns before any schema work, so a
+        # conditional column addition would never run on an upgraded install.
         conn.execute(
             "CREATE TABLE IF NOT EXISTS journal_effective_events ("
             "event_id TEXT PRIMARY KEY, "
@@ -2495,17 +2580,109 @@ def open_db(*, _target_path=None) -> sqlite3.Connection:
             "status TEXT NOT NULL CHECK (status IN ('active','tombstone')), "
             "content_hash TEXT NOT NULL, "
             "batch_id TEXT, "
-            "event_json TEXT)"
+            "event_json TEXT, "
+            "winning_sequence INTEGER, "
+            "conflict_hashes_json TEXT)"
         )
         # Disposable selector diagnostics (#402 Task A). The append-only journal
         # remains authoritative; rebuild/live preflight replace this bounded
         # summary after a complete correction-prefix selection.
+        #
+        # `available_after` (#496 S5b §3.2) is the selector's per-fingerprint
+        # minimum sequence: a `journal_protocol_resolution` op that precedes it
+        # is fatal, so an incremental pass that cannot re-derive it cannot
+        # decide whether a resolution is legitimate.
         conn.execute(
             "CREATE TABLE IF NOT EXISTS journal_protocol_violations ("
             "fingerprint TEXT PRIMARY KEY, "
             "batch_id TEXT NOT NULL, "
             "kind TEXT NOT NULL, "
-            "violation_json TEXT NOT NULL)"
+            "violation_json TEXT NOT NULL, "
+            "available_after INTEGER)"
+        )
+        # The primary key is the fingerprint, but every scoped selector read
+        # filters `WHERE batch_id IN (...)` — on the status-line path, once per
+        # merge tick. Without this index that is a full table scan, and the
+        # rows-read guard in `tests/test_live_selection_496_s5b.py` cannot see
+        # it: that proxy counts rows RETURNED, not rows scanned.
+        conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_journal_protocol_violations_batch "
+            "ON journal_protocol_violations(batch_id)"
+        )
+        # ── Durable selector state (#496 S5b §3.2) ──────────────────────────
+        # `resolve_effective_events` accumulates six things over the record
+        # stream and returns only a summary, so every live tick that meets a
+        # correction record re-derives them from the whole journal prefix. These
+        # three tables reproduce those six accumulators and nothing more, which
+        # is what lets a validated generation seed incrementally instead.
+        #
+        # They are OPERATIONALLY AUTHORITATIVE only inside a validated current
+        # generation. The journal remains ultimate truth: every rebuild, every
+        # stale-generation fallback, Model-A versus harvest emission, bootstrap
+        # handling and correction-batch application still derive from journal
+        # records. Durable selector state may ACCELERATE a validated generation
+        # and may never SUPERSEDE retained truth.
+        #
+        # One row, enforced structurally — unlike `stats_publication_stamp`,
+        # whose duplicate row is a state that must resolve INDETERMINATE and
+        # therefore may not be made impossible.
+        conn.execute(
+            "CREATE TABLE IF NOT EXISTS journal_selector_state ("
+            "id INTEGER PRIMARY KEY CHECK (id = 1), "
+            "generation_record_path TEXT, "
+            "generation_stamped_at_utc TEXT, "
+            "covered_segment TEXT, "
+            "covered_offset INTEGER, "
+            "next_sequence INTEGER NOT NULL DEFAULT 0, "
+            "selector_version INTEGER NOT NULL, "
+            # `cutover_seen` distinguishes "no cutover op exists" from "the op
+            # exists and recorded no account". A plain NULL cannot carry both
+            # answers, and conflating them re-runs the whole-journal cutover
+            # scan F20 exists to remove.
+            "cutover_seen INTEGER NOT NULL DEFAULT 0, "
+            "cutover_account_key TEXT)"
+        )
+        conn.execute(
+            "CREATE TABLE IF NOT EXISTS journal_selector_batches ("
+            "batch_id TEXT PRIMARY KEY, "
+            "status TEXT NOT NULL "
+            "  CHECK (status IN ('begin_only','completed','tainted')), "
+            "action_count INTEGER, "
+            "action_set_hash TEXT, "
+            "begin_segment TEXT, begin_offset INTEGER, "
+            "earliest_commit_segment TEXT, earliest_commit_offset INTEGER)"
+        )
+        # One row per marker and per action. A digest alone is not enough: when
+        # a batch completes, the selector rebuilds every action's canonical core
+        # to derive `actual_actions_hash`, and a split cycle — begin and actions
+        # in an earlier generation, commit in this tick — decides completion NOW
+        # from cores captured THEN. `action_core_json` is therefore retained
+        # while the batch is `begin_only` OR `tainted`, and dropped only on
+        # `completed`; an early taint does not end a batch's record stream.
+        conn.execute(
+            "CREATE TABLE IF NOT EXISTS journal_selector_batch_records ("
+            "batch_id TEXT NOT NULL, "
+            "kind TEXT NOT NULL CHECK (kind IN ('marker','action')), "
+            "key TEXT NOT NULL, "
+            "record_digest TEXT NOT NULL, "
+            "identity_digest TEXT, "
+            "sequence INTEGER NOT NULL, "
+            "action_core_json TEXT, "
+            "PRIMARY KEY (batch_id, kind, key))"
+        )
+        # Set only by Stage 3, reserved here so no stage depends on a table a
+        # later stage creates (#496 S5b §4.7). The stats quota projection is
+        # materialized FROM cache.db, so a partial cache recovery publishes a
+        # semantically partial projection inside the generation; the flag is the
+        # per-transaction gate that keeps that projection from being served. The
+        # target is VERSIONED, not a bare coordinate, so a target written by one
+        # binary is never misread by another.
+        conn.execute(
+            "CREATE TABLE IF NOT EXISTS stats_quota_projection_state ("
+            "id INTEGER PRIMARY KEY CHECK (id = 1), "
+            "incomplete INTEGER NOT NULL DEFAULT 0, "
+            "target_version INTEGER NOT NULL DEFAULT 0, "
+            "recovery_target_json TEXT)"
         )
         # In-place publication identity (#496 S3 §5). An in-place publish
         # attaches the scratch read-only and detaches it, so the scratch

package/bin/_cctally_dashboard.py

@@ -324,6 +324,40 @@ def _cctally():
     return sys.modules["cctally"]
 
 
+class _QuotaProjectionIncompleteUnavailable(BaseException):
+    """The unmatchable stand-in `_quota_projection_incomplete_cls` falls back to.
+
+    A `BaseException` subclass nothing raises, so an `except` clause given this
+    class matches no exception and the handler below it runs unchanged.
+    """
+
+
+def _quota_projection_incomplete_cls():
+    """`QuotaProjectionIncomplete`, resolved at call time (#496 S5b).
+
+    Call-time for the same reason `assert_projection_readable` is imported
+    inside its handlers: this module reaches `_cctally_quota` lazily, and an
+    `except` clause is evaluated only when an exception is being handled, so a
+    module-level import would buy nothing and add an import-order constraint.
+
+    Resolving it is therefore an import evaluated WHILE another exception is
+    already propagating, and an `ImportError` raised there would replace the
+    original exception and skip the generic handler that owns it. Both failure
+    modes answer with an unmatchable sentinel instead, so a resolution failure
+    degrades to the generic handler rather than to a different exception. The
+    class is deliberately NOT cached across calls: `_cctally_quota` is
+    re-imported into a fresh namespace by the test harness, and a cached class
+    object from an earlier namespace would stop matching the exception the
+    current one raises.
+    """
+    try:
+        import _cctally_quota
+
+        return _cctally_quota.QuotaProjectionIncomplete
+    except (ImportError, AttributeError):
+        return _QuotaProjectionIncompleteUnavailable
+
+
 # === Honest imports from extracted homes ===================================
 # Spec 2026-05-17-cctally-core-kernel-extraction.md §3.3: kernel symbols
 # import from _cctally_core; already-decentralized buckets (X = _lib_*,
@@ -698,7 +732,10 @@ def _build_codex_project_detail(context, qualified, observations, *, key: str) -
 
 def _build_codex_block_detail(context, observations, *, key: str) -> dict[str, Any]:
     from _lib_quota import build_blocks, forecast_quota, percent_milestones, quota_freshness
+    from _cctally_quota import assert_projection_readable
 
+    # BEFORE the SQL, per #496 S5b section 4.7.
+    assert_projection_readable(context.stats_conn)
     rows = context.stats_conn.execute(
         "SELECT source_root_key, logical_limit_key, observed_slot, window_minutes, "
         "limit_name, resets_at_utc, current_percent, orphaned_at "
@@ -2942,7 +2979,8 @@ def _dashboard_build_daily_panel(conn: "sqlite3.Connection",
 #                       resolves to `foo (parent_dir)`).
 #   - ``bucket_path`` = canonical equality key (``ProjectKey.bucket_path``)
 #                       — the absolute on-disk path. Privacy-sensitive;
-#                       _lib_share._scrub strips it on the share path.
+#                       _lib_share.render()/compose() prepare it away on
+#                       the share path.
 
 # Per-tick memo (spec §6.4 + memory: *Pre-probe before sync_cache*).
 # Keyed on (max(session_entries.id), current_week.week_start_at,
@@ -6320,6 +6358,17 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 "error": "source capability unavailable",
             })
             return
+        except _quota_projection_incomplete_cls():
+            # #496 S5b, same reason as the `/api/milestones` branch: this route
+            # reaches `_build_codex_block_detail`, whose gate runs before its
+            # SQL, and the generic 400 below reported "capability unavailable"
+            # for a reconcilable state and named no remedy.
+            self._respond_json(503, {
+                "code": "quota_projection_incomplete",
+                "error": "quota view reconciling",
+                "action": "cctally cache-sync",
+            })
+            return
         except Exception as exc:  # noqa: BLE001 — detailed diagnostics stay server-only.
             self.log_error("/api/source/%s/%s failed: %r", source, resource, exc)
             self._respond_json(400, {
@@ -6646,6 +6695,11 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 # gets the same BEGIN/commit envelope as the stats conn.
                 stats_conn.execute("BEGIN")
                 cache_conn.execute("BEGIN")
+                # The gate acquires no lock, so it is safe INSIDE this
+                # transaction — and inside is the only placement that covers a
+                # connection opened before the publication (#496 S5b section 4.7).
+                from _cctally_quota import assert_projection_readable
+                assert_projection_readable(stats_conn)
                 roots = tuple(sorted({
                     str(r[0]) for r in stats_conn.execute(
                         "SELECT DISTINCT source_root_key FROM quota_window_blocks "
@@ -6688,6 +6742,16 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 })
                 return
             self._send_milestones_json(200, {**result, "source": "codex", "key": key})
+        except _quota_projection_incomplete_cls():
+            # #496 S5b. A refused projection read is a RETRY signal over a
+            # valid index, not a server fault, and the generic 500 below both
+            # mislabels it and drops the one remedy the user can act on: the
+            # message naming `cctally cache-sync` reached the server log only.
+            self._send_milestones_json(503, {
+                "error": "quota view reconciling",
+                "code": "quota_projection_incomplete",
+                "action": "cctally cache-sync",
+            })
         except Exception as exc:  # noqa: BLE001
             self.log_error("/api/milestones failed: %r", exc)
             self.send_error(500, "milestones detail failed")
@@ -7398,6 +7462,12 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
     # SIGUSR1 is unavailable (Windows).
     _register_faulthandler_sigusr1()
 
+    # #496 S5b §4.7: a long-lived server, and the surface on which a gated
+    # quota projection is most visible, so it may resume that recovery. One
+    # attempt per throttle interval — see
+    # `_cctally_journal._PROJECTION_RECONCILE_RETRY_SECONDS`.
+    _cctally_core.enable_quota_projection_reconciliation()
+
     # Spec §5.7: capture the un-mutated argv + PATH-resolved entrypoint
     # at boot so the in-place ``execvp`` after a successful update
     # re-enters the user-facing wrapper (npm Node shim → CCTALLY_PYTHON

package/bin/_cctally_dashboard_envelope.py

@@ -874,7 +874,9 @@ def _sync_failure_envelope(
     if not error:
         return None
 
-    def attributed(database: str, *, corruption: bool = False) -> bool:
+    def attributed(
+        database: str, *, corruption: bool = False, leg: str | None = None,
+    ) -> bool:
         for item in attributions or ():
             item_database = (
                 item.get("database") if isinstance(item, dict)
@@ -884,9 +886,13 @@ def _sync_failure_envelope(
                 item.get("corruption") if isinstance(item, dict)
                 else getattr(item, "corruption", False)
             )
+            item_leg = (
+                item.get("leg") if isinstance(item, dict)
+                else getattr(item, "leg", None)
+            )
             if item_database == database and (
                 not corruption or bool(item_corruption)
-            ):
+            ) and (leg is None or item_leg == leg):
                 return True
         return False
 
@@ -909,6 +915,26 @@ def _sync_failure_envelope(
             "action": None,
         }
 
+    # #496 S5b. A refused quota-projection read is the one attribution whose
+    # remedy the user can act on immediately, and without this branch it fell
+    # through to the terminal default below: `database="other"` matches nothing
+    # above it, so the chip read "⚠ server sync error" with no action, while
+    # the message naming `cctally cache-sync` sat in `last_sync_error`, which
+    # this module's own contract forbids putting in a visible text, title or
+    # aria surface. Keyed on the leg rather than on the raw text, because
+    # `database="other"` is deliberately generic and text classification is
+    # what the attribution vocabulary exists to replace.
+    if attributed("other", leg="quota-projection"):
+        return {
+            "kind": "quota_projection_incomplete",
+            "label": "quota view reconciling",
+            "detail": (
+                "The quota view is being rebuilt after an interrupted cache "
+                "recovery."
+            ),
+            "action": "cctally cache-sync",
+        }
+
     # conversations.db is intentionally outside core dashboard generations.
     # Typed transcript ownership therefore degrades through the generic server
     # contract: Doctor owns integrity diagnosis, and raw SQLite wording must

package/bin/_cctally_dashboard_share.py

@@ -321,7 +321,8 @@ def _share_apply_content_toggles(snap_built, options: dict):
     The render kernel consumes whatever the template builder emits, so
     chart/table on-off can't be expressed by the builder alone (every
     builder unconditionally emits both). Apply the toggle here, after
-    the builder, before `_scrub` and `render`. ShareSnapshot is frozen;
+    the builder, before `render()` / `compose()` prepare it.
+    ShareSnapshot is frozen;
     `dataclasses.replace` returns a new instance.
 
     Defaults preserve pre-toggle behavior: `show_chart` defaults to
@@ -379,8 +380,11 @@ def _share_top_projects_for_range(
     week, current 5h block).
 
     NULL `project_path` collapses to the `(unknown)` sentinel. Anon
-    happens later in `_scrub()`; builders always emit real names per
-    the kernel's privacy chokepoint contract.
+    happens later, in the preparation pass `render()` and `compose()` run
+    over the raw snapshot; builders always emit real names per the
+    kernel's privacy chokepoint contract. (It is NOT `_scrub()`: that
+    function is retained for backward compatibility and no production
+    path calls it.)
     """
     bucket: dict[str, float] = {}
     try:
@@ -1114,9 +1118,11 @@ def _build_projects_share_panel_data(options: dict,
       }
 
     The Privacy invariant per spec §7.4 lives at the share-render gate
-    (`_lib_share._scrub`), NOT here. This panel_data carries REAL
-    display_keys + bucket_paths; downstream `_scrub` rewrites them
-    when ``reveal_projects=false``.
+    (`_lib_share.render()` / `compose()`), NOT here. This panel_data
+    carries REAL display_keys + bucket_paths; the preparation pass those
+    entry points run over the raw snapshot rewrites them when
+    ``reveal_projects=false``. (It is NOT `_scrub()`: that function is
+    retained for backward compatibility and no production path calls it.)
     """
     env: dict = getattr(snap, "projects_envelope", None) or {} if snap else {}
     if not env:
@@ -1823,7 +1829,24 @@ class _SharePeriodError(ValueError):
 
 def _share_public_failure(handler, exc: Exception, *, phase: str,
                           capability: bool = False) -> None:
-    handler.log_error("/api/share/%s failed: %r", phase, exc)
+    # A privacy refusal is logged by CLASS ONLY (#503 S1 R10). Since the
+    # refusal message widened to name the matched value, a `%r` of the
+    # exception can put an absolute path, a UUID or an email address into the
+    # dashboard log — and a log is a plausible thing to paste into a bug
+    # report. The data is the user's own and the HTTP response below is
+    # generic either way, so nothing reaches a remote client; this is about
+    # what the log file accumulates. Every raise site in `_lib_share` sets
+    # `classes`, and `SharePrivacyViolation` defaults it to a non-empty
+    # sentinel, so this branch cannot fall through to the `%r` for a privacy
+    # refusal even if a future raise site forgets the keyword. Any OTHER
+    # exception is still logged in full, because its repr is the only
+    # diagnostic there is.
+    classes = getattr(exc, "classes", None)
+    if classes:
+        handler.log_error("/api/share/%s failed: %s: %s", phase,
+                          type(exc).__name__, ", ".join(classes))
+    else:
+        handler.log_error("/api/share/%s failed: %r", phase, exc)
     if capability:
         handler._respond_json(400, {
             "code": "source_capability_unavailable",
@@ -1877,9 +1900,10 @@ def _handle_share_render_post_impl(handler) -> None:
     template_id against the registry, dispatches to the per-panel
     `_build_<panel>_share_panel_data` helper to assemble the
     builder-shaped dict from the current dashboard snapshot, runs the
-    template's builder, applies `_scrub` when
-    ``options.reveal_projects`` is False, then renders via
-    `_lib_share.render`. Response: ``{body, content_type, snapshot}``
+    template's builder, then renders via `_lib_share.render`, which
+    prepares the RAW snapshot it is handed — anonymizing project labels
+    when ``options.reveal_projects`` is False. Response:
+    ``{body, content_type, snapshot}``
     where `snapshot` carries `kernel_version` + `data_digest` for the
     v2 composer's drift detection (spec §5.2).
 
@@ -2024,11 +2048,16 @@ def _handle_share_render_post_impl(handler) -> None:
     source_snaps = tuple(
         _share_apply_content_toggles(item, options) for item in source_snaps
     )
-    reveal = bool(options.get("reveal_projects", True))
-    if not reveal:
-        source_snaps = tuple(
-            ls._scrub(item, reveal_projects=False) for item in source_snaps
-        )
+    # FAIL CLOSED (#503 S1 F3). HTTP genuinely has an absent-field case, so
+    # a default belongs here; it must resolve to anonymize, matching
+    # /api/share/compose, which already defaulted closed. The kernel itself
+    # has no default at all, so a fourth site cannot get this wrong.
+    reveal = bool(options.get("reveal_projects", False))
+    # No pre-scrub: the kernel's `render()` / `compose()` own the privacy
+    # contract and require RAW snapshots (#503 S1). Pre-scrubbing here
+    # renumbers aliases on the legacy path, and in the `source=all` branch it
+    # merges two distinct projects that each mapped locally to `project-1`
+    # into a single alias.
     try:
         if source == "all":
             body = ls.compose(
@@ -2049,6 +2078,7 @@ def _handle_share_render_post_impl(handler) -> None:
                 format=fmt,
                 theme=options.get("theme", "light"),
                 branding=not options.get("no_branding", False),
+                reveal_projects=reveal,
             )
     except Exception as exc:
         _share_public_failure(handler, exc, phase="render kernel")
@@ -2093,9 +2123,31 @@ def _handle_share_render_post_impl(handler) -> None:
         if account_label is not None:
             account_meta["account_label"] = account_label
 
+    # #503 S1 B1 — does this export contain project names at all?
+    #
+    # The share modal's status line said "Export will show real project names"
+    # on every panel. Some renders produce artifacts that are byte-identical in
+    # both privacy modes apart from the `anonymized:` frontmatter line, so on
+    # those the line was making a false statement — and a warning users learn to
+    # disregard on Forecast is one they may disregard on Projects. The client
+    # renders a third, neutral state from this flag.
+    #
+    # Which renders those are is derived per render from the snapshot in hand,
+    # never counted or listed: it depends on the data the panel actually holds,
+    # and it varies within a single panel. Do not state a number here.
+    #
+    # ADDITIVE per `docs/cli-contract.md`: an optional key does not bump a
+    # schema version, and consumers must tolerate unknown keys. Derived from
+    # the same RAW snapshots the renderer was just handed, through the kernel's
+    # `_map_project_display` enumeration — never from a panel list, which would
+    # be a second source of truth and wrong at template granularity.
+    has_project_names = any(
+        ls.has_project_identities(item) for item in source_snaps)
+
     handler._respond_json(200, {
         "body": body,
         "content_type": content_type,
+        "has_project_names": has_project_names,
         "snapshot": {
             "kernel_version": ls.KERNEL_VERSION,
             "panel": panel,
@@ -2282,10 +2334,14 @@ def _handle_share_compose_post_impl(handler) -> None:
             _share_apply_content_toggles(item, composite_opts)
             for item in source_snaps
         )
-        if not reveal_projects:
-            source_snaps = tuple(
-                ls._scrub(item, reveal_projects=False) for item in source_snaps
-            )
+        # No pre-scrub (#503 S1): `compose()` prepares every section itself,
+        # under one merged alias namespace. Scrubbing per section here is what
+        # made `project-1` denote a different project in each section.
+        #
+        # The digest below is unaffected by the removal: `_share_digest_input`
+        # reads only `snapshot.period` off each snapshot, never a label, so it
+        # stays byte-identical and no basket section spuriously reads
+        # "Outdated".
 
         # Defensive: digest is non-blocking metadata — fall back to
         # "" on failure rather than 500-ing the whole compose

package/bin/_cctally_dashboard_sources.py

@@ -15,6 +15,7 @@ from zoneinfo import ZoneInfo
 
 from _cctally_core import get_week_start_name
 from _cctally_quota import (
+    assert_projection_readable,
     codex_five_hour_percent_at_crossing,
     codex_quota_breakdown,
     codex_physical_mutation_seq,
@@ -586,6 +587,9 @@ def _codex_weekly_periods(
     # so the sentinel needs no NULL branch here (unlike the cache tables).
     account_predicate = "" if account_key is None else "AND account_key = ? "
     account_params: tuple = () if account_key is None else (account_key,)
+    # BEFORE the `try`, per #496 S5b section 4.7: beneath that handler a denial
+    # would be rendered as empty data rather than as an error.
+    assert_projection_readable(stats_conn)
     try:
         rows = stats_conn.execute(
             "SELECT source_root_key, account_key, logical_limit_key, limit_name, "
@@ -931,6 +935,12 @@ def codex_projection_coherence(
     physical signature only after its stats transaction commits, and its cache
     sequence must still match before presentation can use it.
     """
+    # BEFORE the `try`, per #496 S5b section 4.7, and for the same reason every
+    # other gated site places it there: the handler below catches
+    # `ValueError`/`TypeError` as well as `sqlite3.Error`, so a refusal raised
+    # inside it would be rendered as `ProjectionCoherence(False,
+    # "projection_read_failed")` — a degraded-data verdict instead of a denial.
+    assert_projection_readable(context.stats_conn)
     try:
         active_roots = tuple(sorted(
             str(row[0]) for row in context.cache_conn.execute(
@@ -1516,6 +1526,7 @@ def _quota_wire(
     """
     if cycle is None or now_utc is None:
         return ()
+    assert_projection_readable(stats_conn)
     try:
         rows = stats_conn.execute(
             "SELECT source_root_key, logical_limit_key, observed_slot, window_minutes, "
@@ -3151,6 +3162,7 @@ def _codex_block_account_keys(
     if not root_keys:
         return set()
     placeholders = ",".join("?" for _ in root_keys)
+    assert_projection_readable(stats_conn)
     try:
         return {
             str(row[0] or _lib_accounts.UNATTRIBUTED)