CLI output contract

This document is the canonical reference for what the retrofit CLI prints, where, and in what shape. It is the contract you script against.

The persistent root flag --as=text|json selects the output mode. Stdout carries the disposition (a terminal envelope under JSON mode); stderr carries advisories. Errors normally land on stdout under JSON so a single jq filter handles both ok and error paths. Channel exceptions lists the records that depart from this rule.

The contract

The flag: --as=text|json

--as is a persistent root flag. It defaults to text and applies to every subcommand. An unknown value refuses as kind-mismatch (exit 2).

A handful of verbs accept legacy values for one-release backward compatibility:

• op show --as=add|revise|json: deprecated; use --framing=log|add|revise plus the persistent --as=json for output mode. The legacy spelling emits a deprecated-flag warning. (Default framing is log, the on-disk record grammar; add and revise are the runnable-line framings.)
• op revise --as=revise|json: removed; the persistent flag supersedes it.
• reconcile -y / --yes / -i / --interactive / --force: removed; the mode flag (--clean / --accept-dirty) is the consent signal. These are registered as hidden aliases and exit 3 (flag-conflict) with a redirect message.
• reconcile --output is not registered. reconcile exits 3 (flag-conflict) on any flag-parse error, an unregistered flag included; other verbs exit 2 for an unregistered flag.

The verbosity axis: --quiet / --verbose

-q/--quiet and -v/--verbose are persistent root flags governing the human text advisory tier on stderr. They are orthogonal to --as: --as picks the wire format, verbosity picks how much of the advisory tier that format shows. -q+-v resolves quiet-wins with no error. --verbose means the verbose level on every command, op show included; no verb repurposes -v (op show’s former local --verbose is spelled --annotate).

--quiet is a count: stack it to go quieter. --verbose stays a plain flag: the ladder runs downward only, and there is no level above verbose.

The ladder

Each position is defined by what it shows, not by how it is spelled internally:

--quiet also takes an explicit count (--quiet=2 is -qq), and --quiet=0 is a legal way to say “not quiet”. The retired --quiet=true / --quiet=false spellings are refused with a message naming their replacement.

Never suppressible at any level (including -qq): all error: output, every refusal, the JSON Success.Schema field, and the result-carrying wire lines op seal sealed N ops as <OpID> and snapshot engine_version:. No quiet level silences an error, a refusal, or a command’s primary result, and none of them changes the exit status.

One advisory outranks the ladder: internal-invalid-advisory, which retrofit emits when the advisory machinery itself fails. It renders at every level, because an advisory whose whole purpose is to report that the tier is broken cannot be suppressible by that tier.

--as=json × verbosity is orthogonal: in JSON mode the ladder does not apply; structured advisories ({"level":"note",...}) and the Success.Schema field ride the envelope regardless of -q/-v/-qq, so --as=json -qq drops nothing structured.

No --no-color flag: the output carries no color.

Repetition: --no-consolidate

When one advisory repeats within a run, the human text surface renders the repeats as one line carrying the first occurrence’s content, the number of occurrences, and the way back. Two or more occurrences collapse; a single occurrence renders unchanged.

The disclosure is part of the collapsed line, never a separate note: there is no path that reduces the output without saying so. The count includes the occurrence shown, so a group of twelve reads 12 occurrences rather than and 11 others, and a group whose occurrences do not all read alike says that too.

--no-consolidate is a persistent root flag that restores the full list. It affects only verbs that raise a repeating advisory, so it parses and does nothing on most of the tree.

Consolidation is a display transform only:

• it never changes the exit status;
• it is off entirely on a failing run, where every occurrence prints;
• --as=json carries every occurrence uncollapsed at all times;
• it composes with the ladder without special cases: --no-consolidate picks what the tier would show, the ladder picks whether it shows anything, so -qq --no-consolidate prints nothing.

Attestation: answering an advisory instead of silencing it

No flag names an advisory code to turn it off. Where retrofit offers a way out of a recurring advisory, the flag names the fact that answers it, and the advisory then has nothing left to report.

migrate --allow-external-atomicity is such a flag. It states that the apply context owns transaction atomicity, which answers the no-wrapper advisory wherever that advisory arose from a delegated envelope. On an attested run the advisory is not raised at all (in text or JSON), while the emitted SQL and the exit status are byte-identical to the unattested run.

An attested run records the attestation: the terminal envelope carries data.external_atomicity_attested. Attesting one cause never silences another: a run whose wrapper is also suppressed by --down --into-schema still raises the advisory, and a note names the --into-schema cause that survived.

When the fact never arose, the run prints a code-less note on stderr, note: --allow-external-atomicity had no effect: this run's transaction wrapper was not suppressed by a delegated apply context, so the fact it attests never arose. The note is not a refusal, and the exit is unchanged.

Resolved-schema surface

Every schema-context verb (op*, snapshot, migrate, reconcile, drift, import, schema move, schema engine, schema scope add, schema set-default) names its resolved schema in output:

• Text mode: the registered schema-context advisory renders as a note: schema-context: <name> line on stderr before the verb’s main stdout output (it rides the threaded advisory carrier; it is a courtesy-band note, -q-suppressible). Suppressed when -f <path> was used (path-as-identity bypasses the resolver) and when no schema-naming leg fired.
• JSON mode: a "schema":"<name>" field on the terminal {"type":"ok",...} envelope. The preamble is not repeated per intermediate record.

RETROFIT_REQUIRE_EXPLICIT_SCHEMA=1 makes the resolver refuse with explicit-schema-required when neither --schema nor -f fired. It is a CI hardening knob.

Stdout

text mode (default)

Verb-defined human output:

Stream line grammar

