Second Brain

bible-v1918-r41-r44-retrofit-pattern

3 min read

bible-v19.1.8-r41-r44-retrofit-pattern

Bible v19.1.8 R41-R44 retrofit pattern (proven on snowflake-mcp v22.0.4)

When a pair has already shipped at Bible v19.1.7 SIGNED but Bible bumps to v19.1.8 (R41-R44), the retrofit is straightforward and additive — no breaking changes for downstream consumers. snowflake-mcp v22.0.3 → v22.0.4 cycle (2026-05-02) is the reference implementation; ~2-hour cycle including build/deploy/PR/merge.

The 4 retrofits in priority order (per Bible PR #21 guidance)

R41 — Probe-Script Transient-Network Retry Contract

Where: scripts/tool_health_census.py. What: add TRANSIENT_EXCEPTIONS tuple (httpx.RemoteProtocolError, ReadError, WriteError, ConnectError, PoolTimeout), wrap client.post() call in retry loop with exponential backoff (0.25s → 5s cap), expose a module-level TRANSIENT_RETRY_COUNT counter in run summary. Cost: ~10 LOC. Verification: census output reports retry rate (expected 1-3%); 0 retries with BROKEN>5 fires R41 false-negative warning.

R43 — Insights-Shape Type Contract

Where: every tool that returns an envelope. What: insights field MUST be None | str | list[str], NEVER dict. Audit: grep -rnE "['\"]insights['\"]~~:space:~~ <!-- broken wikilink, target missing -->*:~~:space:~~ <!-- broken wikilink, target missing -->*\{|insights~~:space:~~ <!-- broken wikilink, target missing -->*=~~:space:~~ <!-- broken wikilink, target missing -->*\{" src/. snowflake-mcp v22.0.3 sweep returned 0 violations — pre-existing R43 compliance was a happy accident.

R42 — Centralized FEATURE_NOT_ENABLED Helper Pattern

Where: new file src/<pair>/core/feature_error_helper.py. What: FeatureErrorHelper class with FEATURE_REQUIREMENTS dict (one entry per license-gated capability) + not_enabled_envelope() classmethod. Each entry has feature_name, required_license, required_permissions, setup_path, alternatives, documentation_url. The classmethod produces canonical envelope guaranteed to satisfy R42 invariants by construction (status=feature_not_enabled, data.feature.name: str, data.how_to_enable.setup_path: str, insights: list[str] of length ≥3). Refactor every per-tool inline FEATURE_NOT_ENABLED wrap to one-line FeatureErrorHelper.not_enabled_envelope(feature_key=..., original_error=..., org_type=...). Snowflake registered 12 keys: Cortex, SemanticViewsV2, CortexAgentsV2, CortexSearch, CortexFineTuning, SnowparkContainerServices, HybridTables, IcebergV3, StreamlitInSnowflake, Notebooks, DocumentAI, MigrationHandlerNotWired.

R44 — R33 11-Surface Cascade Expansion

Surface 10: every __init__.py carrying __version__ = "..." MUST match server version. Surface 11: prometheus <pair>_mcp_info gauge MUST emit framework="Bible-vX.Y.Z" label.

Strategic call for surface 11: if your pair already emits a different label scheme (e.g., snowflake-mcp v22.0.3 emitted framework="fastmcp-3.0" + bible="v19.1.7" — two labels carrying separate info), do NOT rename in-place. Instead adopt ADDITIVELY:

  • Rename old framework=<runtime> → runtime=<runtime> (frees the framework= label)
  • Put Bible-prefixed version in framework="Bible-vX.Y.Z" (R44 spec compliant)
  • Keep legacy bible="vX.Y.Z" label for backward compat with any consumer of v22.0.3 scheme
  • Net: 5 labels instead of 4, all info accessible, cascade-check.sh passes, zero consumer breakage

Adoption priority order (Bible PR #21)

  1. R41 (transport retry) — eliminates entire false-positive class, near-zero risk
  2. R43 (insights shape) — single-line audit per tool, fast
  3. R42 (FeatureErrorHelper) — refactor scope, requires per-feature license metadata research
  4. R44 (cascade surfaces) — alongside R33 enforcement, additive label adoption recommended

Cascade

  • Server version bump (e.g., v22.0.3 → v22.0.4) — 7 surfaces × 1 scale per R13
  • Framework version bump (Bible v19.1.7 → v19.1.8) — 7 surfaces × 1 scale per R13
  • README sync in same PR (per workspace memory feedback_repo_cleanup_includes_readme.md)
  • Skill ~/.claude/skills/<pair>/SKILL.md cascaded to new versions
  • pilot-learnings.md appended with retrofit closure

Adoption-lag postmortem

Bible PR #21 explicitly mandated adoption “before next major-version upgrade (Snowflake)” — but Snowflake v22.0.3 had already shipped at Bible v19.1.7 SIGNED hours before PR #21 merged. Net adoption lag: ~7 days (in retrofit territory). Future pairs facing the same: just retrofit additively, no rollback needed. Bible v19.1.8 was designed for additive adoption.

Reference impl

  • snowflake-mcp v22.0.4 commit 5b93acb (PR #17 merged 2026-05-02)
  • salesforce-mcp v7.0.0 (Bible reference impl, commits e35c1c3 + 303bb5c)

Graph View

Backlinks