Decide: one shape for the `--json` top-level `error` (scan and get emit both a string and a {code, message} object)

[mikolalysenko]

[agent] Filed by the scheduled architecture audit routine (CLI and core). Register: discussion #560 register.

Kind: decision. Source: review 2.8 and R4; register C14.

Question

scan, get and rollback aren't on the unified envelope yet. Their top-level error key has no fixed type: within one command, it is sometimes a bare string and sometimes a {code, message} object, depending on which failure fired. A consumer can't read .error without checking its type first. Which shape should the legacy commands emit?

Options:

1. Always {code, message} (recommended). This matches EnvelopeError, which the migrated commands already use, so every string site gets a stable code. It is a breaking change for consumers that read .error as a string, so it needs a MAJOR note in CLI_CONTRACT.md.
2. Keep error as a string and add a sibling errorCode everywhere. get's lock failure already does this. It's additive, but the object-shaped sites would then have to flip back to strings, which also breaks consumers.
3. Move scan, get and rollback onto Envelope now. This finishes the v3.0 migration in one MAJOR step. It's the largest change, and it overlaps C11 (the run_scan split).

Whichever option is chosen, one emitter per command should own the shape, so a new failure path can't pick its own.

Problem (main @ 045d7ec)

• get:
  • string: report_error emits {"status":"error","error":"<msg>"};
  • string + code: report_lock_failure emits {"status":"error","errorCode":…,"error":"<msg>"};
  • object: vendor failure and L3801-L3802 emit "error": {"code","message"}.
• scan:
  • object: embedded-VEX failure;
  • string: emit_discovery_error_json, L1281-L1282 and L2062-L2063.`` The doc comment of the first says it keeps "one consistent scan-error schema".
• rollback: string only, from emit_rollback_error.
• The migrated commands use EnvelopeError { code, message }. CLI_CONTRACT.md "Migration status (v3.0)" still lists scan, get and rollback as ⏳.

Impact

Every PR-bot or dashboard consumer has to type-check .error. Each new failure path picks a shape ad hoc, which is how get ended up with three. This is also the root of the untyped error codes (C13): the string sites carry no code at all.

Proposed change (after the decision)

• Add one fn emit_legacy_error(cmd, code, message) per legacy command, or a shared one in json_envelope.rs.
• Route every site above through it, and delete report_error, emit_rollback_error and emit_discovery_error_json's ad-hoc assignment.
• Assign a code to each string site, reusing existing codes where they exist.

Size and scope

Option 1 is about 150 production lines across get.rs, scan/mod.rs, rollback.rs and json_envelope.rs, plus test updates and a contract note. The per-patch patches[*].error strings and rollback's results[*].error are out of scope: only the top-level key is.

Acceptance criteria

• An owner picks an option.
• Each of scan, get and rollback emits a single top-level error type on every failure path, with a test per path that asserts the type.
• CLI_CONTRACT.md documents the shape and the change (MAJOR if option 1 or 3).
• The existing get/scan/rollback JSON tests stay green or are updated in the same PR.

Dependencies

• Feeds C13 (typed error-code registry). Option 3 overlaps C11 (run_scan split).
• Not blocked by anything.

[mikolalysenko]

[agent] Triage: priority:p3 (CLI JSON contract). This is a decision issue, so it keeps agent:needs-human until an owner picks an option. Agents won't claim it before then.

---

Generated by Claude Code