The verbs that emit a per-event stream (op add, op add --dry-run, import, schema create, drift) share one line shape:

<prefix> <opid>  <Operator>  <bound-target>  [(<annotation>)]

Column invariant: awk '{print $1}' returns the prefix and awk '{print $2}' returns the opid for every stream line. The opid column is never empty: placeholders fill the slot for pre-mint and no-op rows.

~ is overloaded across two distinct shapes that share the grammar but populate different slots:

• op_add same-as-tail: ~ <opid> <Operator> <target> with a real opid (the existing tail’s short-id) and a catalog operator.
• drift skipped: ~ (skipped) <SkipKind> <target> with the literal (skipped) placeholder in the opid slot and a single-token skip-kind in the operator slot: a dashed slug (add-pk-unresolved-column, comment-column-unresolved, …) or a CamelCase pg_query AST node name (AlterTableStmt, IndexStmt, …). Always whitespace-free.

Tools that switch on the operator column should also key off the opid value ((skipped) vs. a 12-char short-id) to disambiguate the two ~ shapes.

json mode

Stdout is NDJSON, and cardinality decides the envelope. The common case is a stream of one-JSON-object-per-line records, all keyed by a single type discriminator: each line is either an intermediate {"type":"<name>",...} record or the terminal {"type":"ok",...} / {"type":"failed",...} / {"type":"unverifiable",...} record. The terminal record is always emitted on success or graceful failure; its absence means the process was killed.

[ {"type": "<intermediate-name>", ...} ]*  # zero or more intermediate records
{"type": "ok", ...}                        # OR
{"type": "failed", "code": "...", ...}     # OR
{"type": "unverifiable", "code": "...", "entries": [...], ...}

The shape lets a single jq filter handle every path:

retrofit X --as=json | jq 'select(.type == "ok" or .type == "failed" or .type == "unverifiable") | .type'

unverifiable is the third terminal type. The oplog is readable but carries a rule this build cannot evaluate; the run exits 2. A broken sealed prefix is sealed-oplog-unparsable instead, exit 1.

A standing rule violation dominates: if any violation stands the record is failed, whatever else the run observed. unverifiable is reached only when nothing stands and something could not be asked.

Its entries array lists each unevaluable rule as {"rule": "<code>", "opid": "<opid>", "reason": "<why>"}, so “this oplog has an unanswerable question” is actionable: it names which question and where.

A consumer matching only ok must handle both failed and unverifiable.

violations is an extension array on a failed envelope, beside the unverifiable/entries precedent above. It appears on an accumulating refusal: one that evaluates every argument and reports each failure rather than stopping at the first:

{"type": "failed", "code": "<covering-code>",
 "violations": [{"argument": "<arg>", "code": "<per-failure-code>", "detail": "<why>"?}, …]}

Where entries is homogeneous under one code, violations is heterogeneous: each entry carries its OWN code beside the argument it refused, and the envelope’s code is the covering code naming the envelope’s KIND rather than the first failure’s, so a consumer branches per entry rather than reading the first failure as the whole answer. Entries are ordered as the arguments were given. detail is omitempty.

retrofit schema ref-tables’s ref-tables-rejected is the shipped covering code; its entries carry ref-table-not-live, ref-table-pattern-qualified or reference-data-partition. retrofit data capture --from-label’s from-label-refused is the second: a run refusing more than one selected table carries one entry per refusal, each with its own from-label-* code (from-label-undeclared, from-label-not-foldable, from-label-empty, from-label-no-chain-for-table); a run refusing once keeps that refusal’s own code on the envelope. The field is omitempty, so an envelope with no entries carries no violations key.

Single-document exception. A verb whose entire success stdout is a SINGLE JSON value emits that value bare: no leading type key, no terminal ok line. The type discriminator earns its place only when two or more values share the stream and a consumer must tell them apart; on a one-value document it discriminates nothing, so it is omitted and json.load(stdout) / jq '.' sees the payload directly. The verbs are op info --dump --as=json (the {"operators":[...]} catalog document), op info <Operator> --as=json (the single-operator descriptor), and identify --as=json on an exact match (the outcome/opid/seal document). The graceful-failure path is unchanged: a failure still emits the terminal {"type":"failed",...} envelope. So a consumer that may hit either path decodes the first JSON value and inspects its type: absent or non-failed means the success document, failed means the error.

Per-verb shapes:

On a multi-record stdout the discriminator field is type, identical across intermediate and terminal records. Other top-level fields are verb-specific and merged into the envelope when the payload is an object. Terminal values are ok, failed and unverifiable; intermediate values are verb-defined past-participle or noun forms (appended, preview, applied, skipped, report, diff, item, …). All three terminal values are reserved and must not appear as intermediate type values. The single-document verbs above (op info and identify) are the exception: their success output is a bare value with no type key (see the single-document exception).

The Detail field (detail: on text mode, "detail":"..." on JSON envelopes) carries the factual narrative when the primary message is too tight to fit it.

op add records

{"type":"appended","operator":"...","opid":"...","prev":"...","outcome":"minted|noted","target":"...","minted":{...}?,"tail_after":"...","values":{...},"note":"..."?,"notes":[{"code":"<advisory-code>","message":"..."}]?,"warnings":[...]?}
{"type":"ok","notes":[{"code":"<advisory-code>","message":"..."}]?,"note":"..."?}

