Skip to main content

Troubleshooting

Use this page as the short-entry fault guide. The deeper operator flows remain in the existing runbooks and testing standards.

Reader Outcome​

This page should help an operator quickly decide whether the problem is:

  • Beam source/docs/contract drift
  • upstream Fabric truth-consumption drift
  • promotion/stage-3 evidence drift
  • host attachment/access drift

If the first bounded Beam check is green but the runtime owner lane is still broken, classify it as an external owner follow-up instead of recreating the runtime truth locally in Beam.

Primary References​

  • Operations
  • Runbook
  • Deployment Verify Ops (docs/DEPLOYMENT_VERIFY_OPS.md)
  • Upgrade Operator Guide (docs/UPGRADE_OPERATOR_GUIDE.md)

Docs / Contract Drift​

Symptoms:

  • docs inventory verification fails
  • canonical docs and manifest disagree
  • local-only workspace docs appear in canonical paths

Run this check:

python3 maintenance/verify-docs-inventory-adoption.py
python3 maintenance/verify-maintenance-contracts.py

Expected posture:

  • docs/docs.manifest.yaml stays conservative
  • local-only docs such as docs/PUBLIC_SURFACES.md and docs/RUNTIME_FLOWS.md are not promoted to canonical truth
  • Beam docs do not imply runtime or deployment ownership outside Beam's own verifier/governance scope

Fabric Truth Consumption Drift​

Symptoms:

  • combination safety matrix fails
  • docs-standard or voice-events contract family checks fail

Run this check:

python3 maintenance/verify-fabric-combination-safety.py
python3 maintenance/verify-voice-governance.py

For live readback:

python3 maintenance/verify-fabric-combination-safety.py --live-url `api/v`1/combinations/profiles
python3 maintenance/verify-voice-governance.py --live-via-ssh <internal-runtime-redacted><internal-runtime-redacted>

Promotion / Stage-3 Feedback Problems​

Symptoms:

  • stage-3 feedback cannot publish
  • lock evidence is missing
  • live feedback readback mismatches expected payload

Run this check:

python3 maintenance/verify-promotion-bridge.py
python3 maintenance/verify-published-feedback-check.py
python3 maintenance/verify-stage3-metrics.py

Host Attachment / Host Access Problems​

Symptoms:

  • Beam cannot verify host-bound contracts
  • SSH batch-mode contract fails
  • live stack attachment evidence is stale

Run this check:

bash ops/host/verify-ssh-batchmode-contract.sh
bash ops/host/verify-live-stack-attachment.sh

Public Source-Truth Drift​

Run this check:

python3 maintenance/verify-beam-terminology.py
python3 maintenance/verify-docs-inventory-adoption.py

Use it when the public-facing source pages start to blur the difference between Beam certification truth and foreign runtime truth.

License: AGPLv3. See ../LICENSE (LICENSE).

Learn more at helpifyr.com.