feat(cli): carry the ADR-0112 code and httpStatus in --format json failure envelopes (#13510)

* feat(cli): carry the ADR-0112 code and httpStatus in --format json failure envelopes
Every machine-readable failure the CLI emits was `{ success: false, error:
error.message }` and nothing else — 48 sites under `packages/cli/src/commands/`.
The error reaching those `catch` blocks from `@objectstack/client` is not a bare
`Error`: the SDK's `fetch` wrapper attaches `err.code` (the semantic ADR-0112
string, normalized across both server dialects) and `err.httpStatus`. Both were
discarded at the CLI boundary, so a script had to substring-match an English
sentence that no contract pins.
One shared builder (`errorCodeFields` in `utils/format.ts`) plus 48 call-site
spreads. Additive: `success` and `error` keep their meaning and spelling, the
payload stays flat, and the two keys are ABSENT — not `undefined` — when the
thrown error did not carry them. No fallback code is invented for a
locally-thrown plain `Error`. Human `table` output is untouched.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TvqBFLRzXdSPcbusDoED9k
* test(cli): give the #13347 envelope cases an explicit wall-clock budget
Each case drives a real `Command.run` against the real oclif root — ~0.8s per
case on an idle box, and measured TIMING OUT at vitest's 5s default when the
file ran inside `@objectstack/cli`'s full 220-file suite on a shared container.
Wall-clock only: no assertion moves. The neighbouring
`delete-reset-carriers.test.ts` reaches the same conclusion the same way.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TvqBFLRzXdSPcbusDoED9k
* docs(cli): declare errorCodeFields.code's real value space — pass-through, ADR-0112 for wire failures, Node errno for local I/O
Contract-review amendment on #13510: the field doc and changeset called
code 'the semantic ADR-0112 code', but the builder is a structural
pass-through and os validate/compile/lint throw errno-carrying fs errors
inside the same try, so ENOENT/ENOTDIR are genuinely publishable values.
Behaviour unchanged (the ruling's literal pass-through shape stands);
only the declaration now matches it. The vocabularies are disjoint
(errnos are E-prefixed OS names), so ADR-0112 branches cannot
false-match an errno.
---------
Co-authored-by: Claude <noreply@anthropic.com>

Author: os-trump

.changeset/cli-json-error-envelope-adr-0112-code.md

@@ -0,0 +1,81 @@
+---
+"@objectstack/cli": minor
+---
+
+feat(cli): `--format json` failure envelopes carry the ADR-0112 `code` and `httpStatus` (#13347)
+
+Every machine-readable failure this CLI emits was built the same way — 48 sites
+under `packages/cli/src/commands/`:
+
+```ts
+awaitemitJson({ success: false, error: error.message });
+```
+
+The payload carried the human sentence and nothing else. The error reaching
+those `catch` blocks from `@objectstack/client` is not a bare `Error`: the SDK's
+`fetch` wrapper attaches `err.code` (the semantic ADR-0112 string, normalized to
+the same spelling across the flat `@objectstack/rest` envelope and the wrapped
+runtime-dispatcher one) and `err.httpStatus`. Both were discarded at the CLI
+boundary, so the one outcome a script most needs to branch on — *someone else
+edited it, re-read and retry* vs *you are not allowed* vs *the server is down* —
+was separable only by substring-matching an English sentence that no contract
+pins.
+
+A stale-pin refusal from `os meta delete --if-match` used to read:
+
+```json
+{
+"success": false,
+"error": "[metadata_conflict] view/race_probe has been modified since you loaded it. …"
+}
+```
+
+and now reads:
+
+```json
+{
+"success": false,
+"error": "[metadata_conflict] view/race_probe has been modified since you loaded it. …",
+"code": "METADATA_CONFLICT",
+"httpStatus": 409
+}
+```
+
+Maintainer ruling 2026-08-30 (option **A** of three):
+
+- The payload stays **FLAT**. Nesting into `{ error: { code, message, httpStatus } }`
+ was considered and declined as breaking.
+-`success` and `error` keep their current meaning **and spelling**.
+- The two keys are emitted **only when the thrown error carries them**, and are
+**absent** — not `undefined` — otherwise. No fallback code is invented for a
+ locally-thrown plain `Error`: this CLI's own input refusals get no code,
+ deliberately, because ADR-0112's ledger is the authority on who may mint one.
+
+One value-space note, stated so the declaration matches what ships: `code` is a
+**pass-through**, never minted or filtered. On wire failures it is the semantic
+ADR-0112 string the SDK attached; on local I/O failures inside the same `try`
+(`os validate` reading a `src/docs` that is a file, say) it is the Node errno
+(`ENOENT`, `ENOTDIR`, …). The two vocabularies are disjoint — errnos are
+`E`-prefixed OS names — so a consumer branching on ADR-0112 codes cannot
+false-match an errno, but not every emitted `code` is ledger-owned.
+
+Human (`table`) output is untouched.
+
+**Why `minor` and not `patch`.** Maintainer-set, and it overrides the obvious
+reading: this is a shape change to an **already-published error envelope**, and
+that makes it minor even though it is purely additive.
+
+**Migration.** Nothing is required — no key is removed, renamed or re-typed, and
+every payload this CLI emitted before is still emitted, byte-for-byte, minus the
+two new keys. Two things are worth knowing before you rely on the new ones:
+
+-**The envelope is polymorphic, by design.**`code` and `httpStatus` are absent
+ whenever the failure did not carry them, which a consumer cannot distinguish
+ from an older CLI. Branch on presence (`if (payload.code === 'METADATA_CONFLICT')`),
+ never on absence meaning "success" or "unsupported version". This cost was
+ weighed against breaking every existing consumer, and the non-breaking side won.
+-**Stop substring-matching the sentence.**`error` is prose and no contract pins
+ its wording; the bracketed `[metadata_conflict]` tag some messages carry today
+ is a property of one producer, not a contract, and a separate card argues for
+ removing it. Code that reads the sentence to classify a failure should move to
+`code` (with `httpStatus` as the coarse fallback).

packages/cli/src/commands/cloud/login.ts

@@ -73,7 +73,7 @@ import * as readline from 'node:readline/promises';
 import{stdinasinput,stdoutasoutput}from'node:process';
 import{Command,Flags}from'@oclif/core';
 importtype{CliExitCode}from'../../utils/format.js';
-import{printHeader,printKV,printSuccess,printError,emitJson}from'../../utils/format.js';
+import{printHeader,printKV,printSuccess,printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{loginWithBrowser,loginWithPassword}from'../../utils/auth-flows.js';
 import{DEFAULT_CLOUD_URL,readCloudConfig,writeCloudConfig}from'../../utils/cloud-config.js';
 
@@ -246,7 +246,7 @@ export default class CloudLogin extends Command {
 // written (an expired code, a denied approval, a poll failure), so an
 // indented payload here would recreate a two-document stream on the
 // path a consumer is least able to recover from.
-awaitemitRecord({success: false,error: error.message});
+awaitemitRecord({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/cloud/logout.ts

@@ -8,7 +8,7 @@
 
 import{Command,Flags}from'@oclif/core';
 import{ObjectStackClient}from'@objectstack/client';
-import{printHeader,printSuccess,printError,emitJson}from'../../utils/format.js';
+import{printHeader,printSuccess,printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{deleteCloudConfig,tryReadCloudConfig}from'../../utils/cloud-config.js';
 
 exportdefaultclassCloudLogoutextendsCommand{
@@ -46,7 +46,7 @@ export default class CloudLogout extends Command {
 }
 }catch(error: any){
 if(flags.json){
-awaitemitJson({success: false,error: error.message});
+awaitemitJson({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/cloud/whoami.ts

@@ -7,7 +7,7 @@
  */
 
 import{Command,Flags}from'@oclif/core';
-import{printHeader,printKV,printSuccess,printError,emitJson,isExitSignal}from'../../utils/format.js';
+import{printHeader,printKV,printSuccess,printError,emitJson,isExitSignal,errorCodeFields}from'../../utils/format.js';
 import{tryReadCloudConfig}from'../../utils/cloud-config.js';
 
 exportdefaultclassCloudWhoamiextendsCommand{
@@ -72,7 +72,7 @@ export default class CloudWhoami extends Command {
 }catch(error: any){
 if(isExitSignal(error))throwerror;
 if(flags.json){
-awaitemitJson({success: false,error: error.message});
+awaitemitJson({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/compile.ts

@@ -39,6 +39,7 @@ import {
 printMetadataStats,
 emitJson,
 isExitSignal,
+errorCodeFields,
 }from'../utils/format.js';
 import{checkSpecVersionGap}from'../utils/spec-version.js';
 
@@ -720,7 +721,7 @@ export default class Compile extends Command {
 }catch(error: any){
 if(isExitSignal(error))throwerror;
 if(flags.json){
-awaitemitJson({success: false,error: error.message,warnings: warningsSoFar(),conversions: conversionNotices},0,{compact: true});
+awaitemitJson({success: false,error: error.message,...errorCodeFields(error),warnings: warningsSoFar(),conversions: conversionNotices},0,{compact: true});
 this.exit(1);
 }
 console.log('');

packages/cli/src/commands/data/create.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -100,6 +100,7 @@ export default class DataCreate extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/delete.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -83,6 +83,7 @@ export default class DataDelete extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/get.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,emitJson}from'../../utils/format.js';
+import{printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -74,6 +74,7 @@ export default class DataGet extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/query.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,emitJson}from'../../utils/format.js';
+import{printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -117,6 +117,7 @@ export default class DataQuery extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/update.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -104,6 +104,7 @@ export default class DataUpdate extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

.changeset/cli-json-error-envelope-adr-0112-code.md

@@ -0,0 +1,81 @@
+---
+"@objectstack/cli": minor
+---
+
+feat(cli): `--format json` failure envelopes carry the ADR-0112 `code` and `httpStatus` (#13347)
+
+Every machine-readable failure this CLI emits was built the same way — 48 sites
+under `packages/cli/src/commands/`:
+
+```ts
+awaitemitJson({ success: false, error: error.message });
+```
+
+The payload carried the human sentence and nothing else. The error reaching
+those `catch` blocks from `@objectstack/client` is not a bare `Error`: the SDK's
+`fetch` wrapper attaches `err.code` (the semantic ADR-0112 string, normalized to
+the same spelling across the flat `@objectstack/rest` envelope and the wrapped
+runtime-dispatcher one) and `err.httpStatus`. Both were discarded at the CLI
+boundary, so the one outcome a script most needs to branch on — *someone else
+edited it, re-read and retry* vs *you are not allowed* vs *the server is down* —
+was separable only by substring-matching an English sentence that no contract
+pins.
+
+A stale-pin refusal from `os meta delete --if-match` used to read:
+
+```json
+{
+"success": false,
+"error": "[metadata_conflict] view/race_probe has been modified since you loaded it. …"
+}
+```
+
+and now reads:
+
+```json
+{
+"success": false,
+"error": "[metadata_conflict] view/race_probe has been modified since you loaded it. …",
+"code": "METADATA_CONFLICT",
+"httpStatus": 409
+}
+```
+
+Maintainer ruling 2026-08-30 (option **A** of three):
+
+- The payload stays **FLAT**. Nesting into `{ error: { code, message, httpStatus } }`
+ was considered and declined as breaking.
+-`success` and `error` keep their current meaning **and spelling**.
+- The two keys are emitted **only when the thrown error carries them**, and are
+**absent** — not `undefined` — otherwise. No fallback code is invented for a
+ locally-thrown plain `Error`: this CLI's own input refusals get no code,
+ deliberately, because ADR-0112's ledger is the authority on who may mint one.
+
+One value-space note, stated so the declaration matches what ships: `code` is a
+**pass-through**, never minted or filtered. On wire failures it is the semantic
+ADR-0112 string the SDK attached; on local I/O failures inside the same `try`
+(`os validate` reading a `src/docs` that is a file, say) it is the Node errno
+(`ENOENT`, `ENOTDIR`, …). The two vocabularies are disjoint — errnos are
+`E`-prefixed OS names — so a consumer branching on ADR-0112 codes cannot
+false-match an errno, but not every emitted `code` is ledger-owned.
+
+Human (`table`) output is untouched.
+
+**Why `minor` and not `patch`.** Maintainer-set, and it overrides the obvious
+reading: this is a shape change to an **already-published error envelope**, and
+that makes it minor even though it is purely additive.
+
+**Migration.** Nothing is required — no key is removed, renamed or re-typed, and
+every payload this CLI emitted before is still emitted, byte-for-byte, minus the
+two new keys. Two things are worth knowing before you rely on the new ones:
+
+-**The envelope is polymorphic, by design.**`code` and `httpStatus` are absent
+ whenever the failure did not carry them, which a consumer cannot distinguish
+ from an older CLI. Branch on presence (`if (payload.code === 'METADATA_CONFLICT')`),
+ never on absence meaning "success" or "unsupported version". This cost was
+ weighed against breaking every existing consumer, and the non-breaking side won.
+-**Stop substring-matching the sentence.**`error` is prose and no contract pins
+ its wording; the bracketed `[metadata_conflict]` tag some messages carry today
+ is a property of one producer, not a contract, and a separate card argues for
+ removing it. Code that reads the sentence to classify a failure should move to
+`code` (with `httpStatus` as the coarse fallback).

packages/cli/src/commands/cloud/login.ts

@@ -73,7 +73,7 @@ import * as readline from 'node:readline/promises';
 import{stdinasinput,stdoutasoutput}from'node:process';
 import{Command,Flags}from'@oclif/core';
 importtype{CliExitCode}from'../../utils/format.js';
-import{printHeader,printKV,printSuccess,printError,emitJson}from'../../utils/format.js';
+import{printHeader,printKV,printSuccess,printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{loginWithBrowser,loginWithPassword}from'../../utils/auth-flows.js';
 import{DEFAULT_CLOUD_URL,readCloudConfig,writeCloudConfig}from'../../utils/cloud-config.js';
 
@@ -246,7 +246,7 @@ export default class CloudLogin extends Command {
 // written (an expired code, a denied approval, a poll failure), so an
 // indented payload here would recreate a two-document stream on the
 // path a consumer is least able to recover from.
-awaitemitRecord({success: false,error: error.message});
+awaitemitRecord({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/cloud/logout.ts

@@ -8,7 +8,7 @@
 
 import{Command,Flags}from'@oclif/core';
 import{ObjectStackClient}from'@objectstack/client';
-import{printHeader,printSuccess,printError,emitJson}from'../../utils/format.js';
+import{printHeader,printSuccess,printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{deleteCloudConfig,tryReadCloudConfig}from'../../utils/cloud-config.js';
 
 exportdefaultclassCloudLogoutextendsCommand{
@@ -46,7 +46,7 @@ export default class CloudLogout extends Command {
 }
 }catch(error: any){
 if(flags.json){
-awaitemitJson({success: false,error: error.message});
+awaitemitJson({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/cloud/whoami.ts

@@ -7,7 +7,7 @@
  */
 
 import{Command,Flags}from'@oclif/core';
-import{printHeader,printKV,printSuccess,printError,emitJson,isExitSignal}from'../../utils/format.js';
+import{printHeader,printKV,printSuccess,printError,emitJson,isExitSignal,errorCodeFields}from'../../utils/format.js';
 import{tryReadCloudConfig}from'../../utils/cloud-config.js';
 
 exportdefaultclassCloudWhoamiextendsCommand{
@@ -72,7 +72,7 @@ export default class CloudWhoami extends Command {
 }catch(error: any){
 if(isExitSignal(error))throwerror;
 if(flags.json){
-awaitemitJson({success: false,error: error.message});
+awaitemitJson({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/compile.ts

@@ -39,6 +39,7 @@ import {
 printMetadataStats,
 emitJson,
 isExitSignal,
+errorCodeFields,
 }from'../utils/format.js';
 import{checkSpecVersionGap}from'../utils/spec-version.js';
 
@@ -720,7 +721,7 @@ export default class Compile extends Command {
 }catch(error: any){
 if(isExitSignal(error))throwerror;
 if(flags.json){
-awaitemitJson({success: false,error: error.message,warnings: warningsSoFar(),conversions: conversionNotices},0,{compact: true});
+awaitemitJson({success: false,error: error.message,...errorCodeFields(error),warnings: warningsSoFar(),conversions: conversionNotices},0,{compact: true});
 this.exit(1);
 }
 console.log('');

packages/cli/src/commands/data/create.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -100,6 +100,7 @@ export default class DataCreate extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/delete.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -83,6 +83,7 @@ export default class DataDelete extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/get.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,emitJson}from'../../utils/format.js';
+import{printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -74,6 +74,7 @@ export default class DataGet extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/query.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,emitJson}from'../../utils/format.js';
+import{printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -117,6 +117,7 @@ export default class DataQuery extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/update.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -104,6 +104,7 @@ export default class DataUpdate extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

.changeset/cli-json-error-envelope-adr-0112-code.md

@@ -0,0 +1,81 @@
+---
+"@objectstack/cli": minor
+---
+
+feat(cli): `--format json` failure envelopes carry the ADR-0112 `code` and `httpStatus` (#13347)
+
+Every machine-readable failure this CLI emits was built the same way — 48 sites
+under `packages/cli/src/commands/`:
+
+```ts
+awaitemitJson({ success: false, error: error.message });
+```
+
+The payload carried the human sentence and nothing else. The error reaching
+those `catch` blocks from `@objectstack/client` is not a bare `Error`: the SDK's
+`fetch` wrapper attaches `err.code` (the semantic ADR-0112 string, normalized to
+the same spelling across the flat `@objectstack/rest` envelope and the wrapped
+runtime-dispatcher one) and `err.httpStatus`. Both were discarded at the CLI
+boundary, so the one outcome a script most needs to branch on — *someone else
+edited it, re-read and retry* vs *you are not allowed* vs *the server is down* —
+was separable only by substring-matching an English sentence that no contract
+pins.
+
+A stale-pin refusal from `os meta delete --if-match` used to read:
+
+```json
+{
+"success": false,
+"error": "[metadata_conflict] view/race_probe has been modified since you loaded it. …"
+}
+```
+
+and now reads:
+
+```json
+{
+"success": false,
+"error": "[metadata_conflict] view/race_probe has been modified since you loaded it. …",
+"code": "METADATA_CONFLICT",
+"httpStatus": 409
+}
+```
+
+Maintainer ruling 2026-08-30 (option **A** of three):
+
+- The payload stays **FLAT**. Nesting into `{ error: { code, message, httpStatus } }`
+ was considered and declined as breaking.
+-`success` and `error` keep their current meaning **and spelling**.
+- The two keys are emitted **only when the thrown error carries them**, and are
+**absent** — not `undefined` — otherwise. No fallback code is invented for a
+ locally-thrown plain `Error`: this CLI's own input refusals get no code,
+ deliberately, because ADR-0112's ledger is the authority on who may mint one.
+
+One value-space note, stated so the declaration matches what ships: `code` is a
+**pass-through**, never minted or filtered. On wire failures it is the semantic
+ADR-0112 string the SDK attached; on local I/O failures inside the same `try`
+(`os validate` reading a `src/docs` that is a file, say) it is the Node errno
+(`ENOENT`, `ENOTDIR`, …). The two vocabularies are disjoint — errnos are
+`E`-prefixed OS names — so a consumer branching on ADR-0112 codes cannot
+false-match an errno, but not every emitted `code` is ledger-owned.
+
+Human (`table`) output is untouched.
+
+**Why `minor` and not `patch`.** Maintainer-set, and it overrides the obvious
+reading: this is a shape change to an **already-published error envelope**, and
+that makes it minor even though it is purely additive.
+
+**Migration.** Nothing is required — no key is removed, renamed or re-typed, and
+every payload this CLI emitted before is still emitted, byte-for-byte, minus the
+two new keys. Two things are worth knowing before you rely on the new ones:
+
+-**The envelope is polymorphic, by design.**`code` and `httpStatus` are absent
+ whenever the failure did not carry them, which a consumer cannot distinguish
+ from an older CLI. Branch on presence (`if (payload.code === 'METADATA_CONFLICT')`),
+ never on absence meaning "success" or "unsupported version". This cost was
+ weighed against breaking every existing consumer, and the non-breaking side won.
+-**Stop substring-matching the sentence.**`error` is prose and no contract pins
+ its wording; the bracketed `[metadata_conflict]` tag some messages carry today
+ is a property of one producer, not a contract, and a separate card argues for
+ removing it. Code that reads the sentence to classify a failure should move to
+`code` (with `httpStatus` as the coarse fallback).

packages/cli/src/commands/cloud/login.ts

@@ -73,7 +73,7 @@ import * as readline from 'node:readline/promises';
 import{stdinasinput,stdoutasoutput}from'node:process';
 import{Command,Flags}from'@oclif/core';
 importtype{CliExitCode}from'../../utils/format.js';
-import{printHeader,printKV,printSuccess,printError,emitJson}from'../../utils/format.js';
+import{printHeader,printKV,printSuccess,printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{loginWithBrowser,loginWithPassword}from'../../utils/auth-flows.js';
 import{DEFAULT_CLOUD_URL,readCloudConfig,writeCloudConfig}from'../../utils/cloud-config.js';
 
@@ -246,7 +246,7 @@ export default class CloudLogin extends Command {
 // written (an expired code, a denied approval, a poll failure), so an
 // indented payload here would recreate a two-document stream on the
 // path a consumer is least able to recover from.
-awaitemitRecord({success: false,error: error.message});
+awaitemitRecord({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/cloud/logout.ts

@@ -8,7 +8,7 @@
 
 import{Command,Flags}from'@oclif/core';
 import{ObjectStackClient}from'@objectstack/client';
-import{printHeader,printSuccess,printError,emitJson}from'../../utils/format.js';
+import{printHeader,printSuccess,printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{deleteCloudConfig,tryReadCloudConfig}from'../../utils/cloud-config.js';
 
 exportdefaultclassCloudLogoutextendsCommand{
@@ -46,7 +46,7 @@ export default class CloudLogout extends Command {
 }
 }catch(error: any){
 if(flags.json){
-awaitemitJson({success: false,error: error.message});
+awaitemitJson({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/cloud/whoami.ts

@@ -7,7 +7,7 @@
  */
 
 import{Command,Flags}from'@oclif/core';
-import{printHeader,printKV,printSuccess,printError,emitJson,isExitSignal}from'../../utils/format.js';
+import{printHeader,printKV,printSuccess,printError,emitJson,isExitSignal,errorCodeFields}from'../../utils/format.js';
 import{tryReadCloudConfig}from'../../utils/cloud-config.js';
 
 exportdefaultclassCloudWhoamiextendsCommand{
@@ -72,7 +72,7 @@ export default class CloudWhoami extends Command {
 }catch(error: any){
 if(isExitSignal(error))throwerror;
 if(flags.json){
-awaitemitJson({success: false,error: error.message});
+awaitemitJson({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/compile.ts

@@ -39,6 +39,7 @@ import {
 printMetadataStats,
 emitJson,
 isExitSignal,
+errorCodeFields,
 }from'../utils/format.js';
 import{checkSpecVersionGap}from'../utils/spec-version.js';
 
@@ -720,7 +721,7 @@ export default class Compile extends Command {
 }catch(error: any){
 if(isExitSignal(error))throwerror;
 if(flags.json){
-awaitemitJson({success: false,error: error.message,warnings: warningsSoFar(),conversions: conversionNotices},0,{compact: true});
+awaitemitJson({success: false,error: error.message,...errorCodeFields(error),warnings: warningsSoFar(),conversions: conversionNotices},0,{compact: true});
 this.exit(1);
 }
 console.log('');

packages/cli/src/commands/data/create.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -100,6 +100,7 @@ export default class DataCreate extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/delete.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -83,6 +83,7 @@ export default class DataDelete extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/get.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,emitJson}from'../../utils/format.js';
+import{printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -74,6 +74,7 @@ export default class DataGet extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/query.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,emitJson}from'../../utils/format.js';
+import{printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -117,6 +117,7 @@ export default class DataQuery extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/update.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -104,6 +104,7 @@ export default class DataUpdate extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

.changeset/cli-json-error-envelope-adr-0112-code.md

@@ -0,0 +1,81 @@
+---
+"@objectstack/cli": minor
+---
+
+feat(cli): `--format json` failure envelopes carry the ADR-0112 `code` and `httpStatus` (#13347)
+
+Every machine-readable failure this CLI emits was built the same way — 48 sites
+under `packages/cli/src/commands/`:
+
+```ts
+awaitemitJson({ success: false, error: error.message });
+```
+
+The payload carried the human sentence and nothing else. The error reaching
+those `catch` blocks from `@objectstack/client` is not a bare `Error`: the SDK's
+`fetch` wrapper attaches `err.code` (the semantic ADR-0112 string, normalized to
+the same spelling across the flat `@objectstack/rest` envelope and the wrapped
+runtime-dispatcher one) and `err.httpStatus`. Both were discarded at the CLI
+boundary, so the one outcome a script most needs to branch on — *someone else
+edited it, re-read and retry* vs *you are not allowed* vs *the server is down* —
+was separable only by substring-matching an English sentence that no contract
+pins.
+
+A stale-pin refusal from `os meta delete --if-match` used to read:
+
+```json
+{
+"success": false,
+"error": "[metadata_conflict] view/race_probe has been modified since you loaded it. …"
+}
+```
+
+and now reads:
+
+```json
+{
+"success": false,
+"error": "[metadata_conflict] view/race_probe has been modified since you loaded it. …",
+"code": "METADATA_CONFLICT",
+"httpStatus": 409
+}
+```
+
+Maintainer ruling 2026-08-30 (option **A** of three):
+
+- The payload stays **FLAT**. Nesting into `{ error: { code, message, httpStatus } }`
+ was considered and declined as breaking.
+-`success` and `error` keep their current meaning **and spelling**.
+- The two keys are emitted **only when the thrown error carries them**, and are
+**absent** — not `undefined` — otherwise. No fallback code is invented for a
+ locally-thrown plain `Error`: this CLI's own input refusals get no code,
+ deliberately, because ADR-0112's ledger is the authority on who may mint one.
+
+One value-space note, stated so the declaration matches what ships: `code` is a
+**pass-through**, never minted or filtered. On wire failures it is the semantic
+ADR-0112 string the SDK attached; on local I/O failures inside the same `try`
+(`os validate` reading a `src/docs` that is a file, say) it is the Node errno
+(`ENOENT`, `ENOTDIR`, …). The two vocabularies are disjoint — errnos are
+`E`-prefixed OS names — so a consumer branching on ADR-0112 codes cannot
+false-match an errno, but not every emitted `code` is ledger-owned.
+
+Human (`table`) output is untouched.
+
+**Why `minor` and not `patch`.** Maintainer-set, and it overrides the obvious
+reading: this is a shape change to an **already-published error envelope**, and
+that makes it minor even though it is purely additive.
+
+**Migration.** Nothing is required — no key is removed, renamed or re-typed, and
+every payload this CLI emitted before is still emitted, byte-for-byte, minus the
+two new keys. Two things are worth knowing before you rely on the new ones:
+
+-**The envelope is polymorphic, by design.**`code` and `httpStatus` are absent
+ whenever the failure did not carry them, which a consumer cannot distinguish
+ from an older CLI. Branch on presence (`if (payload.code === 'METADATA_CONFLICT')`),
+ never on absence meaning "success" or "unsupported version". This cost was
+ weighed against breaking every existing consumer, and the non-breaking side won.
+-**Stop substring-matching the sentence.**`error` is prose and no contract pins
+ its wording; the bracketed `[metadata_conflict]` tag some messages carry today
+ is a property of one producer, not a contract, and a separate card argues for
+ removing it. Code that reads the sentence to classify a failure should move to
+`code` (with `httpStatus` as the coarse fallback).

packages/cli/src/commands/cloud/login.ts

@@ -73,7 +73,7 @@ import * as readline from 'node:readline/promises';
 import{stdinasinput,stdoutasoutput}from'node:process';
 import{Command,Flags}from'@oclif/core';
 importtype{CliExitCode}from'../../utils/format.js';
-import{printHeader,printKV,printSuccess,printError,emitJson}from'../../utils/format.js';
+import{printHeader,printKV,printSuccess,printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{loginWithBrowser,loginWithPassword}from'../../utils/auth-flows.js';
 import{DEFAULT_CLOUD_URL,readCloudConfig,writeCloudConfig}from'../../utils/cloud-config.js';
 
@@ -246,7 +246,7 @@ export default class CloudLogin extends Command {
 // written (an expired code, a denied approval, a poll failure), so an
 // indented payload here would recreate a two-document stream on the
 // path a consumer is least able to recover from.
-awaitemitRecord({success: false,error: error.message});
+awaitemitRecord({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/cloud/logout.ts

@@ -8,7 +8,7 @@
 
 import{Command,Flags}from'@oclif/core';
 import{ObjectStackClient}from'@objectstack/client';
-import{printHeader,printSuccess,printError,emitJson}from'../../utils/format.js';
+import{printHeader,printSuccess,printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{deleteCloudConfig,tryReadCloudConfig}from'../../utils/cloud-config.js';
 
 exportdefaultclassCloudLogoutextendsCommand{
@@ -46,7 +46,7 @@ export default class CloudLogout extends Command {
 }
 }catch(error: any){
 if(flags.json){
-awaitemitJson({success: false,error: error.message});
+awaitemitJson({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/cloud/whoami.ts

@@ -7,7 +7,7 @@
  */
 
 import{Command,Flags}from'@oclif/core';
-import{printHeader,printKV,printSuccess,printError,emitJson,isExitSignal}from'../../utils/format.js';
+import{printHeader,printKV,printSuccess,printError,emitJson,isExitSignal,errorCodeFields}from'../../utils/format.js';
 import{tryReadCloudConfig}from'../../utils/cloud-config.js';
 
 exportdefaultclassCloudWhoamiextendsCommand{
@@ -72,7 +72,7 @@ export default class CloudWhoami extends Command {
 }catch(error: any){
 if(isExitSignal(error))throwerror;
 if(flags.json){
-awaitemitJson({success: false,error: error.message});
+awaitemitJson({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/compile.ts

@@ -39,6 +39,7 @@ import {
 printMetadataStats,
 emitJson,
 isExitSignal,
+errorCodeFields,
 }from'../utils/format.js';
 import{checkSpecVersionGap}from'../utils/spec-version.js';
 
@@ -720,7 +721,7 @@ export default class Compile extends Command {
 }catch(error: any){
 if(isExitSignal(error))throwerror;
 if(flags.json){
-awaitemitJson({success: false,error: error.message,warnings: warningsSoFar(),conversions: conversionNotices},0,{compact: true});
+awaitemitJson({success: false,error: error.message,...errorCodeFields(error),warnings: warningsSoFar(),conversions: conversionNotices},0,{compact: true});
 this.exit(1);
 }
 console.log('');

packages/cli/src/commands/data/create.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -100,6 +100,7 @@ export default class DataCreate extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/delete.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -83,6 +83,7 @@ export default class DataDelete extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/get.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,emitJson}from'../../utils/format.js';
+import{printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -74,6 +74,7 @@ export default class DataGet extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/query.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,emitJson}from'../../utils/format.js';
+import{printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -117,6 +117,7 @@ export default class DataQuery extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/update.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -104,6 +104,7 @@ export default class DataUpdate extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

.changeset/cli-json-error-envelope-adr-0112-code.md

@@ -0,0 +1,81 @@
+---
+"@objectstack/cli": minor
+---
+
+feat(cli): `--format json` failure envelopes carry the ADR-0112 `code` and `httpStatus` (#13347)
+
+Every machine-readable failure this CLI emits was built the same way — 48 sites
+under `packages/cli/src/commands/`:
+
+```ts
+awaitemitJson({ success: false, error: error.message });
+```
+
+The payload carried the human sentence and nothing else. The error reaching
+those `catch` blocks from `@objectstack/client` is not a bare `Error`: the SDK's
+`fetch` wrapper attaches `err.code` (the semantic ADR-0112 string, normalized to
+the same spelling across the flat `@objectstack/rest` envelope and the wrapped
+runtime-dispatcher one) and `err.httpStatus`. Both were discarded at the CLI
+boundary, so the one outcome a script most needs to branch on — *someone else
+edited it, re-read and retry* vs *you are not allowed* vs *the server is down* —
+was separable only by substring-matching an English sentence that no contract
+pins.
+
+A stale-pin refusal from `os meta delete --if-match` used to read:
+
+```json
+{
+"success": false,
+"error": "[metadata_conflict] view/race_probe has been modified since you loaded it. …"
+}
+```
+
+and now reads:
+
+```json
+{
+"success": false,
+"error": "[metadata_conflict] view/race_probe has been modified since you loaded it. …",
+"code": "METADATA_CONFLICT",
+"httpStatus": 409
+}
+```
+
+Maintainer ruling 2026-08-30 (option **A** of three):
+
+- The payload stays **FLAT**. Nesting into `{ error: { code, message, httpStatus } }`
+ was considered and declined as breaking.
+-`success` and `error` keep their current meaning **and spelling**.
+- The two keys are emitted **only when the thrown error carries them**, and are
+**absent** — not `undefined` — otherwise. No fallback code is invented for a
+ locally-thrown plain `Error`: this CLI's own input refusals get no code,
+ deliberately, because ADR-0112's ledger is the authority on who may mint one.
+
+One value-space note, stated so the declaration matches what ships: `code` is a
+**pass-through**, never minted or filtered. On wire failures it is the semantic
+ADR-0112 string the SDK attached; on local I/O failures inside the same `try`
+(`os validate` reading a `src/docs` that is a file, say) it is the Node errno
+(`ENOENT`, `ENOTDIR`, …). The two vocabularies are disjoint — errnos are
+`E`-prefixed OS names — so a consumer branching on ADR-0112 codes cannot
+false-match an errno, but not every emitted `code` is ledger-owned.
+
+Human (`table`) output is untouched.
+
+**Why `minor` and not `patch`.** Maintainer-set, and it overrides the obvious
+reading: this is a shape change to an **already-published error envelope**, and
+that makes it minor even though it is purely additive.
+
+**Migration.** Nothing is required — no key is removed, renamed or re-typed, and
+every payload this CLI emitted before is still emitted, byte-for-byte, minus the
+two new keys. Two things are worth knowing before you rely on the new ones:
+
+-**The envelope is polymorphic, by design.**`code` and `httpStatus` are absent
+ whenever the failure did not carry them, which a consumer cannot distinguish
+ from an older CLI. Branch on presence (`if (payload.code === 'METADATA_CONFLICT')`),
+ never on absence meaning "success" or "unsupported version". This cost was
+ weighed against breaking every existing consumer, and the non-breaking side won.
+-**Stop substring-matching the sentence.**`error` is prose and no contract pins
+ its wording; the bracketed `[metadata_conflict]` tag some messages carry today
+ is a property of one producer, not a contract, and a separate card argues for
+ removing it. Code that reads the sentence to classify a failure should move to
+`code` (with `httpStatus` as the coarse fallback).

packages/cli/src/commands/cloud/login.ts

@@ -73,7 +73,7 @@ import * as readline from 'node:readline/promises';
 import{stdinasinput,stdoutasoutput}from'node:process';
 import{Command,Flags}from'@oclif/core';
 importtype{CliExitCode}from'../../utils/format.js';
-import{printHeader,printKV,printSuccess,printError,emitJson}from'../../utils/format.js';
+import{printHeader,printKV,printSuccess,printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{loginWithBrowser,loginWithPassword}from'../../utils/auth-flows.js';
 import{DEFAULT_CLOUD_URL,readCloudConfig,writeCloudConfig}from'../../utils/cloud-config.js';
 
@@ -246,7 +246,7 @@ export default class CloudLogin extends Command {
 // written (an expired code, a denied approval, a poll failure), so an
 // indented payload here would recreate a two-document stream on the
 // path a consumer is least able to recover from.
-awaitemitRecord({success: false,error: error.message});
+awaitemitRecord({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/cloud/logout.ts

@@ -8,7 +8,7 @@
 
 import{Command,Flags}from'@oclif/core';
 import{ObjectStackClient}from'@objectstack/client';
-import{printHeader,printSuccess,printError,emitJson}from'../../utils/format.js';
+import{printHeader,printSuccess,printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{deleteCloudConfig,tryReadCloudConfig}from'../../utils/cloud-config.js';
 
 exportdefaultclassCloudLogoutextendsCommand{
@@ -46,7 +46,7 @@ export default class CloudLogout extends Command {
 }
 }catch(error: any){
 if(flags.json){
-awaitemitJson({success: false,error: error.message});
+awaitemitJson({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/cloud/whoami.ts

@@ -7,7 +7,7 @@
  */
 
 import{Command,Flags}from'@oclif/core';
-import{printHeader,printKV,printSuccess,printError,emitJson,isExitSignal}from'../../utils/format.js';
+import{printHeader,printKV,printSuccess,printError,emitJson,isExitSignal,errorCodeFields}from'../../utils/format.js';
 import{tryReadCloudConfig}from'../../utils/cloud-config.js';
 
 exportdefaultclassCloudWhoamiextendsCommand{
@@ -72,7 +72,7 @@ export default class CloudWhoami extends Command {
 }catch(error: any){
 if(isExitSignal(error))throwerror;
 if(flags.json){
-awaitemitJson({success: false,error: error.message});
+awaitemitJson({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/compile.ts

@@ -39,6 +39,7 @@ import {
 printMetadataStats,
 emitJson,
 isExitSignal,
+errorCodeFields,
 }from'../utils/format.js';
 import{checkSpecVersionGap}from'../utils/spec-version.js';
 
@@ -720,7 +721,7 @@ export default class Compile extends Command {
 }catch(error: any){
 if(isExitSignal(error))throwerror;
 if(flags.json){
-awaitemitJson({success: false,error: error.message,warnings: warningsSoFar(),conversions: conversionNotices},0,{compact: true});
+awaitemitJson({success: false,error: error.message,...errorCodeFields(error),warnings: warningsSoFar(),conversions: conversionNotices},0,{compact: true});
 this.exit(1);
 }
 console.log('');

packages/cli/src/commands/data/create.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -100,6 +100,7 @@ export default class DataCreate extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/delete.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -83,6 +83,7 @@ export default class DataDelete extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/get.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,emitJson}from'../../utils/format.js';
+import{printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -74,6 +74,7 @@ export default class DataGet extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/query.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,emitJson}from'../../utils/format.js';
+import{printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -117,6 +117,7 @@ export default class DataQuery extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/update.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -104,6 +104,7 @@ export default class DataUpdate extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

.changeset/cli-json-error-envelope-adr-0112-code.md

@@ -0,0 +1,81 @@
+---
+"@objectstack/cli": minor
+---
+
+feat(cli): `--format json` failure envelopes carry the ADR-0112 `code` and `httpStatus` (#13347)
+
+Every machine-readable failure this CLI emits was built the same way — 48 sites
+under `packages/cli/src/commands/`:
+
+```ts
+awaitemitJson({ success: false, error: error.message });
+```
+
+The payload carried the human sentence and nothing else. The error reaching
+those `catch` blocks from `@objectstack/client` is not a bare `Error`: the SDK's
+`fetch` wrapper attaches `err.code` (the semantic ADR-0112 string, normalized to
+the same spelling across the flat `@objectstack/rest` envelope and the wrapped
+runtime-dispatcher one) and `err.httpStatus`. Both were discarded at the CLI
+boundary, so the one outcome a script most needs to branch on — *someone else
+edited it, re-read and retry* vs *you are not allowed* vs *the server is down* —
+was separable only by substring-matching an English sentence that no contract
+pins.
+
+A stale-pin refusal from `os meta delete --if-match` used to read:
+
+```json
+{
+"success": false,
+"error": "[metadata_conflict] view/race_probe has been modified since you loaded it. …"
+}
+```
+
+and now reads:
+
+```json
+{
+"success": false,
+"error": "[metadata_conflict] view/race_probe has been modified since you loaded it. …",
+"code": "METADATA_CONFLICT",
+"httpStatus": 409
+}
+```
+
+Maintainer ruling 2026-08-30 (option **A** of three):
+
+- The payload stays **FLAT**. Nesting into `{ error: { code, message, httpStatus } }`
+ was considered and declined as breaking.
+-`success` and `error` keep their current meaning **and spelling**.
+- The two keys are emitted **only when the thrown error carries them**, and are
+**absent** — not `undefined` — otherwise. No fallback code is invented for a
+ locally-thrown plain `Error`: this CLI's own input refusals get no code,
+ deliberately, because ADR-0112's ledger is the authority on who may mint one.
+
+One value-space note, stated so the declaration matches what ships: `code` is a
+**pass-through**, never minted or filtered. On wire failures it is the semantic
+ADR-0112 string the SDK attached; on local I/O failures inside the same `try`
+(`os validate` reading a `src/docs` that is a file, say) it is the Node errno
+(`ENOENT`, `ENOTDIR`, …). The two vocabularies are disjoint — errnos are
+`E`-prefixed OS names — so a consumer branching on ADR-0112 codes cannot
+false-match an errno, but not every emitted `code` is ledger-owned.
+
+Human (`table`) output is untouched.
+
+**Why `minor` and not `patch`.** Maintainer-set, and it overrides the obvious
+reading: this is a shape change to an **already-published error envelope**, and
+that makes it minor even though it is purely additive.
+
+**Migration.** Nothing is required — no key is removed, renamed or re-typed, and
+every payload this CLI emitted before is still emitted, byte-for-byte, minus the
+two new keys. Two things are worth knowing before you rely on the new ones:
+
+-**The envelope is polymorphic, by design.**`code` and `httpStatus` are absent
+ whenever the failure did not carry them, which a consumer cannot distinguish
+ from an older CLI. Branch on presence (`if (payload.code === 'METADATA_CONFLICT')`),
+ never on absence meaning "success" or "unsupported version". This cost was
+ weighed against breaking every existing consumer, and the non-breaking side won.
+-**Stop substring-matching the sentence.**`error` is prose and no contract pins
+ its wording; the bracketed `[metadata_conflict]` tag some messages carry today
+ is a property of one producer, not a contract, and a separate card argues for
+ removing it. Code that reads the sentence to classify a failure should move to
+`code` (with `httpStatus` as the coarse fallback).

packages/cli/src/commands/cloud/login.ts

@@ -73,7 +73,7 @@ import * as readline from 'node:readline/promises';
 import{stdinasinput,stdoutasoutput}from'node:process';
 import{Command,Flags}from'@oclif/core';
 importtype{CliExitCode}from'../../utils/format.js';
-import{printHeader,printKV,printSuccess,printError,emitJson}from'../../utils/format.js';
+import{printHeader,printKV,printSuccess,printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{loginWithBrowser,loginWithPassword}from'../../utils/auth-flows.js';
 import{DEFAULT_CLOUD_URL,readCloudConfig,writeCloudConfig}from'../../utils/cloud-config.js';
 
@@ -246,7 +246,7 @@ export default class CloudLogin extends Command {
 // written (an expired code, a denied approval, a poll failure), so an
 // indented payload here would recreate a two-document stream on the
 // path a consumer is least able to recover from.
-awaitemitRecord({success: false,error: error.message});
+awaitemitRecord({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/cloud/logout.ts

@@ -8,7 +8,7 @@
 
 import{Command,Flags}from'@oclif/core';
 import{ObjectStackClient}from'@objectstack/client';
-import{printHeader,printSuccess,printError,emitJson}from'../../utils/format.js';
+import{printHeader,printSuccess,printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{deleteCloudConfig,tryReadCloudConfig}from'../../utils/cloud-config.js';
 
 exportdefaultclassCloudLogoutextendsCommand{
@@ -46,7 +46,7 @@ export default class CloudLogout extends Command {
 }
 }catch(error: any){
 if(flags.json){
-awaitemitJson({success: false,error: error.message});
+awaitemitJson({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/cloud/whoami.ts

@@ -7,7 +7,7 @@
  */
 
 import{Command,Flags}from'@oclif/core';
-import{printHeader,printKV,printSuccess,printError,emitJson,isExitSignal}from'../../utils/format.js';
+import{printHeader,printKV,printSuccess,printError,emitJson,isExitSignal,errorCodeFields}from'../../utils/format.js';
 import{tryReadCloudConfig}from'../../utils/cloud-config.js';
 
 exportdefaultclassCloudWhoamiextendsCommand{
@@ -72,7 +72,7 @@ export default class CloudWhoami extends Command {
 }catch(error: any){
 if(isExitSignal(error))throwerror;
 if(flags.json){
-awaitemitJson({success: false,error: error.message});
+awaitemitJson({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/compile.ts

@@ -39,6 +39,7 @@ import {
 printMetadataStats,
 emitJson,
 isExitSignal,
+errorCodeFields,
 }from'../utils/format.js';
 import{checkSpecVersionGap}from'../utils/spec-version.js';
 
@@ -720,7 +721,7 @@ export default class Compile extends Command {
 }catch(error: any){
 if(isExitSignal(error))throwerror;
 if(flags.json){
-awaitemitJson({success: false,error: error.message,warnings: warningsSoFar(),conversions: conversionNotices},0,{compact: true});
+awaitemitJson({success: false,error: error.message,...errorCodeFields(error),warnings: warningsSoFar(),conversions: conversionNotices},0,{compact: true});
 this.exit(1);
 }
 console.log('');

packages/cli/src/commands/data/create.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -100,6 +100,7 @@ export default class DataCreate extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/delete.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -83,6 +83,7 @@ export default class DataDelete extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/get.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,emitJson}from'../../utils/format.js';
+import{printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -74,6 +74,7 @@ export default class DataGet extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/query.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,emitJson}from'../../utils/format.js';
+import{printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -117,6 +117,7 @@ export default class DataQuery extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/update.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -104,6 +104,7 @@ export default class DataUpdate extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

.changeset/cli-json-error-envelope-adr-0112-code.md

@@ -0,0 +1,81 @@
+---
+"@objectstack/cli": minor
+---
+
+feat(cli): `--format json` failure envelopes carry the ADR-0112 `code` and `httpStatus` (#13347)
+
+Every machine-readable failure this CLI emits was built the same way — 48 sites
+under `packages/cli/src/commands/`:
+
+```ts
+awaitemitJson({ success: false, error: error.message });
+```
+
+The payload carried the human sentence and nothing else. The error reaching
+those `catch` blocks from `@objectstack/client` is not a bare `Error`: the SDK's
+`fetch` wrapper attaches `err.code` (the semantic ADR-0112 string, normalized to
+the same spelling across the flat `@objectstack/rest` envelope and the wrapped
+runtime-dispatcher one) and `err.httpStatus`. Both were discarded at the CLI
+boundary, so the one outcome a script most needs to branch on — *someone else
+edited it, re-read and retry* vs *you are not allowed* vs *the server is down* —
+was separable only by substring-matching an English sentence that no contract
+pins.
+
+A stale-pin refusal from `os meta delete --if-match` used to read:
+
+```json
+{
+"success": false,
+"error": "[metadata_conflict] view/race_probe has been modified since you loaded it. …"
+}
+```
+
+and now reads:
+
+```json
+{
+"success": false,
+"error": "[metadata_conflict] view/race_probe has been modified since you loaded it. …",
+"code": "METADATA_CONFLICT",
+"httpStatus": 409
+}
+```
+
+Maintainer ruling 2026-08-30 (option **A** of three):
+
+- The payload stays **FLAT**. Nesting into `{ error: { code, message, httpStatus } }`
+ was considered and declined as breaking.
+-`success` and `error` keep their current meaning **and spelling**.
+- The two keys are emitted **only when the thrown error carries them**, and are
+**absent** — not `undefined` — otherwise. No fallback code is invented for a
+ locally-thrown plain `Error`: this CLI's own input refusals get no code,
+ deliberately, because ADR-0112's ledger is the authority on who may mint one.
+
+One value-space note, stated so the declaration matches what ships: `code` is a
+**pass-through**, never minted or filtered. On wire failures it is the semantic
+ADR-0112 string the SDK attached; on local I/O failures inside the same `try`
+(`os validate` reading a `src/docs` that is a file, say) it is the Node errno
+(`ENOENT`, `ENOTDIR`, …). The two vocabularies are disjoint — errnos are
+`E`-prefixed OS names — so a consumer branching on ADR-0112 codes cannot
+false-match an errno, but not every emitted `code` is ledger-owned.
+
+Human (`table`) output is untouched.
+
+**Why `minor` and not `patch`.** Maintainer-set, and it overrides the obvious
+reading: this is a shape change to an **already-published error envelope**, and
+that makes it minor even though it is purely additive.
+
+**Migration.** Nothing is required — no key is removed, renamed or re-typed, and
+every payload this CLI emitted before is still emitted, byte-for-byte, minus the
+two new keys. Two things are worth knowing before you rely on the new ones:
+
+-**The envelope is polymorphic, by design.**`code` and `httpStatus` are absent
+ whenever the failure did not carry them, which a consumer cannot distinguish
+ from an older CLI. Branch on presence (`if (payload.code === 'METADATA_CONFLICT')`),
+ never on absence meaning "success" or "unsupported version". This cost was
+ weighed against breaking every existing consumer, and the non-breaking side won.
+-**Stop substring-matching the sentence.**`error` is prose and no contract pins
+ its wording; the bracketed `[metadata_conflict]` tag some messages carry today
+ is a property of one producer, not a contract, and a separate card argues for
+ removing it. Code that reads the sentence to classify a failure should move to
+`code` (with `httpStatus` as the coarse fallback).

packages/cli/src/commands/cloud/login.ts

@@ -73,7 +73,7 @@ import * as readline from 'node:readline/promises';
 import{stdinasinput,stdoutasoutput}from'node:process';
 import{Command,Flags}from'@oclif/core';
 importtype{CliExitCode}from'../../utils/format.js';
-import{printHeader,printKV,printSuccess,printError,emitJson}from'../../utils/format.js';
+import{printHeader,printKV,printSuccess,printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{loginWithBrowser,loginWithPassword}from'../../utils/auth-flows.js';
 import{DEFAULT_CLOUD_URL,readCloudConfig,writeCloudConfig}from'../../utils/cloud-config.js';
 
@@ -246,7 +246,7 @@ export default class CloudLogin extends Command {
 // written (an expired code, a denied approval, a poll failure), so an
 // indented payload here would recreate a two-document stream on the
 // path a consumer is least able to recover from.
-awaitemitRecord({success: false,error: error.message});
+awaitemitRecord({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/cloud/logout.ts

@@ -8,7 +8,7 @@
 
 import{Command,Flags}from'@oclif/core';
 import{ObjectStackClient}from'@objectstack/client';
-import{printHeader,printSuccess,printError,emitJson}from'../../utils/format.js';
+import{printHeader,printSuccess,printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{deleteCloudConfig,tryReadCloudConfig}from'../../utils/cloud-config.js';
 
 exportdefaultclassCloudLogoutextendsCommand{
@@ -46,7 +46,7 @@ export default class CloudLogout extends Command {
 }
 }catch(error: any){
 if(flags.json){
-awaitemitJson({success: false,error: error.message});
+awaitemitJson({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/cloud/whoami.ts

@@ -7,7 +7,7 @@
  */
 
 import{Command,Flags}from'@oclif/core';
-import{printHeader,printKV,printSuccess,printError,emitJson,isExitSignal}from'../../utils/format.js';
+import{printHeader,printKV,printSuccess,printError,emitJson,isExitSignal,errorCodeFields}from'../../utils/format.js';
 import{tryReadCloudConfig}from'../../utils/cloud-config.js';
 
 exportdefaultclassCloudWhoamiextendsCommand{
@@ -72,7 +72,7 @@ export default class CloudWhoami extends Command {
 }catch(error: any){
 if(isExitSignal(error))throwerror;
 if(flags.json){
-awaitemitJson({success: false,error: error.message});
+awaitemitJson({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/compile.ts

@@ -39,6 +39,7 @@ import {
 printMetadataStats,
 emitJson,
 isExitSignal,
+errorCodeFields,
 }from'../utils/format.js';
 import{checkSpecVersionGap}from'../utils/spec-version.js';
 
@@ -720,7 +721,7 @@ export default class Compile extends Command {
 }catch(error: any){
 if(isExitSignal(error))throwerror;
 if(flags.json){
-awaitemitJson({success: false,error: error.message,warnings: warningsSoFar(),conversions: conversionNotices},0,{compact: true});
+awaitemitJson({success: false,error: error.message,...errorCodeFields(error),warnings: warningsSoFar(),conversions: conversionNotices},0,{compact: true});
 this.exit(1);
 }
 console.log('');

packages/cli/src/commands/data/create.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -100,6 +100,7 @@ export default class DataCreate extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/delete.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -83,6 +83,7 @@ export default class DataDelete extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/get.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,emitJson}from'../../utils/format.js';
+import{printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -74,6 +74,7 @@ export default class DataGet extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/query.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,emitJson}from'../../utils/format.js';
+import{printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -117,6 +117,7 @@ export default class DataQuery extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/update.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -104,6 +104,7 @@ export default class DataUpdate extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

.changeset/cli-json-error-envelope-adr-0112-code.md

@@ -0,0 +1,81 @@
+---
+"@objectstack/cli": minor
+---
+
+feat(cli): `--format json` failure envelopes carry the ADR-0112 `code` and `httpStatus` (#13347)
+
+Every machine-readable failure this CLI emits was built the same way — 48 sites
+under `packages/cli/src/commands/`:
+
+```ts
+awaitemitJson({ success: false, error: error.message });
+```
+
+The payload carried the human sentence and nothing else. The error reaching
+those `catch` blocks from `@objectstack/client` is not a bare `Error`: the SDK's
+`fetch` wrapper attaches `err.code` (the semantic ADR-0112 string, normalized to
+the same spelling across the flat `@objectstack/rest` envelope and the wrapped
+runtime-dispatcher one) and `err.httpStatus`. Both were discarded at the CLI
+boundary, so the one outcome a script most needs to branch on — *someone else
+edited it, re-read and retry* vs *you are not allowed* vs *the server is down* —
+was separable only by substring-matching an English sentence that no contract
+pins.
+
+A stale-pin refusal from `os meta delete --if-match` used to read:
+
+```json
+{
+"success": false,
+"error": "[metadata_conflict] view/race_probe has been modified since you loaded it. …"
+}
+```
+
+and now reads:
+
+```json
+{
+"success": false,
+"error": "[metadata_conflict] view/race_probe has been modified since you loaded it. …",
+"code": "METADATA_CONFLICT",
+"httpStatus": 409
+}
+```
+
+Maintainer ruling 2026-08-30 (option **A** of three):
+
+- The payload stays **FLAT**. Nesting into `{ error: { code, message, httpStatus } }`
+ was considered and declined as breaking.
+-`success` and `error` keep their current meaning **and spelling**.
+- The two keys are emitted **only when the thrown error carries them**, and are
+**absent** — not `undefined` — otherwise. No fallback code is invented for a
+ locally-thrown plain `Error`: this CLI's own input refusals get no code,
+ deliberately, because ADR-0112's ledger is the authority on who may mint one.
+
+One value-space note, stated so the declaration matches what ships: `code` is a
+**pass-through**, never minted or filtered. On wire failures it is the semantic
+ADR-0112 string the SDK attached; on local I/O failures inside the same `try`
+(`os validate` reading a `src/docs` that is a file, say) it is the Node errno
+(`ENOENT`, `ENOTDIR`, …). The two vocabularies are disjoint — errnos are
+`E`-prefixed OS names — so a consumer branching on ADR-0112 codes cannot
+false-match an errno, but not every emitted `code` is ledger-owned.
+
+Human (`table`) output is untouched.
+
+**Why `minor` and not `patch`.** Maintainer-set, and it overrides the obvious
+reading: this is a shape change to an **already-published error envelope**, and
+that makes it minor even though it is purely additive.
+
+**Migration.** Nothing is required — no key is removed, renamed or re-typed, and
+every payload this CLI emitted before is still emitted, byte-for-byte, minus the
+two new keys. Two things are worth knowing before you rely on the new ones:
+
+-**The envelope is polymorphic, by design.**`code` and `httpStatus` are absent
+ whenever the failure did not carry them, which a consumer cannot distinguish
+ from an older CLI. Branch on presence (`if (payload.code === 'METADATA_CONFLICT')`),
+ never on absence meaning "success" or "unsupported version". This cost was
+ weighed against breaking every existing consumer, and the non-breaking side won.
+-**Stop substring-matching the sentence.**`error` is prose and no contract pins
+ its wording; the bracketed `[metadata_conflict]` tag some messages carry today
+ is a property of one producer, not a contract, and a separate card argues for
+ removing it. Code that reads the sentence to classify a failure should move to
+`code` (with `httpStatus` as the coarse fallback).

packages/cli/src/commands/cloud/login.ts

@@ -73,7 +73,7 @@ import * as readline from 'node:readline/promises';
 import{stdinasinput,stdoutasoutput}from'node:process';
 import{Command,Flags}from'@oclif/core';
 importtype{CliExitCode}from'../../utils/format.js';
-import{printHeader,printKV,printSuccess,printError,emitJson}from'../../utils/format.js';
+import{printHeader,printKV,printSuccess,printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{loginWithBrowser,loginWithPassword}from'../../utils/auth-flows.js';
 import{DEFAULT_CLOUD_URL,readCloudConfig,writeCloudConfig}from'../../utils/cloud-config.js';
 
@@ -246,7 +246,7 @@ export default class CloudLogin extends Command {
 // written (an expired code, a denied approval, a poll failure), so an
 // indented payload here would recreate a two-document stream on the
 // path a consumer is least able to recover from.
-awaitemitRecord({success: false,error: error.message});
+awaitemitRecord({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/cloud/logout.ts

@@ -8,7 +8,7 @@
 
 import{Command,Flags}from'@oclif/core';
 import{ObjectStackClient}from'@objectstack/client';
-import{printHeader,printSuccess,printError,emitJson}from'../../utils/format.js';
+import{printHeader,printSuccess,printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{deleteCloudConfig,tryReadCloudConfig}from'../../utils/cloud-config.js';
 
 exportdefaultclassCloudLogoutextendsCommand{
@@ -46,7 +46,7 @@ export default class CloudLogout extends Command {
 }
 }catch(error: any){
 if(flags.json){
-awaitemitJson({success: false,error: error.message});
+awaitemitJson({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/cloud/whoami.ts

@@ -7,7 +7,7 @@
  */
 
 import{Command,Flags}from'@oclif/core';
-import{printHeader,printKV,printSuccess,printError,emitJson,isExitSignal}from'../../utils/format.js';
+import{printHeader,printKV,printSuccess,printError,emitJson,isExitSignal,errorCodeFields}from'../../utils/format.js';
 import{tryReadCloudConfig}from'../../utils/cloud-config.js';
 
 exportdefaultclassCloudWhoamiextendsCommand{
@@ -72,7 +72,7 @@ export default class CloudWhoami extends Command {
 }catch(error: any){
 if(isExitSignal(error))throwerror;
 if(flags.json){
-awaitemitJson({success: false,error: error.message});
+awaitemitJson({success: false,error: error.message, ...errorCodeFields(error)});
 this.exit(1);
 }
 printError(error.message||String(error));

packages/cli/src/commands/compile.ts

@@ -39,6 +39,7 @@ import {
 printMetadataStats,
 emitJson,
 isExitSignal,
+errorCodeFields,
 }from'../utils/format.js';
 import{checkSpecVersionGap}from'../utils/spec-version.js';
 
@@ -720,7 +721,7 @@ export default class Compile extends Command {
 }catch(error: any){
 if(isExitSignal(error))throwerror;
 if(flags.json){
-awaitemitJson({success: false,error: error.message,warnings: warningsSoFar(),conversions: conversionNotices},0,{compact: true});
+awaitemitJson({success: false,error: error.message,...errorCodeFields(error),warnings: warningsSoFar(),conversions: conversionNotices},0,{compact: true});
 this.exit(1);
 }
 console.log('');

packages/cli/src/commands/data/create.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -100,6 +100,7 @@ export default class DataCreate extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/delete.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -83,6 +83,7 @@ export default class DataDelete extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/get.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,emitJson}from'../../utils/format.js';
+import{printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -74,6 +74,7 @@ export default class DataGet extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/query.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,emitJson}from'../../utils/format.js';
+import{printError,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -117,6 +117,7 @@ export default class DataQuery extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }

packages/cli/src/commands/data/update.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import{Args,Command,Flags}from'@oclif/core';
-import{printError,printSuccess,emitJson}from'../../utils/format.js';
+import{printError,printSuccess,emitJson,errorCodeFields}from'../../utils/format.js';
 import{createApiClient,requireAuth}from'../../utils/api-client.js';
 import{formatOutput}from'../../utils/output-formatter.js';
 
@@ -104,6 +104,7 @@ export default class DataUpdate extends Command {
 awaitemitJson({
 success: false,
 error: error.message,
+ ...errorCodeFields(error),
 });
 this.exit(1);
 }