• notes[] is the structured advisory list: every entry carries a stable code. Advisory note codes inventories the codes, and the inventory is non-exhaustive by design.
• notes[] rides both the appended record for the authored op and the terminal envelope, carrying the identical slice; read one and ignore the other rather than concatenating them. warnings[] is duplicated across the same two records the same way. Every appended payload initializes warnings to [], so an empty array is not evidence the op was checked and cleared.
• One authored op yields exactly one appended record, so its tail_after IS the true persisted tail. A rejoinable ExtractTable is one op too (see the text-mode op add --dry-run row).
• The one exception is a DropUnique (or DropPrimaryKey) of a UNIQUE constraint that adopted its index USING INDEX: PostgreSQL drops that index with the constraint, so op add also writes the companion DropIndex chained after it and streams a second appended record (a second preview under --dry-run, a second + line in text mode) whose prev is the drop’s opid and whose note explains the companion. Each record’s tail_after is its own opid, so the last one names the true tail.
• An ExtractTable’s derived rejoin family reaches the author only as the extract-rejoin-key-added advisory on stderr, naming each derived column, child PK, and FK-back. It appears on no stdout record, so a stdout-only consumer sees no trace of elements that occupy real schema namespace.
• The free-standing advisories (enum-value-commit-boundary, extract-survivor-arm-selected, extract-rejoin-key-added, extract-reverse-ordinal-divergence among them) appear on stderr only, each as a note: <token> line plus a prose body. Most stay raw text under --as=json; extract-reverse-ordinal-divergence becomes two {"level":"note",...} objects. The set is open: treat stderr as required reading for op add rather than working from a fixed list.
• note (singular) is the free-form, code-less string of the same-as-tail advisory. It is mode-exclusive: under JSON it is the records’ note field on stdout and nothing goes to stderr; under text it is a note: line on stderr.
• outcome: minted = the op was written; noted = the op was written and carries the same-as-tail advisory, its only trigger; deduped = nothing was written. Only a SetReferenceData dedupes: one whose value the table’s resolved read already carries, on a table that is not an unjudged merge or join product (the same per-name no-op schema ref-tables and --ref report). It streams = (skipped) already-declared|not-declared <schema>.<table> as a {"type":"skipped","operator":"SetReferenceData","outcome":"deduped","kind":"already-declared|not-declared","target":"..."} record in place of appended, then the terminal ok, exit 0, identically under --dry-run and --dry-run --explain.

snapshot records

{"type":"snapshot-data","band":"<data band text>"}?
{"type":"snapshot","ddl":"<full doc>"}
{"type":"data-excluded","purpose":"...","table":"...","count":N}*
{"type":"ok"}

• Other records ride the stream around the snapshot record, so treat ok as the terminal shape rather than the whole stream. The order is snapshot-data?, snapshot, data-excluded*, ok.
• snapshot-data rides before the snapshot record whenever at least one data record was selected, and is omitted when none was. It is not label-gated: base-corpus ref rows select with no flags, so a consumer keying on a label would drop reference rows. In JSON mode the band text lives on this record and is not spliced into ddl, unlike text mode, which places it between the tables and the constraints and indexes of the printed document, so mode equivalence holds for the DDL portion only.
• data-excluded appears once per (purpose, table) counted out of the data band, after the snapshot record (the artifact emits first).
• On an OWNERSHIP exclusion (a corpus file under a shared data_root root whose header names a schema this run does not own) the same record carries two ADDITIONAL members, "cause" (other-schema when the named schema is registered, unregistered-schema when no registered schema owns that namespace) and "schema" (the owning namespace), and is keyed on (purpose, table, cause, schema) rather than summed onto (purpose, table). A "count" of 0 reports a foreign file that declares a table empty. Owned-record rows carry neither member. Owned rows emit first, then the ownership rows sorted on (table, cause, schema).
• A "cause":"not-selected" record also carries "unnamed_attested", the record’s labels that --allow-unnamed-label attested were left unnamed on purpose, when there are any. The run-level apply-risk-data-exclusions warning leaves those labels out, so a run that attests every unnamed dataset raises none; the record still counts the rows.
• Two stderr advisory codes accompany them: corpus-records-owned-by-other-schema (per foreign table, -v only in text mode, but always present as a stderr advisory object under --as=json) and corpus-foreign-records-present (one run-level warning line at default verbosity, naming the total and every owning schema).
• Render skips are not on this stdout stream. They ride the stderr advisory channel, so under --as=json they take the {"level":"warning","code":"view-render-skipped"|"element-render-skipped",...} shape on stderr, keyed on level/code rather than type/kind. They are advisory (exit stays 0), while the sibling render-blocked-on-* failures are terminal. import routes the other way and streams its advisories to stdout.

import records

{"type":"appended",...}
{"type":"skipped","kind":"...","name":"...","schema":"...","line":N,"raw_stmt_kind":"...","raw_text":"...","src_file":"..."}
{"type":"appended","operator":"Seal","reason":"<auto-or-custom>",...}
{"type":"import-summary","imported":N,"run_raw_script":N,"skipped":N,"skipped_by_kind":{"<kind>":N,…},"skipped_by_class":{"<class>":N,…}?,"sealed":N?,"sources_zero_op":N?}
{"type":"ok","data":{"dry_run":true?,"imported":N,"run_raw_script":N?,"skipped":N}}

