Aller au contenu principal

Upgrade and Migrate

Use this page when you need a controlled upgrade path with explicit sequencing, rollback posture, and post-upgrade verification.

When to use this page​

  • You are moving a running Helpifyr environment to a new release or release train.
  • You need a migration path that stays aligned with repo truth and runtime truth.
  • You need to decide whether an upgrade should proceed, pause, or roll back.

Prerequisites​

  • You know the current version or release train and the intended target version.
  • You have access to release notes, compatibility notes, and runtime verification surfaces.
  • You can run the repo-owned materialization verifier before and after the change.
  • You know which owner repo controls the deployment path for the affected runtime.

Upgrade intent​

This page does not replace owner-specific release notes. It gives you the stack-level sequence for deciding whether an upgrade is safe to begin and how to prove it actually finished correctly.

Architecture / Flow​

Step-by-step procedure​

1. Pin the exact source and target state​

Before any upgrade step:

  • record the current version or release train
  • record the target version or release train
  • identify whether the change is additive, compatibility-sensitive, or migration-heavy

Without those facts, you cannot tell whether a red signal is expected drift or an actual regression.

2. Read the compatibility and release posture​

Use the docs and reference surfaces before touching the runtime:

These pages should tell you:

  • whether the target version is expected to be admitted
  • whether a migration guide is required
  • whether the upgrade changes docs, contracts, or readiness posture

3. Capture the pre-upgrade baseline​

Record the same health surfaces you will use after the upgrade:

GET /api/v1/platform/services
GET /api/v1/observability/readiness
GET /api/v1/security/readiness

This matters because a post-upgrade green signal is only meaningful when compared against the pre-upgrade state.

4. Verify repo truth before changing runtime truth​

Run the repo-owned verifier:

python ./scripts/verify_runtime_materialization.py --check

If this already shows drift before the upgrade starts, stop and resolve that first. Upgrading on top of unresolved drift makes rollback and blame assignment harder.

5. Apply the owner-approved upgrade sequence​

Use the bounded owner lane for any actual mutation. The public-safe posture here is:

bash ./scripts/redeploy-host-stack.sh

Only run a deploy or redeploy action after:

  • version intent is explicit
  • compatibility posture is reviewed
  • rollback posture is agreed
  • the owning runtime lane says this is the correct next step

6. Re-run the same verification after the change​

After the upgrade, repeat:

GET /api/v1/platform/services
GET /api/v1/observability/readiness
GET /api/v1/security/readiness

and then:

python ./scripts/verify_runtime_materialization.py --check

If the stack has changed in a runtime-sensitive way, also use the stronger bounded guardrail path:

bash ./scripts/verify-runtime-guardrails.sh

Example upgrade check sequence​

curl -s <fabric-base-url>/api/v1/platform/services
curl -s <fabric-base-url>/api/v1/observability/readiness
curl -s <fabric-base-url>/api/v1/security/readiness
python ./scripts/verify_runtime_materialization.py --check

# owner-approved upgrade step
bash ./scripts/redeploy-host-stack.sh

curl -s <fabric-base-url>/api/v1/platform/services
curl -s <fabric-base-url>/api/v1/observability/readiness
curl -s <fabric-base-url>/api/v1/security/readiness
python ./scripts/verify_runtime_materialization.py --check
bash ./scripts/verify-runtime-guardrails.sh

Verification​

Treat the upgrade as complete only when:

  1. the source and target versions are explicitly recorded
  2. release and compatibility posture were reviewed before mutation
  3. the pre-upgrade health baseline was captured
  4. python ./scripts/verify_runtime_materialization.py --check is acceptable before and after the change
  5. post-upgrade readiness does not contradict the target release posture
  6. no owner-specific rollback trigger remains unresolved

Common failure modes​

Upgrade was applied without a clean baseline​

Risk:

  • you cannot tell whether the regression is new or pre-existing.

Recovery:

  • recapture baseline on the current state
  • compare against release-note expectations

Compatibility says one thing, runtime says another​

Risk:

  • you may have upgraded into a partially admitted state.

Recovery:

Readiness turns red after a migration step​

Risk:

  • continuing can widen the failure boundary.

Recovery:

  • stop the sequence
  • use Upgrade safely
  • escalate to the owning repo path for rollback or bounded recovery

Owner Handoff​

  • upgrade sequencing truth owner: JaddaHelpifyr/helpifyr-fabric
  • deployment support owner: JaddaHelpifyr/jhf-deployment
  • runtime environment support owner: JaddaHelpifyr/jhf-openclaw-env

Source Truth​

Next paths​