Drift and recovery

This page explains how Pilotage prevents a validated program from silently running against a changed world.

Drift is a mismatch between the catalog snapshot a Client checked and the catalog visible at execution time.

For an inline program, validation returns catalog_version. The execute request sends that token back as expected_catalog_version. The server compares it with the current authorization-scoped token before revalidation or any side effect.

Harborview starts with:

cv_590fefad56a7a504

After light.floor2_west is removed, the catalog token becomes:

cv_d4e1f4237c537ac0

Executing with the stale token returns this captured outcome:

{
  "run_id": "run_0009",
  "outcome": {
    "ok": false,
    "status": "catalog_drift",
    "error": "the catalog changed since validation"
  }
}

No side effect occurs. Recovery is deliberate: retrieve the relevant catalog entries again, validate against the current snapshot, inspect the new plan and risk, then execute with the new token. If the program or input changes, use a fresh idempotency key.

promotion_drift is different. It means the load-bearing catalog fields recorded when a program was promoted no longer match. That reference is terminal: retrying it cannot succeed. The program must be promoted again to create a new immutable reference and baseline, or the Client must return to inline authoring.

Formal rules: Part II §6.5.2, Processing order, Part II §6.5.3, Drift protection, and Part II §7.5, Drift recovery.

Next: The catalog · Idempotency