• One appended record per minted op and one skipped record per dropped statement. raw_stmt_kind is the PG AST node name, distinct from kind, which can be a semantic class like cross-schema; drift’s skipped event omits raw_stmt_kind because drift doesn’t carry the AST node through its differ. src_file names the source file line is relative to, so a record stays locatable across a multi-file import. It is the path relative to the project root (falling back to the absolute path for a source outside the root), the same spelling as the DML sidecar’s src-file, and it is omitted, not empty, for skips with no source file (e.g. snapshot --skip-manifest view/element-render records).
• Under --seal[=<text>] a trailing Seal appended record carries a reason: auto-derived for bare --seal (imported <basename> / imported <b1>, <b2>, … / imported <stdin>, a basename that collides within the batch widened to its shortest unique trailing path), or the verbatim <text> for --seal=<text>.
• The import-summary record precedes the terminal envelope, and --summary-file <path> writes the same record as a standalone JSON object. The first four keys are normative. skipped_by_class is an additive sub-tally splitting the SAME skipped total along the disposition axis (keys gap, integrity, preserved, decision, internal-defect) and is omitted when nothing was skipped. skipped stays the aggregate over every class, so the class counts partition it rather than re-base it. Only gap and integrity can drive the exit 2; preserved (non-SMO DML set aside to the DML sidecar) and decision exit clean.
• sealed is present only under --seal-per-file, and counts the sources that sealed. sources_zero_op rides the same gate and is omitted when zero: it counts the batch sources that minted no ops and are therefore not sealed, so a reader can reconcile the input count against sealed (84 sources, 82 seals, sources_zero_op: 2). It is a source-level tally, not a skip: it never enters skipped/skipped_by_kind/skipped_by_class and never affects the exit code.
• Terminal data keys are in alphabetical order; key by name, not position. Terminal skipped is the integer count of skipped statements; per-statement detail lives only in the skipped records, and the per-kind tally lives only on import-summary, never on the terminal envelope. run_raw_script is present only when non-zero. data.dry_run: true is present only under --dry-run and absent on real runs, as drift’s data.applied is present only on a real run.
• A run passing both --force and --purge-orphaned-corpus that wrote the oplog and found at least one orphan adds a purged_orphaned_corpus object to the same data, shaped {"total":N,"by_file":{...},"by_table":{...},"pre_existing":N}, so a consumer parses ONE object rather than reading a second report printed alongside it. The object is omitted when any leg of that conjunction fails, so its absence is not a claim that nothing was orphaned. The placement is the contract; the field spellings inside that object are non-normative, so key off the object’s presence and tolerate its inner shape changing.
• Advisories ride the stdout stream under two type values (see Channel exceptions). Two kinds carry a contract:
  • {"type":"warning","kind":"import-data-motion-deferred","resembled":"...","source":"...","span":"...","child":"..."?,"hint":"..."} per deferred data-motion op (child present only on a child-shape defer);
  • {"type":"warning","kind":"import-apply-risk-summary","count":N,"by_kind":{"<apply-risk-code>":N,…}}, at most one per run, emitted only when at least one minted op is apply-risky, folding the per-op findings into a single event. Its by_kind keys are the apply-risk-* codes from Advisory note codes, in lexical key order.
• Under --ddl-only the run DECLINES every preserved-DML statement (authored DML, the non-observational members of a pg_dump data band, and the synthesized body=none floors) and lists them instead of minting them: one {"type":"not-captured","table":"...","cause":"declined by --ddl-only"} record per WRITTEN RELATION (a statement writing N relations contributes to N records), the matching {"type":"skipped","kind":"declined by --ddl-only","name":"<table>"} manifest entries, and ONE {"type":"cta",...} block after them. The declined statements take these per-TABLE records INSTEAD of their per-statement skipped ones, and import-summary’s skipped_by_kind tallies them under the same cause word, so the three surfaces agree; the aggregate skipped is unchanged.
• rows is ABSENT on the declined by --ddl-only cause, on the note and on the manifest entry alike, never 0 and never null: the cause declines a NON-observational population (authored UPDATE/DELETE/MERGE, INSERT … SELECT, and floors), for which no VALUES-tuple count is the row count. Every other cause word keeps its numeric rows, including the dump data band cause, whose (0) for a COPY … FROM stdin head is legitimate. A band row that IS observational (INSERT-form, or a COPY … FROM stdin head) therefore keeps the dump data band cause and its numeric rows even under this flag; only a band-stamped statement with no such count (a DELETE/UPDATE/MERGE, or a synthesized floor) joins this cause.
• A declined CLEARING statement (TRUNCATE t, unqualified DELETE FROM t) over a table carrying live chain records refuses the whole run before any write with code data-declined-clear (exit 2).

function-synthesized-stub

An unresolved trigger callback is accepted with a finding. Text mode emits this stream line on stdout (where <name> is the bare callback name):

finding: function-synthesized-stub: callback <name> is unresolved; a stub was synthesized and will fail at apply if <name> does not exist in the target database

JSON mode emits this NDJSON record on stdout:

{"type":"finding","kind":"function-synthesized-stub","function":"<name>"}

The JSON record carries the finding kind and callback identity; it does not repeat the text renderer’s sentence. The text line is an intermediate stream item before the human-readable import summary; the JSON record is an intermediate stream item before the terminal ok envelope. Neither form is a stderr advisory.

The advisory record

One shape serves both channels. On stdout it is one NDJSON line:

{"type":"advisory","level":"warning","code":"<code>","class":"<class>",
 "message":"…", "<declared field>":…, "detail":"…", "hint":"…"}

On stderr it is the same object minus the type key, field for field, level, detail and hint included. One render path serves both, so the two never drift.

Identity is code, alone. type is carrier framing and level is the display register; kind does not appear on an advisory record at all. detail and hint are present only when the definition declares them, so a missing key means “none declared”, never “empty”.

class is closed; code stays open. The class set is apply-risk, atomicity, data-motion, dml, render-skip, type, schema, internal; a consumer may exhaust it. The code set is open and will grow, so a consumer must tolerate one it does not recognize. class is emphatically not a severity substitute: it says what the advisory is about, not how much it matters. Severity, as far as this contract has one, is level.

