SENTINEL SIGNAL

Sentinel Signal

v1.0.659 — Proof-strip server-side snapshot + Verify cross-brand breadcrumb

Source: docs/proof-strip-snapshot-and-verify-breadcrumb-v1.0.659.md

All documents Docs Home Home

Document Content

v1.0.659 — Proof-strip server-side snapshot + Verify cross-brand breadcrumb

Context

Two small, independent follow-ups the user found after using the rebranded sites:

  1. The corporate homepage's Verify proof strip fetched its two dynamic numbers (discovered candidates, endpoints observed) client-side with a 1.5s timeout, rendering a bare "—" on any failure or before JS ran — crawlers, social-preview scrapers, and non-JS clients saw no numbers at all, even though Verify already had the real data (~88.2K discovered, ~16.1K endpoints) behind a 5-minute server-side cache.
  2. Verify's own UI had no visual link back to the parent brand beyond a small footer line. The user wanted a one-line breadcrumb near the top of every Verify page, explicitly not a redesign of Verify's dense, intentionally-technical nav.

What shipped

Verify: cross-brand breadcrumb

render_brand_breadcrumb() / inject_brand_breadcrumb() (verify/src/mcp_verify/main.py, next to the existing render_site_footer()/inject_site_footer()) render "SENTINEL SIGNAL / VERIFY" — "SENTINEL SIGNAL" linking to https://sentinelsignal.io/, styled to match the footer's existing cross-brand-link conventions (inline styles, color:inherit, rel="noreferrer"). Injected from the same shared _html_response() closure that already auto-injects the footer on every real page response (confirmed via grep: 81 call sites through that closure vs. 3 legitimate exceptions — a 503 capacity-shed page, an innerHTML-injected fragment response, and an internal admin page — none of which should carry brand chrome anyway). Zero changes to render_site_nav(), MAIN_NAV_ITEMS, or any of its ~59 call sites, so Verify's own nav stays exactly as dense/technical as before.

Marketing: server-side-cached proof-strip snapshot

marketing/site/ is baked into the nginx image at build time with no writable path into the running container — a real architectural constraint the design had to work around. Added one bind-mounted host directory to the marketing service (deploy/ionos/docker-compose.yml and the root dev docker-compose.yml), and two tiny SSI-included fragments in marketing/site/index.html (<!--#include virtual="/_data/proof-strip-discovered.html" --> etc., replacing the old data-stat spans) — SSI re-reads these from disk on every request, so a refresh takes effect immediately with no container restart.

scripts/refresh_marketing_proof_strip_snapshot.py fetches Verify's existing /v1/coverage-summary, rounds each number the same way the old client-side JS did (88237 → "88K+"), and writes each fragment atomically (temp file + rename). On any fetch/format failure it changes nothing and exits non-zero — the previous snapshot keeps being served untouched, which is exactly "if Verify is unavailable, return the last cached value," free, because the file is simply never overwritten. A new systemd unit pair (sentinel-signal-proof-strip-snapshot.service/.timer, modeled directly on the existing sentinel-signal-verify-coherence pair) runs it every 4 hours; deploy.sh also runs it once synchronously on every deploy and installs/enables the timer, mirroring the coherence-check block exactly.

Removed the now-redundant client-side fetch/timeout/data-loaded logic from marketing/site/_js/site.js — the numbers are always present in the served HTML now, so there's nothing left for JS to populate.

A real bug found via local Docker testing

Building and running the actual marketing nginx image locally (same discipline as the earlier homepage/redirect work) caught a genuine bug the plan didn't anticipate: a missing SSI include target doesn't just silently omit or show a short error string — it embeds nginx's full default 404 HTML page verbatim into the served page. ssi_silent_errors on; does not cover this case (it only covers SSI processing errors, not a missing include target). This would have been visibly broken — a chunk of raw "404 Not Found" HTML sitting inside the proof strip — on a brand-new host before its first snapshot refresh, or if the bind-mounted directory were ever briefly empty.

Fixed two ways: (1) marketing/nginx.conf's /_data/ location now does try_files $uri @empty_snapshot_fragment; with @empty_snapshot_fragment { return 204; }, so a missing fragment renders as genuinely empty, not an embedded error page; (2) committed real seed files (marketing/site/_data/proof-strip-discovered.html = 88K+, proof-strip-endpoints.html = 16K+) baked into the image for the case where no bind mount is active at all (local docker run, or as a baseline before the first mount exists), and deploy.sh now seeds (never overwrites, cp -n) the host bind-mount directory with these same files before the marketing container (re)starts, so a brand-new host is never dependent on the timer's first tick to show real numbers. All three scenarios (no mount, empty mount, live-refreshed mount) were verified locally against the real built image before shipping.

Verification

  • python -m pytest tests/ -q — 330 passed (was 321 before this change).
  • PYTHONPATH=verify/src:verify/tests python -m pytest verify/tests -q — 824 passed (was 823).
  • Local Docker: built and ran the real marketing image three ways (no mount, empty bind mount, bind mount with real content) and confirmed the proof-strip renders correctly (seeded fallback, clean empty, and live values respectively) with no embedded error HTML in any case; confirmed all 5 pages still 200 and CSS/JS cache headers unaffected.
  • docker compose --env-file deploy/ionos/prod.env.example -f deploy/ionos/docker-compose.yml config — confirms the new bind mount resolves correctly on the marketing service.
  • bash -n deploy/ionos/deploy.sh — confirms the new deploy steps didn't break shell syntax.