Rollout and decision watchdog CLI
Evaluate standing-decision drift, shadow rule promotion readiness, and routed canary health across an organisation's active workloads or offline against a checked-in Stackfile and runtime ledger.
DATABASE_MIGRATE_URL=... npm run aperture:watchdog -- --org convexitynpm run aperture:watchdog -- --stackfile vitna.stack.json --policy policy.json --ledger ./ledger.jsonl --fail-on-rollbackNothing is written to the database or disk. Every finding prints the exact operator command (aperture:decide, aperture:rule:promote, aperture:rule:add, or aperture:rule:remove) required to advance or roll back a rollout. See Rollout and decision watchdog for how each verdict is derived.
Modes and flags
- Register mode (
--org <slug>or--workload <org/slug>): reads active workloads, standing decisions (recovering decision-time unit costs from pinnedpricePeriodIdsandenteredPriceIds), lane rules, fallback chains, pusheddeployment_observationwindows,evidencerows, live Witness and entered rates, provider compliance terms, and three-provenance SKU capabilities. May optionally pair a local runtime.jsonlfile via--ledger <path>. - Offline Stackfile mode (
--stackfile <vitna.stack.json>): runs with zero database connection for CI pipelines and GitOps checks, pairing the Stackfile with an optional signed--policy <policy.json>,--ledger <file.jsonl>,--evidence <evals.json>, and--terms <terms.json>.
| Flag | Meaning |
|---|---|
--org <slug> | Evaluate all active workloads in <slug> |
--workload <org/slug> | Narrow evaluation to one active workload |
--window YYYY-MM-DD..YYYY-MM-DD | Restrict observation and ledger rows to one closed UTC date range |
--ledger <file.jsonl> | Summarize per-request vitna-runtime ledger rows (shadowRule, serve, cohort, latencyMs) |
--stackfile <file> | Run offline against a vitna.stackfile.v1 file with no database |
--policy <policy.json> | Pair offline Stackfile evaluation with a signed policy.json |
--evidence <evals.json> | Supply offline evaluation rows in --stackfile mode |
--min-shadow-matches <n> | Minimum shadow matches before promote_ready (default 50) |
--min-canary-units <n> | Minimum served canary units before expand_or_adopt_ready (default 100) |
--max-unserved-pct <n> | Maximum unserved attempt rate percentage (default 5) |
--max-fallback-pct <n> | Maximum fallback share of served traffic percentage (default 10) |
--max-price-drift-pct <n> | Maximum unit-cost increase vs standing decision percentage (default 10) |
--json | Emit structured JSON report |
--fail-on-rollback | Exit 4 if any workload verdict is rollback_recommended or decision_drifted |
Exit codes
| Code | Meaning |
|---|---|
0 | Evaluation succeeded (and no rollback or decision drift occurred when --fail-on-rollback is set) |
1 | Register mode requested with neither DATABASE_MIGRATE_URL nor DATABASE_URL set |
2 | Invalid flags, malformed date window, unreadable input file, or unknown organisation/workload |
4 | --fail-on-rollback was passed and at least one workload returned rollback_recommended or decision_drifted |