In text mode an advisory renders as the <register>: <message> head, then one indented detail: <line> line per line of the rendered detail when the definition declares one, then the rendered hint as an indented hint: <hint> line when the definition declares one. A line whose value renders empty is omitted entirely rather than emitted blank. Both spellings are the ones errors and warnings use elsewhere, so an advisory’s body reads the same whichever channel or carrier delivered it.

Retired type tokens

A threaded advisory arrives as the one advisory record above, never under the warning, finding or note type values on stdout. A consumer filtering a threaded advisory on a retired token goes silently empty rather than erroring, which is why they are named here rather than left to be discovered:

A threaded advisory never prints finding:: its line reads warning: <code>: <message> or note: <code>: <message>. The plain finding stream records (function-synthesized-stub, function-identity-uncanonicalized) print finding: lines. A threaded advisory’s identity is its code, and the register set is {warning, note}; there is no finding register.

op add’s notes[] and drift’s per-op warnings[] are fields of stdout records, not advisory records, and are reached by the per-verb rows above (see Channel exceptions).

One code a correct build never emits

internal-reserved-type-violation is a carrier-internal diagnostic. It reports that retrofit’s own advisory machinery was misused (a record type reserved for the advisory carrier reached a generic writer), and it is a defect in retrofit, not something the invoking command did wrong.

It carries the ordinary envelope plus two parameter fields, type_name (the token that was refused) and entry_point (which writer took the call), and declares neither detail nor hint.

Exclude it from advisory aggregation and route it to your own defect channel. The rule generalises: exclude any advisory whose class is internal and whose emission is carrier-internal: currently internal-invalid-advisory and internal-reserved-type-violation. Counting either as a finding about your schema would attribute a retrofit bug to your work.

Stderr

text mode

Human-readable lines:

error: <code>: <message>[ at <path>[:<line>]]
  detail: <detail-line>?
  hint: <hint>?

Validation-class errors (rule-*, rule-dropped, ambiguous-element, no-match) MAY prepend a header block carrying the structured identity slots that don’t fit the error: line:

# ==== VALIDATION FAILED ====
# drop_opid=<id>?
# element_id=<id>?
# ==== end VALIDATION FAILED ====
error: <code>: <message>
  detail: <detail-line>?
  hint: <hint>?

The block renders only when at least one of drop_opid / element_id is populated; otherwise the trailing error: line already carries the code+message verbatim and the empty marker pair would just be visual noise. The editor-buffer companion in op revise -i is the load-bearing caller of the legacy embedded-message shape: its buffer-prepended variant embeds <code>: <message> because the trailing error: line never follows the user into the buffer they’re editing.

The terminal unverifiable record (see the unverifiable discriminator under json mode) carries its entries in text mode too: listing each entry’s Rule, OpID and Reason is not conditional on output mode, and text is the DEFAULT. One indented line per entry follows the error: block, in the order the entries were recorded:

error: <code>: <message>
  detail: <detail-line>?
  hint: <hint>?
  unverifiable: <rule>[ at <opid>][: <reason>]
  unverifiable: <rule>[ at <opid>][: <reason>]

There is one line per unevaluable rule, deduped by rule code (the refusal’s identity), so one op with several unevaluable rules names each of them. at <opid> and : <reason> are omitted when absent, matching the omitempty fields on the JSON entries objects; a rule with no code renders as (unnamed rule).

An accumulating refusal (one that reports every failing argument rather than stopping at the first) renders its violations array the same way, one indented line per entry after the error: block, in the order the arguments were given:

error: <covering-code>: <message>
  detail: <detail-line>?
  violation: <argument>: <code>[: <detail>]
  violation: <argument>: <code>[: <detail>]
  hint: <hint>?

Each entry carries its own per-failure code, under the envelope’s covering code (see violations under json mode). A trailing : <detail> is omitted when absent, matching the omitempty member on the JSON objects.

Notes and warnings are line-prefixed and render as the advisory record describes for text mode:

note: <message>
warning: [<code>: ]<message>
  detail: <detail-line>?
  hint: <hint>?

json mode

Stderr mostly carries advisories, each one JSON object on its own line:

{"level": "note", "message": "..."}
{"level": "warning", "code": "...", "class": "...", "message": "...", "detail": "..."?, "hint": "..."?, "<param>": …}

An in-tier advisory, a warning or note raised through the output gateway, always carries code and class, and its declared parameter fields ride as flat siblings of them, never nested under a params envelope. class is the taxonomy axis: a closed, ratified list of apply-risk, atomicity, data-motion, dml, render-skip, type, the named residual schema for codes those six do not absorb, and internal for the reserved self-report code. It is independent of level, which is the display register. class rides as its own field because that is where it survives machine reading: a code’s leading segment may repeat it for the human eye, but many codes do not carry one, so the field is the parse contract and the prefix never is. detail and hint are present only when the definition supplies them. A parameter value is a typed atomic, a typed list, or a typed list of records, never a prose fragment.

A code-less courtesy or info line is deliberately not an advisory: it emits {"level": …, "message": …} and carries no code, no class, and no parameter fields. Its identity-free shape is the signal, not an omission.

The human line puts the code after the class token, never in place of it: warning: <code>: <message>, note: <code>: <message>. The code and class values are wire tokens and are never localized; message is the rendered template and carries neither the class token nor the code.

Coverage boundary. Codes are mandatory on in-gateway advisories only. op add’s free-standing note: <token> lines and import’s stdout {"type":"warning"|"finding","kind":…} records carry no registry code, so stderr carries two grammars: the advisory object above and op add’s raw lines (see Channel exceptions).

Consumers tail stderr for diagnostics; on an enveloped (multi-record) stdout the type field is the canonical disposition. (Single-document success stdout carries no type (see the single-document exception); its disposition is “no terminal record, exit 0”.) Stderr keeps a separate level discriminator (rather than reusing type) so the stream origin is obvious to consumers doing 2>&1.

