pivot-ops/README.md

PivotOps

Decide whether a plan still holds when conditions change, and name the assumption that broke.

PivotOps is a pure function over a plan and its current readings. It has no clock and does no I/O, and it executes nothing. It tells you whether to proceed, pivot to a fallback, stop, or hold.

What it checks and why

Conditions changing is not the real failure. The failure is a plan that never wrote down what it assumed, so nobody can tell whether a change matters. PivotOps is built against three versions of that.

1. A plan whose assumptions are implicit cannot be invalidated. Say a rollout assumes a host has disk headroom, a registry is reachable and a maintenance window is open. If none of that is recorded, a full disk only shows up as the failure at the end. A plan with no recorded assumptions returns hold, never proceed.
2. A stale reading is worse than no reading. Replanning against a condition nobody re-measured gives a confident decision from an old fact. An assumption with observed: null is NOT ASSESSED and blocks. "We did not look" is not "it is fine".
3. Degradation without a floor is optimism. "Reduce concurrency and continue" is a plan. "Continue at reduced capacity" with no point at which capacity becomes unacceptable is a way of never stopping. A broken assumption whose fallback has no floor makes the decision stop, not pivot.

Four decisions, not two

Decision	When
proceed	every assumption was re-checked and holds
pivot	something broke, and each broken assumption has a fallback with a floor
stop	something broke with no fallback, or with a fallback that has no floor
hold	nothing broke, but at least one condition was never re-measured

hold gives "we do not know" its own outcome, separate from "carry on" and "abandon". Folding it into either one leads to the two mistakes this library exists to prevent: proceeding on unread conditions, or killing a viable rollout because one probe was missing. A broken assumption outranks an unread one, so stop wins over hold.

Non-numeric values are never ordered. An at-least comparison of "closing" against "open" reports NOT ASSESSED instead of comparing the strings, which would pass or fail on alphabetical order. equals works on any value.

Usage

import { replan, formatReplan, type Plan } from '@extant2000/pivot-ops'

const plan: Plan = {
  name: 'nightly rollout',
  assumptions: [
    {
      id: 'disk-headroom',
      description: 'the host has room for the new image',
      condition: 'disk free bytes',
      comparison: 'at-least',
      required: 5e9,
      observed: 2e9,
      where: 'df -P /var/lib/docker',
      fallback: { description: 'reduce concurrency to 1', floor: 'stop below 500 MB free' },
    },
    {
      id: 'window',
      description: 'the maintenance window is open',
      condition: 'window state',
      comparison: 'equals',
      required: 'open',
      observed: 'open',
      where: 'change calendar',
    },
  ],
}

const { decision, reason, broken, unverified } = replan(plan)
console.log(decision)
console.log(reason)

// The full report, for a terminal or CI log
console.log(formatReplan(plan))

toReport(plan) returns the same result as a CapabilityReport from @extant2000/evidence-record, where every finding cites the reading it was based on.

Sample output

Produced by running the example above and printing decision and reason:

pivot
1 assumption(s) broken, each with a fallback and a floor: disk-headroom → reduce concurrency to 1.

Install

The package is published to the GitLab package registry, so point the @extant2000 scope there first:

npm config set @extant2000:registry https://gitlab.com/api/v4/packages/npm/
npm install @extant2000/pivot-ops

License

MIT. Copyright (c) 2026 Extant 2000 LLC. See LICENSE.