feat(spec,core,runtime,docs)!: ADR-0112 batch 1 — one error-code vocabulary, SCREAMING_SNAKE, schema-enforced (#3841)

.changeset/adr-0112-batch-1-screaming-codes.md

@@ -0,0 +1,35 @@
+---
+"@objectstack/spec": minor
+"@objectstack/core": minor
+"@objectstack/runtime": minor
+---
+
+feat(spec,core,runtime)!: ADR-0112 batch 1 — one error-code vocabulary, SCREAMING_SNAKE, schema-enforced (#3841)
+
+Settles #3841 per ADR-0112: the top-level `error.code` vocabulary is
+SCREAMING_SNAKE, in two tiers.
+
+- **`StandardErrorCode` members renamed in place** (`validation_error` →
+  `VALIDATION_ERROR`, all 53). Breaking for importers that branch on the old
+  lowercase members; the type name and member *meanings* are unchanged.
+- **New `ERROR_CODE_LEDGER`** (`@objectstack/spec/api`): service-specific codes
+  (`AUTH_REQUIRED`, `VALIDATION_FAILED`, `ATTACHMENT_DOWNLOAD_DENIED`, …) are
+  registered per owning package. `ErrorCode` = standard ∪ registered.
+- **`ApiErrorSchema.code` is now `ErrorCode`**, not `z.string()` — an
+  unregistered code fails parse, so the envelope conformance suites assert
+  values, not just shape.
+- **`FieldErrorSchema.code` widened to `z.string()`** (ADR-0112 D6): field-level
+  codes are a separate vocabulary the enum never described; #3977 owns its real
+  catalog.
+- **Derived codes changed case on the wire**: `standardErrorCodeForHttpStatus`
+  now yields SCREAMING members (`permission_denied` → `PERMISSION_DENIED`,
+  `method_not_allowed` → `METHOD_NOT_ALLOWED`, …) — this map was #3842's
+  designated one-file sweep point for exactly this decision.
+- **`ANONYMOUS_DENY_CODE` is `'UNAUTHENTICATED'`** (was `'unauthenticated'`) —
+  the promoted code on anonymous-denied requests and the REST `enforceAuth`
+  body change spelling with it.
+
+`error-catalog.mdx` and the error-handling guides are rewritten to the single
+vocabulary; a spec test now locks the catalog page's headings to the enum so
+they cannot drift apart again. Remaining lowercase emitters (cloud-connection,
+plugin-auth envelope codes, metadata-protocol, …) are the batch-2 sweep.

content/docs/api/client-sdk.mdx

@@ -511,7 +511,7 @@ All errors follow a standardized format:
 try {
   await client.data.create('todo_task', { subject: '' });
 } catch (error) {
-  console.error(error.code);       // 'validation_error'
+  console.error(error.code);       // 'VALIDATION_ERROR'
   console.error(error.category);   // 'validation'
   console.error(error.httpStatus); // 400
   console.error(error.retryable);  // false
@@ -554,15 +554,15 @@ field-anchored".
 
 | Code | HTTP | Category | Retryable | Description |
 |:-----|:-----|:---------|:----------|:------------|
-| `validation_error` | 400 | validation | No | Input validation failed |
-| `invalid_query` | 400 | validation | No | Malformed query expression |
-| `unauthenticated` | 401 | authentication | No | Authentication required |
-| `permission_denied` | 403 | authorization | No | Insufficient permissions |
-| `resource_not_found` | 404 | not_found | No | Resource does not exist |
-| `rate_limit_exceeded` | 429 | rate_limit | Yes | Too many requests |
-| `internal_error` | 500 | server | Yes | Unexpected server error |
-| `service_unavailable` | 503 | server | Yes | Service temporarily unavailable |
-| `not_implemented` | 501 | server | No | Service not installed (plugin missing) |
+| `VALIDATION_ERROR` | 400 | validation | No | Input validation failed |
+| `INVALID_QUERY` | 400 | validation | No | Malformed query expression |
+| `UNAUTHENTICATED` | 401 | authentication | No | Authentication required |
+| `PERMISSION_DENIED` | 403 | authorization | No | Insufficient permissions |
+| `RESOURCE_NOT_FOUND` | 404 | not_found | No | Resource does not exist |
+| `RATE_LIMIT_EXCEEDED` | 429 | rate_limit | Yes | Too many requests |
+| `INTERNAL_ERROR` | 500 | server | Yes | Unexpected server error |
+| `SERVICE_UNAVAILABLE` | 503 | server | Yes | Service temporarily unavailable |
+| `NOT_IMPLEMENTED` | 501 | server | No | Service not installed (plugin missing) |
 
 ---