Channel exceptions

The lead’s rule (disposition on stdout, advisories on stderr) has exceptions in both directions. The categories below are the known ones, not a closed set: a merged-stream consumer must not assume every stderr line is a level-keyed JSON advisory.

Failed envelopes on stderr. Four verbs put a terminal failed envelope on stderr under JSON:

• snapshot: only its seed / data-band pre-flight abort, raised after the cut is resolved but before the first DDL byte, goes to stderr instead of stdout. A redirected retrofit snapshot > schema.sql then yields an empty file rather than a half-written artifact followed by an error object. Snapshot’s earlier failures (flag validation, engine-version resolution, replay, the fork-in-range refusal on an unreconciled fork in (genesis, --at] (exit 1, mirroring migrate’s envelope and its retrofit reconcile <shared-prev> hint), and cut selection) land on stdout like every other verb’s, so this is a narrow per-path exception, not a property of the verb.
• data list: a corpus-scan refusal and an ambiguous-layer refusal go to stderr instead of stdout.
• schema ref-tables: a refusal reading the oplog, its cut or the corpus goes to stderr instead of stdout.
• reconcile --all: the failed leaf’s envelope on a mid-run halt is written to stdout and mirrored to stderr, so it appears twice under 2>&1. The stderr copy is the contracted signal; the stdout copy is an accepted duplicate. The two records are semantically equivalent but not byte-identical (the stdout copy’s keys are alphabetical, while the stderr mirror puts type first), so de-duplicate on the parsed object or on a stable identity field such as code, never by comparing raw lines.

Only the JSON stream differs; text mode writes every error to stderr. The envelope shape is identical in every case. A consumer that must catch every structured failure should therefore read both streams (2>&1) rather than assume stdout-only. Terminal envelopes carry type and no level, which tells them apart from stderr advisories.

Stream origin: level does not imply stderr. A threaded advisory record on stdout carries level too, so under 2>&1 “has level” does not tell the channel. Use these recipes:

select(.type) alone matches both the advisory records and every ordinary stream record; do not use it.

import’s per-statement advisories are stdout stream records, not stderr advisories. import streams its findings about the statements it processed on stdout, so an advisory is ordered against the appended / skipped records it describes. Dispatch is two-part. A record threaded onto the advisory carrier arrives as type == "advisory" and is identified by its code; a plain stream record keeps its kind under one of two type values. So:

• select(.type == "advisory") then switch on .code: the threaded half;
• select(.type == "warning" or .type == "finding") then switch on .kind: the plain half. finding carries function-synthesized-stub and function-identity-uncanonicalized; warning carries the rest.

Do not filter to type == "warning" alone; it drops the finding records and the advisory ones. This holds in both modes: JSON emits the record on stdout, and text renders the same finding as a line on stdout. A plain stream record (import-data-motion-deferred, import-apply-risk-summary, import-extract-recognized, serial-folded-to-identity, parameterized-type-deparse-failed, …) gets a note:, warning: or finding: prefix chosen per record, so the text prefix does not tell you the record type. The kind set is open and not exhaustively documented, and the remaining keys on a record are per-kind. A consumer must therefore switch on kind and tolerate an unknown one (log and continue) rather than assume a closed set or a fixed key shape. import records spells out only the two kinds that carry a cross-version contract.

The carve-out covers that streamed family only; import still writes to stderr, so do not run it under 2>/dev/null. One import warning stays on the stderr channel: rollback-incomplete, emitted once per leg when a failed run could not undo a file it had already written. It names the residual path and is the one advisory a consumer most needs, so it rides the diagnostic channel rather than a stdout stream that a caller may be parsing as the run’s report.

Advisory content inside stdout records. op add’s structured notes[] and drift’s per-op warnings[] are fields of stdout records, and under --as=json they are the only copy. Each is mode-exclusive, riding stdout under JSON and stderr under text, so a finding is never duplicated across channels within one mode. Read the per-verb rows rather than assume a single global stream rule.

Raw-text advisories. Several op add advisories (enum-value-commit-boundary, extract-survivor-arm-selected, extract-rejoin-key-added among them) are written straight to stderr as note: <token> plus an optional free-text body, bypassing the output gateway, so they stay plain text even under --as=json and have neither level nor type (see op add records).

Raw refusal / violation diagnostics. The same bypass carries op add’s refusal: <token> lines (plus body prose) and op seal’s violation: diagnostic, which precedes the failed envelope on stdout. The structured counterpart still arrives (a refusal’s stdout envelope carries code: "refusal-<token>"), so parse the envelope for machine decisions and treat these lines as human diagnostics.

A consumer parsing stderr as NDJSON must therefore tolerate a line that does not parse as JSON rather than treating it as a protocol error.

Advisory note codes

Advisory code values are part of the wire format: the spelling is the contract, codes are added but never renamed, and a consumer switches on the code rather than on the message text.

The table below inventories the three families that carry a cross-verb contract. It is not exhaustive and is not a closed set: new codes are added as operators gain advisories, so a consumer must treat an unrecognized code as a forward-compatible advisory (log it, do not fail on it) rather than assume the list below is complete.

The axes are independent: data-loss-on-apply says the apply loses information, the apply-risk-* family says the apply is slow or locking, and the data-motion-* / cascade-* family says the op’s scope or atomicity is wider than its name suggests. A run can carry several, and none implies another.

