{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "ErrorOutput",
"description": "Serializable error envelope emitted as a single NDJSON line. The suggestion field is context-aware: for WORKSPACE_JAIL, the text varies based on whether --workspace was provided to the CLI.",
"type": "object",
"required": ["error", "code", "exit", "message", "error_class", "retryable"],
"properties": {
"error": {
"type": "boolean",
"const": true
},
"code": {
"type": "string",
"enum": [
"FILE_NOT_FOUND",
"INVALID_INPUT",
"PERMISSION_DENIED",
"DISK_FULL",
"QUOTA_EXCEEDED",
"CROSS_DEVICE",
"IO_ERROR",
"CONFIG_INVALID",
"STATE_DRIFT",
"CHECKSUM_VERIFY_FAILED",
"FILE_TOO_LARGE",
"WORKSPACE_JAIL",
"SYMLINK_BLOCKED",
"IMMUTABLE_FILE",
"BINARY_FILE",
"FIFO_DETECTED",
"DEVICE_FILE",
"NO_MATCHES",
"BROKEN_PIPE",
"INTERNAL_ERROR",
"LOCK_TIMEOUT",
"SYNTAX_ERROR_DETECTED",
"EXDEV_FALLBACK_DISABLED",
"COPY_BACK_BLAKE3_FAILED",
"ORPHAN_JOURNAL"
]
},
"exit": {
"type": "integer",
"description": "Suggested process exit code"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"path": {
"type": ["string", "null"],
"description": "Filesystem path related to the error, if applicable"
},
"error_class": {
"type": "string",
"enum": ["permanent", "transient", "conflict", "precondition_failed"]
},
"retryable": {
"type": "boolean",
"description": "Whether a retry may resolve this error"
},
"suggestion": {
"type": ["string", "null"],
"description": "Optional actionable suggestion for the caller. Context-aware for WORKSPACE_JAIL: when --workspace is provided the text says 'use a path inside the workspace (<root>)', when absent it says 'set --workspace <root> or export ATOMWRITE_WORKSPACE=<path>'. For IMMUTABLE_FILE it mentions 'chattr -i' on Unix or 'fsutil' on Windows. For BINARY_FILE it recommends 'read --stat'. Only BROKEN_PIPE has no suggestion because SIGPIPE is not actionable."
},
"workspace": {
"type": ["string", "null"],
"description": "Workspace root used for jail validation. Appears on WORKSPACE_JAIL errors (and may appear on any error in future releases) to help the caller diagnose path resolution."
},
"failed_pair_index": {
"type": ["integer", "null"],
"minimum": 1,
"description": "1-based index of the failed --old/--new pair. Present only on multi-pair edit failures (G117, v0.1.15+)."
},
"pairs_total": {
"type": ["integer", "null"],
"minimum": 1,
"description": "Total number of --old/--new pairs in the invocation. Present only on multi-pair edit failures (G117, v0.1.15+)."
},
"pair_results": {
"type": ["array", "null"],
"description": "Per-pair diagnostics up to and including the failed pair. Pairs after the failure were never attempted and are absent (all-or-nothing default). Present only on multi-pair edit failures (G117, v0.1.15+).",
"items": {
"$ref": "#/definitions/PairResult"
}
}
},
"definitions": {
"PairResult": {
"type": "object",
"required": ["index", "matched"],
"properties": {
"index": {
"type": "integer",
"minimum": 1,
"description": "1-based position of the pair in the --old/--new invocation order"
},
"matched": {
"type": "boolean",
"description": "Whether the pair matched and was applied to the content"
},
"strategy": {
"type": "string",
"description": "Matching strategy that succeeded (e.g. exact, whitespace_normalized)"
},
"similarity": {
"type": "number",
"minimum": 0.0,
"maximum": 1.0,
"description": "Similarity score of the fuzzy match (block-anchor and context-aware only)"
}
}
}
}
}