retrofit drift

Reconcile an oplog with an out-of-band .sql capture.

drift parses <source>, diffs it against the current cut of <schema-name>'s
unsealed tail, and either appends the SMO sequence that brings the oplog
to the target (default) or reports it (--dry-run).

Reference data: the tables declared at the new head are converged in the
same run, with no flag. Each one whose rows differ from its chain is
captured into the data corpus (one file per changed table,
disposition=replace body=data); see --help-all.

Usage:
  retrofit drift <source> [--schema <name>] [flags]

Flags:
      --allow-capability-gaps          accept skips that drop content retrofit has no operator for (exit 0 instead of exit 2; the drift-run-summary record is byte-identical either way)
      --data-root data_root            root that overrides the schema's data_root
      --dry-run                        parse, diff, and emit the report; never open the editor; never write the oplog
      --extra-seed-path seed_paths     root that appends to the declared seed_paths
  -h, --help                           help for drift
      --help-all                       show extended help (vocabulary, semantics, caveats)
      --ignore-drops string[="*"]      suppress Drop op authoring; bare = all kinds, or CSV of: table, column, index, view, materialized-view, constraint, foreign-key, primary-key, not-null, identity, schema (suppressed drops still surface as deferred-drop events)
  -i, --interactive                    open the editor even when there are no questions
      --on-question string             question policy for unattended runs: error|editor|skip (default: editor when $EDITOR or $VISUAL is set, else refuse)
      --ref <table>                    declare <table> reference data (repeatable): a CreateTable this run mints is written reference_data=true; a table live at the run's starting cut gets SetReferenceData(value=true) appended after the run's DDL ops
      --schema <name>                  registered schema <name> (resolves via the chain when omitted)
      --seal --seal=<text>             append a Seal op covering drift's new tail (bare flag auto-derives reason from source basename; --seal=<text> overrides); refused as `op seal` refuses when the range holds an unwitnessed reference record
      --seed-path seed_paths           root that replaces the declared seed_paths
      --show string                    report-side filter on the live event stream: both|additions|removals (presentation-only; writes proceed for both directions) (default "both")
      --skip-manifest <path>           write the reference capture's skip manifest to <path> as JSONL
      --table <pattern>                repeatable source <pattern> narrowing the reference capture (bare relname or glob)

Global Flags:
      --as string        output mode: text | json (default "text")
  -C, --chdir string     treat <dir> as the working directory for the entire run
      --config string    retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
  -f, --file string      oplog file path; selects a registered [[schema]] path (overrides discovery)
      --no-consolidate   render every advisory occurrence instead of collapsing repeats
  -q, --quiet count      suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
  -v, --verbose          reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-drift/

Extended help:

Ambiguity handling: drop+add column pairs and type changes don't
have a unique reconciling sequence (a drop followed by an add could
also be a rename plus a type change, or a move-column across tables).
drift auto-elevates these to the editor (human or LLM via $EDITOR)
for an interactive disambiguation pass before authoring the SMO
sequence.

Use `-i` to force the editor open even when the diff is
unambiguous, `--dry-run` to print the planned SMO sequence
without writing, and `--seal` to append a Seal op after a
successful run.

`--on-question=<policy>` controls how the run handles
ambiguity that drift can't auto-resolve:
  error:  refuse with `needs-interactive-resolution` (overrides
          the default auto-elevation when $EDITOR/$VISUAL is set).
  editor: open the editor; equivalent to `-i` once a question fires.
  skip:   emit each question as a `skipped` event with kind
          `unresolved-question:<class>` and proceed with the ops
          drift could mint. Useful for unattended regression harnesses
          that batch many drift steps and want to surface ambiguity in
          the skip manifest rather than stop on the first one.

Without the flag, a question opens the editor when $EDITOR or $VISUAL
is set, and the run refuses with `needs-interactive-resolution` otherwise.

`--show=<both|additions|removals>` is a report-side filter on
the live event stream. `additions` hides per-op events for
Drop* operators; `removals` hides per-op events for Add*
and Create* operators. The `drift plan:` header above the
stream and the summary below it are NOT filtered; they
always show the full diff shape and what was written. `--show` is presentation-only: writes proceed for both
directions regardless of value.

Reference data:

  drift converges the reference tables declared at its new head in the same
  run, with no flag: each declared table whose INSERT rows differ from its
  chain is captured as a full observed row set (one file per table,
  `disposition=replace body=data`); an unchanged one reads
  `already-captured`. Declare a
  table with `retrofit schema ref-tables add <table>`, or with `--ref <table>`
  for a table this run creates. Seed rows are not schema and stay off drift:
  capture them with `retrofit data capture --label <label> <source>`.

  A declared table drift cannot compare is reported with its cause: a COPY
  band (re-dump with `pg_dump --inserts`), a chain whose table is no
  longer declared (`data retire` it, or declare it again), and a declared
  table the source states no rows for (counted as not observed; absence is
  never drift). A captured table that lost a key since its chain is minted
  with a warning naming the key. `--table <pattern>` narrows the source,
  and `--skip-manifest <path>` writes the skipped statements as JSONL.
  A dry run emits one rehearsal record per table and writes neither the
  oplog nor the data corpus.