The apply-risk-* remedies above shorten how long a lock is held. To bound how long the apply waits for one (so a statement queued behind a long-running query gives up instead of stalling every later query on the table), emit with migrate --lock-timeout=<duration>, which writes a SET LOCAL lock_timeout line at the head of every transaction the file opens; see Bounding the lock wait in docs/migrate.md. None of these families is a refusal: an advisory never by itself changes the verb’s disposition or exit code. A run carrying advisories can still exit non-zero for an unrelated reason (a loss-bearing import skip, for one), so the presence of an advisory says nothing about the exit.

Where each family surfaces:

• op add: all three families ride the structured notes[] (JSON) / one note: <code>: <message> stderr line per entry (text). It is the only verb that emits the data-motion-* / cascade-* family: those advisories describe an authored op’s genealogy scope, which no other verb mints. At most one apply-risk-* finding per op. Under JSON the same notes[] appears on both the appended record and the terminal envelope (see the op add row).
• drift: data-loss-on-apply and apply-risk-* only; both ride the op-applied record’s warnings[] (JSON) or a warning: stderr line (text), mode-exclusively: a finding appears on exactly one channel per mode, never both.
• import: the apply-risk-* findings are not emitted per op. They fold into one run-level import-apply-risk-summary stdout stream record whose by_kind map counts them by code (see the import rows).
• migrate: reuses the validating-FK predicate for its apply-time lock-risk pass, so the author-time and apply-time arms cannot drift.
• validate --fail-on-apply-risk: the one opt-in exception to “never by itself changes the exit”. Over each schema’s (latest Seal, head] window, with migrate’s own newborn walk, it raises the apply-risk-window-* codes above the mode split and fails through the structural-gate envelope (exit 2), Detail by code and count, Hint naming each code’s recovery. The same facts ride data.apply_risk = {envelope?, envelope_source?, counted[]{code, schema, opid, table, pair?}, unsealed[]{schema, table_count}}, present whenever the flag is set; envelope / envelope_source appear only when a same-window pair was counted. Without the flag validate emits none of this.

Project exclusions: [[exclude]]

A project that declares [[exclude]] entries in retrofit.toml has the statements they own removed from each parsed input before any walker reads it (import, identify, drift, migrate --from-dump, data capture). The set is project state; no flag adds to it, and the registry-less -f mode applies none. Every run reports what it applied:

An entry that owned nothing in a run is listed in one courtesy-tier line (-q removes it); a run that refuses reports none of the above.

Advisory absence is not a negative claim

An advisory on stderr is a positive claim: when migrate writes wrapper-suppressed, a file was emitted and that file carries no BEGIN;/COMMIT; wrapper. The converse does not hold. The absence of a wrapper-suppressed advisory must not be read as proof that a wrapper was emitted.

Absence has five causes, and stderr cannot tell them apart:

1. No suppression: retrofit wrapped the file, so there was nothing to advise about.
2. A failed emission: the write did not complete, so no complete artifact exists for the advisory to describe. Advisories that assert an emission are withheld unless the emission completed successfully, so a failing run is silent about a file it never finished producing. In text mode a partial artifact may already have reached stdout before the failure; the withheld advisory says nothing about how much.
3. A lost stderr write: advisory writes are best-effort and their result is discarded, so a warning retrofit did produce may not reach a consumer.
4. The advisory tier was quieted: -qq drops the whole advisory tier from the human text surface, so nothing in it reaches stderr. This is a display control: the advisory was still raised, and --as=json carries it in full at every level.
5. The condition was attested away: --allow-external-atomicity states that the apply context owns transaction atomicity, which answers the advisory’s question rather than silencing it. The advisory is then not raised at all, in either mode.

Only case 2 is distinguishable from case 1 by the terminal disposition: a failed emission exits non-zero (the envelope names the cause: an I/O fault is io-error, a recovered internal fault is migrate-internal). Case 3 is not distinguishable this way: a lost advisory write does not affect the run’s outcome, so it exits zero exactly as case 1 does. Cases 4 and 5 are both distinguishable, and deliberately so: case 4 is recorded by the flag in the invocation and leaves the machine record untouched, and case 5 leaves a structural acknowledgement (below).

A consumer needing the positive fact (was this file wrapped?) must read the emitted SQL itself. The wrapper, when present, is literal BEGIN; / COMMIT; text in the artifact; under --as=json it is inside the envelope’s ddl payload.

One structured surface does state a related fact separately. On a run that passed --allow-external-atomicity, the terminal envelope’s data object carries the reserved key external_atomicity_attested. Its presence means the attestation was accepted; its absence means the run was not attested, on every arm, so an audit consumer can always distinguish wrapper suppressed, fact attested from no wrapper question arose. It never states whether a wrapper was emitted, which remains a question only the SQL answers.

The same reasoning applies to every advisory: this contract makes retrofit’s positive claims trustworthy; it does not make its silence meaningful.

Exit codes

The Group column names retrofit’s internal error class for the row. It is not on the wire: no record carries it.

Exit 2 is shared by five groups, so the exit value alone does not name the cause: the terminal record’s code is the discriminator. A loss-bearing import failure always carries the frozen code import-loss-bearing-skips, covering both the capability-gap arm and the integrity arm; a CI consumer matches that code rather than inferring from exit 2. --allow-capability-gaps downgrades the capability-gap arm to exit 0; the integrity arm has no such escape.

