feat(spec,rest,objectql)!: a closed field-level error catalog, and Zod stops leaking onto the wire (#3977) (#4035)

* feat(spec,rest,objectql)!: a closed field-level error catalog, and Zod stops leaking onto the wire (#3977)

Settles what ADR-0112 D6 deferred, recorded as ADR-0114.

FieldErrorCode: 27 members, closed, and lowercase on purpose. A top-level code
names the condition the REQUEST hit; a field-level one names the CONSTRAINT the
value violated, and constraints are declared in the metadata's own snake_case, so
'max_length' the code and 'max_length: 50' the property are the same word. Survey
first, per the issue: nothing branches on these values — objectui's only consumer
uses code as a display fallback, and every framework match is a test — so the
casing was chosen on principle rather than migration cost.

FieldErrorSchema.code tightens from z.string() to the enum; objectql's
FieldValidationError (a hand-listed union — the shape that bit batch 2) and rest's
FieldCoerceError (a bare string) now reference the catalog so the three cannot
drift.

Zod stops reaching the wire. zodIssuesToFields maps via origin/format, which also
resolves the too_small ambiguity #3977 thought had no clean answer. A missing
property now reports 'required' instead of 'invalid_type' — Zod spells absent as a
type mismatch against undefined, and passing that through made a form mark a
MISSING input as the wrong TYPE. The two are indistinguishable on the issue alone
(v4 carries no input value), so the mapper takes the parsed input and walks the
path; without it, 'invalid_type' stands rather than a guess read out of Zod's
message text.

Two things the repo's own gates caught, both kept as evidence in comments: a real
route's test had pinned the invalid_type passthrough, and two doc examples put
top-level concepts (lock_conflict, invalid_field) in a field-code position — one of
which the catalog answers exactly (invalid_transition).

Not done, deliberately: EnhancedApiErrorSchema.fieldErrors keeps a name no
producer emits. Retiring an authorable key needs ADR-0104's tombstone plus
migration, so it gets its own change; the property carries a banner meanwhile.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MaSQn77TT5fUgHK9CesaDK

* docs(api): the client error-shape reference stops teaching a top-level code as a field code

Found by acting on the docs-drift advisory rather than skimming it: the
client-facing shape declared `code: string  // e.g. "INVALID_FORMAT"` on the
per-field entry — a SCREAMING top-level member in the one position that is
deliberately a different, lowercase vocabulary. An AI copying this example would
emit a code the schema now rejects.

Also flags that the declared array name (`fieldErrors`) is not the one producers
emit (`fields`), which is the mismatch ADR-0114 D4 records rather than fixes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MaSQn77TT5fUgHK9CesaDK

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/adr-0114-field-error-catalog.md

@@ -0,0 +1,53 @@
+---
+"@objectstack/spec": minor
+"@objectstack/rest": minor
+"@objectstack/objectql": minor
+---
+
+feat(spec,rest,objectql)!: a closed field-level error catalog, and Zod stops leaking onto the wire (#3977)
+
+Settles the vocabulary ADR-0112 D6 deferred, per [ADR-0114](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0114-field-level-error-code-catalog.md).
+
+**`FieldErrorCode` — a closed, lowercase catalog.** 27 members covering what the
+six emitters already emit. `FieldErrorSchema.code` tightens from `z.string()` to
+this enum, so a validation body's per-field codes are validated for the first time.
+`FieldValidationError.code` (objectql) and `FieldCoerceError.code` (rest) stop
+being a hand-listed union and a bare `string` respectively and reference the
+catalog, so the three cannot drift apart.
+
+Lowercase is deliberate, not an oversight against ADR-0112's SCREAMING_SNAKE: a
+top-level code names the condition the *request* hit, while a field-level code
+names the *constraint* the value violated — and constraints are declared in the
+metadata's own snake_case, so `max_length` the code and `max_length: 50` the
+property are the same word on purpose.
+
+**Zod issue codes no longer reach the wire (wire-visible).** Routes that validate
+with Zod passed its vocabulary straight through, so `fields[]` spoke a different
+language depending on which route served it, and `too_small` was ambiguous between
+a short string, a small number and a short array. `zodIssuesToFields` now maps
+using Zod's `origin`/`format`:
+
+| Was | Now |
+|:---|:---|
+| `too_small` | `min_length` / `min_value` / `min_items` |
+| `too_big` | `max_length` / `max_value` / `max_items` |
+| `invalid_format` | `invalid_email` / `invalid_url` / `invalid_format` |
+| `invalid_value` | `invalid_option` |
+| `unrecognized_keys` | `unknown_field` |
+| `invalid_union`, `invalid_element`, `invalid_key` | `invalid_shape` |
+
+**A missing required property now reports `required`, not `invalid_type`.** Zod
+spells "absent" as a type mismatch against `undefined`, so passing it through made
+a form mark a *missing* input as the wrong *type*. The two are indistinguishable on
+the issue alone, so the mapper takes the parsed input as an optional argument and
+walks the issue path; a caller that cannot supply it keeps `invalid_type` rather
+than guessing.
+
+**`unknown_param` → `unknown_field`.** `ActionParamIssue.code` references the
+catalog instead of its own literal union; the `param` key beside it already says
+what was addressed.
+
+**Not changed:** `EnhancedApiErrorSchema.fieldErrors` keeps its name even though
+every producer emits `fields`. Retiring an authorable key needs a tombstone plus a
+migration (ADR-0104's contract guard), so it lands on its own — the property now
+carries a banner saying which name the wire uses.

content/docs/api/error-catalog.mdx

@@ -443,15 +443,48 @@ interface EnhancedApiError {
 ```typescript
 interface FieldError {
   field: string;            // Field path (supports dot notation)
-  code: string;             // Field-level error code — a SEPARATE vocabulary from
-                            // error.code (`required`, `max_length`, `invalid_email`, …);
-                            // its own catalog is #3977 (ADR-0112 D6)
+  code: FieldErrorCode;     // Which CONSTRAINT the value violated — a closed,
+                            // lowercase catalog, separate from error.code (ADR-0114)
   message: string;          // Human-readable error for this field
   value?: unknown;          // The invalid value (if safe to include)
   constraint?: unknown;     // The constraint that was violated (e.g., max length)
 }
 ```
 
+### Field-level codes
+
+`FieldError.code` is its **own** closed vocabulary, and it is lowercase where
+`error.code` is SCREAMING. That is deliberate (ADR-0114): a top-level code names
+the condition the *request* hit, while a field-level code names the *constraint*
+the value violated — and constraints are declared in the metadata's own
+snake_case, so the code and the schema property are the same word.
+
+```
+{ required: true }   → code 'required'
+{ max_length: 50 }   → code 'max_length'
+{ min_value: 0 }     → code 'min_value'
+```
+
+| Group | Codes |
+|:---|:---|
+| Presence and shape | `required`, `invalid_type`, `invalid_shape`, `unknown_field` |
+| Per-type parse | `invalid_boolean`, `invalid_number`, `invalid_date`, `invalid_time`, `invalid_email`, `invalid_url`, `invalid_phone`, `invalid_json`, `invalid_format` |
+| Bounded ranges | `min_length`, `max_length`, `min_value`, `max_value`, `min_items`, `max_items` |
+| Closed sets and references | `invalid_option`, `invalid_value`, `reference_not_found`, `reference_ambiguous` |
+| Declarative rules | `rule_violation`, `json_schema_violation`, `invalid_initial_state`, `invalid_transition` |
+
+Branch on `code` to decide *how* to mark an input; show `message` to the user.
+Routes that parse with Zod map its issue codes into this catalog rather than
+passing them through, so `fields[]` speaks one vocabulary whichever route served
+it.
+
+<Callout type="warn">
+The declared envelope still calls this array `fieldErrors`, while every producer
+emits **`fields`**. Read `fields`. The rename is decided but deferred — retiring
+an authorable key needs a tombstone plus a migration, so it lands on its own
+(ADR-0114 D4).
+</Callout>
+
 ---
 
 ## Client-Side Error Handling

content/docs/api/error-handling-client.mdx

@@ -19,6 +19,8 @@ Every error response from ObjectStack follows this shape:
 
 {/* os:check */}
 ```typescript
+import type { FieldErrorCode } from '@objectstack/spec/api';
+
 interface ErrorResponse {
   success: false;        // Always false for error responses
   error: {
@@ -29,9 +31,15 @@ interface ErrorResponse {
     retryable?: boolean; // Whether the request can be retried
     retryStrategy?: string;
     retryAfter?: number; // Seconds to wait before retrying (rate limits)
+    // ⚠️ Declared as `fieldErrors`; every producer emits `fields`. Read `fields`.
+    // (ADR-0114 D4 — the rename needs a tombstone + migration, so it lands on
+    // its own.)
     fieldErrors?: Array<{
       field: string;     // Field path (supports dot notation)
-      code: string;      // Per-field error code (e.g. "INVALID_FORMAT")
+      // Which CONSTRAINT the value violated — a lowercase `FieldErrorCode`
+      // (`required`, `max_length`, `invalid_email`, …), NOT a top-level code.
+      // The two vocabularies are separate on purpose: see ADR-0114.
+      code: FieldErrorCode;
       message: string;   // Detail message
       value?: unknown;   // The invalid value that was provided
       constraint?: unknown;

content/docs/api/error-handling-server.mdx

@@ -48,7 +48,10 @@ class TaskAlreadyCompletedError extends AppError {
       'RESOURCE_CONFLICT',
       `Task ${taskId} is already completed and cannot be modified`,
       409,
-      [{ field: 'status', code: 'lock_conflict', message: 'Task is in terminal state' }],
+      // No per-field entry: a terminal-state conflict is a condition of the
+      // RECORD, not a constraint some value violated, and the top-level
+      // RESOURCE_CONFLICT already says so. `fields[]` is for "this value is
+      // wrong", which is why its codes name constraints.
     );
   }
 }
@@ -59,14 +62,16 @@ class InvalidStatusTransitionError extends AppError {
       'INVALID_FIELD',
       `Cannot transition from '${from}' to '${to}'`,
       400,
-      [{ field: 'status', code: 'invalid_field', message: `Invalid transition: ${from} → ${to}` }],
+      // `invalid_transition` — the catalog has a member for exactly this, and it
+      // is more useful to a form than a generic "this field is invalid".
+      [{ field: 'status', code: 'invalid_transition', message: `Invalid transition: ${from} → ${to}` }],
     );
   }
 }
 ```
 
 <Callout type="tip">
-**Error Codes:** The top-level `code` is SCREAMING_SNAKE (`StandardErrorCode` or a ledger-registered code). Per-field `code` values are a **separate, lowercase vocabulary** — the validators emit `required`, `max_length`, `invalid_email`, … and its catalog is being settled in [#3977](https://github.com/objectstack-ai/objectstack/issues/3977) (ADR-0112 D6). Use the `category` and `httpStatus` that match — `ErrorHttpStatusMap` in `@objectstack/spec/api` maps each category to its HTTP status.
+**Error Codes:** The top-level `code` is SCREAMING_SNAKE (`StandardErrorCode` or a ledger-registered code). Per-field `code` values are a **separate, lowercase catalog** — `FieldErrorCode`, closed, naming the constraint the value violated (`required`, `max_length`, `invalid_transition`, …). See the [Error Catalog](/docs/api/error-catalog#field-level-codes); the two vocabularies and why they differ are ADR-0114. Use the `category` and `httpStatus` that match — `ErrorHttpStatusMap` in `@objectstack/spec/api` maps each category to its HTTP status.
 </Callout>
 
 ---

content/docs/references/api/errors.mdx

@@ -30,8 +30,8 @@ Industry alignment: Google Cloud Errors, AWS Error Codes, Stripe API Errors
 ## TypeScript Usage
 
 ```typescript
-import { EnhancedApiError, ErrorCategory, ErrorResponse, FieldError, RetryStrategy, StandardErrorCode } from '@objectstack/spec/api';
-import type { EnhancedApiError, ErrorCategory, ErrorResponse, FieldError, RetryStrategy, StandardErrorCode } from '@objectstack/spec/api';
+import { EnhancedApiError, ErrorCategory, ErrorResponse, FieldError, FieldErrorCode, RetryStrategy, StandardErrorCode } from '@objectstack/spec/api';
+import type { EnhancedApiError, ErrorCategory, ErrorResponse, FieldError, FieldErrorCode, RetryStrategy, StandardErrorCode } from '@objectstack/spec/api';
 
 // Validate data
 const result = EnhancedApiError.parse(data);
@@ -53,7 +53,7 @@ const result = EnhancedApiError.parse(data);
 | **retryStrategy** | `Enum<'no_retry' \| 'retry_immediate' \| 'retry_backoff' \| 'retry_after'>` | optional | Recommended retry strategy |
 | **retryAfter** | `number` | optional | Seconds to wait before retrying |
 | **details** | `any` | optional | Additional error context |
-| **fieldErrors** | `{ field: string; code: string; message: string; value?: any; … }[]` | optional | Field-specific validation errors |
+| **fieldErrors** | `{ field: string; code: Enum<'required' \| 'invalid_type' \| 'invalid_shape' \| 'unknown_field' \| 'invalid_boolean' \| 'invalid_number' \| 'invalid_date' \| 'invalid_time' \| 'invalid_email' \| 'invalid_url' \| 'invalid_phone' \| 'invalid_json' \| 'invalid_format' \| 'min_length' \| 'max_length' \| 'min_value' \| 'max_value' \| 'min_items' \| 'max_items' \| 'invalid_option' \| 'invalid_value' \| 'reference_not_found' \| 'reference_ambiguous' \| 'rule_violation' \| 'json_schema_violation' \| 'invalid_initial_state' \| 'invalid_transition'>; message: string; value?: any; … }[]` | optional | Field-specific validation errors (wire name is `fields` — see ADR-0114 D4) |
 | **timestamp** | `string` | optional | When the error occurred |
 | **requestId** | `string` | optional | Request ID for tracking |
 | **traceId** | `string` | optional | Distributed trace ID |
@@ -100,12 +100,47 @@ const result = EnhancedApiError.parse(data);
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **field** | `string` | ✅ | Field path (supports dot notation) |
-| **code** | `string` | ✅ | Error code for this field (field-level vocabulary — see #3977) |
+| **code** | `Enum<'required' \| 'invalid_type' \| 'invalid_shape' \| 'unknown_field' \| 'invalid_boolean' \| 'invalid_number' \| 'invalid_date' \| 'invalid_time' \| 'invalid_email' \| 'invalid_url' \| 'invalid_phone' \| 'invalid_json' \| 'invalid_format' \| 'min_length' \| 'max_length' \| 'min_value' \| 'max_value' \| 'min_items' \| 'max_items' \| 'invalid_option' \| 'invalid_value' \| 'reference_not_found' \| 'reference_ambiguous' \| 'rule_violation' \| 'json_schema_violation' \| 'invalid_initial_state' \| 'invalid_transition'>` | ✅ | Which constraint the value violated (field-level catalog, ADR-0114) |
 | **message** | `string` | ✅ | Human-readable error message |
 | **value** | `any` | optional | The invalid value that was provided |
 | **constraint** | `any` | optional | The constraint that was violated (e.g., max length) |
 
 
+---
+
+## FieldErrorCode
+
+### Allowed Values
+
+* `required`
+* `invalid_type`
+* `invalid_shape`
+* `unknown_field`
+* `invalid_boolean`
+* `invalid_number`
+* `invalid_date`
+* `invalid_time`
+* `invalid_email`
+* `invalid_url`
+* `invalid_phone`
+* `invalid_json`
+* `invalid_format`
+* `min_length`
+* `max_length`
+* `min_value`
+* `max_value`
+* `min_items`
+* `max_items`
+* `invalid_option`
+* `invalid_value`
+* `reference_not_found`
+* `reference_ambiguous`
+* `rule_violation`
+* `json_schema_violation`
+* `invalid_initial_state`
+* `invalid_transition`
+
+
 ---
 
 ## RetryStrategy