drift follows the same contract over its skipped items. Each one carries a class from the classifier import uses. The run exits 0 over itemized content: ops applied (or previewed under --dry-run) and skips classed decision or preserved, each set aside by a named rationale. Exit 0 does not mean “no divergence”; expressible drift still applies ops at exit 0. A skip classed internal-defect also exits 0, with a drift-skip-internal-defect warning. When any gap skip stands, on --dry-run and real runs alike, the run fails with the frozen code drift-unreconciled-skips (exit 2) after the drift-run-summary record. Its hint names each gap raw kind with its count, and names apart the dependents of a question the run itself answered (rerun drift: the next run plans against the answer). A real run’s appended ops, and a --seal seal, persist before it fails. A skip kind the classifier does not list classes gap and raises drift-skip-unclassified. --allow-capability-gaps waives the gap arm: exit 0 with the same summary record. Every refusal, parse error and needs-interactive-resolution (exit 3) fires first and wins. question items and --ignore-drops’ deferred-drop items never change the exit. Content the walker drops with no item at all never reaches the exit: an EXCLUDE constraint (inline or ALTER TABLE … ADD CONSTRAINT), and an index or ENABLE ROW LEVEL SECURITY on a table drift pairs as a rename.

reconcile exits 2 for a file only a newer build can read, whatever exit the same code carries on other verbs: an unknown operator (unknown-operator with the upgrade hint, a ~ tombstone included), a too-new format or model version (oplog-format-too-new, model-version-too-new), and an unknown key or retrofit-* header (writes-blocked-on-unknowns). The fix is the caller’s build, not the log; the code tells them apart. Content the author fixes stays exit 1: a conflict marker (oplog-conflict-marker), a repeated header (missing-metadata-header), a renamed or split operator, a line with no operator name, a fork it refuses. On reconcile, op revise -i and the op verbs an oplog that exists but cannot be read refuses as oplog-unreadable (exit 2), as on validate; a missing one stays oplog-not-found (exit 2).

--allow-capability-gaps downgrades an invocation only when it carries capability-gap skips, no integrity skips, and minted at least one op. An integrity skip fails regardless of op count or --allow-capability-gaps. The op count is batch-wide, not per-source: an invocation that minted zero ops across all its sources and carries a gap or integrity skip fails with exit 2 on either arm, because a downgrade there would let a run that imported nothing report success. So:

• A multi-source run is not caught merely because one source was gap-only. If any other source minted an op, the batch is non-empty and --allow-capability-gaps downgrades normally.
• The zero-op batch may still have produced preserved DML, so the loss-bearing skip need not be the run’s only observable output; the guard keys on zero ops, not on zero output.

Under --as=json, the exit code matches the terminal record’s disposition: type:"ok" exits 0 (or 0 with a warning), type:"failed" exits per the table above, and type:"unverifiable" exits 2. The single-document verbs (op info and identify) emit no terminal record on success and exit 0; on failure they still emit {"type":"failed",...} and exit per the same table. So exit code and stdout disposition stay consistent on both paths.

Data-band records

migrate and snapshot check each preserved data record against the cut they render. Three record types report the result. They ride stdout in this order, after the verb’s own artifact record and before ok:

A body that needed no repair produces no record at all.

The source-band bound is on the INGEST side. data capture, import and drift refuse a source whose per-table INSERT band exceeds the schema’s data_band_max_bytes with the terminal failed envelope code: "data-band-over-cap" (exit 2), carrying an append-only "band_over_caps":[{"schema":"<s>","table":"<t>","bytes":N,"bound":N,"statements":N,"source":"<file>"?}] key: one row per over-cap table, ordered by bytes descending, then (schema, table) byte-wise, then source. schema and table are separate members (a bare name carries "schema":""); the numbers are plain JSON integers; source appears only on import, whose sum is per source file. The key is omitempty, so every other envelope is byte-unchanged. Text mode renders the same rows, in the same order, as band: lines spelling the pair schema.table.

Refusals are not on this stream. A record that cannot be made true fails the run with stale-dml-reference on stderr (exit 2), listing every refused record with its reason. --allow-stale-dml, accepted by both migrate and snapshot, downgrades those refusals to warnings and emits each body under a -- WARNING: stale reference comment at exit 0, except a forked chain, which is not attestable and refuses either way.

A record whose anchor-op= names an opid the oplog no longer holds cannot be positioned at all, and refuses the run rather than emitting (--allow-stale-dml does not downgrade it). migrate refuses it as dml-anchor-unresolved; snapshot has no window, so it refuses with data check’s own data-file-anchor-unresolved envelope (same Message, the same <file>: record seq=<n> anchors on <opid> Detail lines, and the same retrofit data repin <file> --anchor-op <opid> hint) on stderr, before the first DDL byte, exit 2. Only a record the band would emit refuses: one that the run’s --labels do not select, that --table / --exclude-table / --over leave out, or that is history-bound is counted in data-excluded as before. data list is inspection and never refuses it.

Why these rules

A few rationales for choices that look arbitrary:

• One persistent flag instead of per-verb --as flags: humans don’t remember which verbs accept which output modes. One flag, one place to look.
• JSON envelopes are single-line NDJSON (terminal \n): consumers can read line-by-line in shell pipelines, and jq -c round-trips them.
• Errors emit on stdout under –as=json (not stderr): the disposition lives on a single stream so consumers can retrofit X --as=json | jq for both ok and error paths. Stderr stays for diagnostics. Channel exceptions lists the failed envelopes that reach stderr.
• Validation-class errors get a header block in text mode when they carry structured identity slots (drop_opid / element_id); the block lists only those slots, above the trailing error: line that carries the message. The op revise -i editor buffer’s block also embeds <code>: <message>, because the buffer is what the user edits on retry and the error: line does not follow into it.
• No emoji, no color: this CLI is meant to be piped. ANSI sequences and emoji break grep, ripgrep, awk, and humans-with-screen-readers. Forever.
• Streaming over single-envelope: op show over a 100k-op log can’t buffer 50MB into a single JSON object. Per-line records preserve streaming and let consumers tail output incrementally.