feat(spec)!: EnhancedApiError.fieldErrors -> fields, tombstoned (ADR-0114 D4, #3977)

Completes the one thing #4035 decided but did not execute. The wire has always
carried `fields`; `fieldErrors` was declared and emitted by nobody, so a reader
keying on it was reading a field no server sent — ADR-0078's silently-inert
declaration, on the error envelope.

Tombstoned rather than deleted, because the schema is not .strict(): a plain
removal would let a producer still writing the old name parse clean and lose the
per-field detail, answering a validation failure that mentions no field.
retiredKey() turns that into a rejection carrying the rename.

Registered as a SEMANTIC chain entry, not a conversion, and the distinction is the
point. A conversion rewrites author metadata; this is a response envelope, and no
stack, example or template carries the key (checked across packages/, examples/,
templates/, apps/). A no-op conversion with an identity fixture would claim a
rewrite that does not exist. The analytics-query-request-* entries set the
precedent one step earlier in the same major: an HTTP-only surface with nothing
stored to rewrite is a semantic entry with a reason and an acceptance criterion —
which is what actually reaches spec-changes.json, the upgrade guide and the
spec_changes MCP tool.

Docs followed, and two examples were teaching the opposite of this ADR: the
server guide hand-rolled a Zod mapping with code: 'invalid_field' — a top-level
code in a field position — and the client guide's error class carried the dead
name. The server example now calls zodIssuesToFields, which is the mapping the
platform's own routes use.

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

Author: claude

.changeset/adr-0114-field-errors-rename.md

@@ -0,0 +1,30 @@
+---
+"@objectstack/spec": major
+---
+
+feat(spec)!: `EnhancedApiError.fieldErrors` → `fields`, tombstoned (ADR-0114 D4, #3977)
+
+Completes ADR-0114 D4, which the field-level catalog PR (#4035) decided but left
+unexecuted because retiring an authorable key needs its own sequence.
+
+**FROM → TO:** `EnhancedApiError.fieldErrors` → `EnhancedApiError.fields`. The array
+and its element shape are unchanged — only the property name.
+
+The wire has always carried `fields`: the validators, import coercion,
+`validation-failure.ts`, `@objectstack/client` and the console's field-error
+extractor all say `fields`. `fieldErrors` was declared and emitted by nobody, so
+anyone reading `error.fieldErrors` was reading a field no server sent — ADR-0078's
+silently-inert declaration, sitting on the error envelope.
+
+**The old key is tombstoned, not deleted.** `EnhancedApiErrorSchema` is not
+`.strict()`, so a plain removal would let a producer still writing `fieldErrors`
+parse clean and lose the per-field detail — a validation failure that mentions no
+field. Writing it now fails with the rename prescription instead
+(`retiredKey()`, ADR-0104).
+
+**Migration:** read `error.fields`. There is nothing to run: this is a response
+envelope, so no stack, example or template carries the key and `os migrate meta`
+has no source to rewrite. The change is recorded as a semantic chain entry
+(`enhanced-api-error-field-errors-renamed`) with its reason and acceptance
+criterion, which is what reaches the generated upgrade guide and the
+`spec_changes` MCP tool.

content/docs/api/error-catalog.mdx

@@ -54,7 +54,7 @@ ObjectStack uses a structured error system with **9 error categories** and **53
 
 ### `VALIDATION_ERROR`
 **Cause:** Generic validation failure — request body does not match expected schema.  
-**Fix:** Check the `fieldErrors` array for specific field-level issues.  
+**Fix:** Check the `fields` array for specific field-level issues.  
 **Retry:** `no_retry`
 
 ```json
@@ -64,7 +64,7 @@ ObjectStack uses a structured error system with **9 error categories** and **53
   "category": "validation",
   "httpStatus": 400,
   "retryable": false,
-  "fieldErrors": [
+  "fields": [
     { "field": "email", "message": "Invalid email format", "code": "invalid_format" }
   ]
 }
@@ -77,7 +77,7 @@ ObjectStack uses a structured error system with **9 error categories** and **53
 
 ### `MISSING_REQUIRED_FIELD`
 **Cause:** A required field was not provided in the request body.  
-**Fix:** Include the missing field. Check `fieldErrors` for the field name.  
+**Fix:** Include the missing field. Check `fields` for the field name.  
 **Retry:** `no_retry`
 
 ### `INVALID_FORMAT`
@@ -429,7 +429,7 @@ interface EnhancedApiError {
   retryStrategy?: RetryStrategy; // Recommended retry approach
   retryAfter?: number;           // Seconds to wait (for rate limits)
   details?: unknown;             // Additional error context
-  fieldErrors?: FieldError[];    // Field-specific validation errors
+  fields?: FieldError[];         // One entry per offending value
   timestamp?: string;            // ISO 8601 timestamp
   requestId?: string;            // Request tracking ID
   traceId?: string;              // Distributed trace ID
@@ -478,11 +478,12 @@ 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 type="info">
+The array is `fields` everywhere — producers, the SDK, the console, and now the
+declared envelope. It was declared as `fieldErrors` and emitted by nobody; that
+name is **tombstoned** (ADR-0114 D4), so writing it fails to parse with the rename
+rather than silently losing the array. If you read `error.fieldErrors`, you were
+reading a field no server sent — move to `error.fields`.
 </Callout>
 
 ---
@@ -498,8 +499,8 @@ directly; if your server populates those on the response body, read them from
 
 Two naming details matter here:
 
-- The per-field list is `apiError.fields`, matching the wire (`fields[]`), not
-  the spec contract's `fieldErrors`. Each entry is `{ field, code, message }`.
+- The per-field list is `apiError.fields`, matching the wire and (since ADR-0114
+  D4) the spec contract too. Each entry is `{ field, code, message }`.
   It is left **unset** when the server reported no per-field detail, so
   `if (apiError.fields)` tests "this failure is field-anchored".
 - `apiError.code` is always the semantic code as a **string**. The numeric HTTP
@@ -514,10 +515,9 @@ Two naming details matter here:
 ```typescript
 import type { EnhancedApiError, FieldError } from '@objectstack/spec/api';
 
-// The spec type names the per-field list `fieldErrors`; what the client
-// actually attaches at runtime is `fields` (the wire name). Widen the cast
-// until the two names converge.
-type ThrownApiError = EnhancedApiError & { fields?: FieldError[] };
+// The two names converged in ADR-0114 D4: the spec type and the client both say
+// `fields`, so no widening cast is needed any more.
+type ThrownApiError = EnhancedApiError;
 
 async function handleApiCall() {
   try {
@@ -528,9 +528,7 @@ async function handleApiCall() {
 
     switch (apiError.category) {
       case 'validation':
-        // Show field-level errors to the user. `fields` is what the client
-        // attaches (the wire name); the spec type calls the same idea
-        // `fieldErrors`.
+        // Show field-level errors to the user. One entry per offending value.
         apiError.fields?.forEach(fe => {
           showFieldError(fe.field, fe.message);
         });

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

@@ -31,10 +31,9 @@ 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<{
+    // One entry per offending value. Named `fields` on the wire AND in the spec
+    // contract since ADR-0114 D4; the old `fieldErrors` is tombstoned.
+    fields?: Array<{
       field: string;     // Field path (supports dot notation)
       // Which CONSTRAINT the value violated — a lowercase `FieldErrorCode`
       // (`required`, `max_length`, `invalid_email`, …), NOT a top-level code.
@@ -73,7 +72,7 @@ class ObjectStackError extends Error {
   code: string;
   status: number;
   retryAfter?: number;
-  fieldErrors: ErrorResponse['error']['fieldErrors'];
+  fields: ErrorResponse['error']['fields'];
   details: ErrorResponse['error']['details'];
   requestId?: string;
 
@@ -83,7 +82,7 @@ class ObjectStackError extends Error {
     this.code = response.error.code;
     this.status = response.error.httpStatus ?? 0;
     this.retryAfter = response.error.retryAfter;
-    this.fieldErrors = response.error.fieldErrors;
+    this.fields = response.error.fields;
     this.details = response.error.details;
     this.requestId = response.error.requestId ?? response.meta?.requestId;
   }
@@ -111,7 +110,7 @@ class ObjectStackError extends Error {
   /** Extract field-level errors as a map of field path → message */
   get fieldErrorMap(): Record<string, string> {
     const errors: Record<string, string> = {};
-    for (const detail of this.fieldErrors ?? []) {
+    for (const detail of this.fields ?? []) {
       if (detail.field) {
         errors[detail.field] = detail.message;
       }

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

@@ -8,7 +8,7 @@ description: Best practices for handling and throwing errors in ObjectStack plug
 This guide covers best practices for handling and throwing errors within ObjectStack plugins and server-side code — from creating custom errors with proper codes to transaction rollback and integration with `safeParsePretty()`.
 
 <Callout type="info">
-**Error Contract:** ObjectStack defines a standardized error envelope, `ErrorResponseSchema` (exported from `@objectstack/spec/api`). It wraps an `EnhancedApiError` with a machine-readable `code`, `httpStatus`, optional `category`, and `fieldErrors`. This is the spec's target contract for plugin/hook authors to throw against — but the kernel REST server (`@objectstack/rest`) that serves `/api/v1/data/*` does not auto-translate an arbitrary thrown error into this envelope today. It emits a flatter `{ error, code }` shape and only recognizes a small, fixed set of SCREAMING_SNAKE_CASE codes (`VALIDATION_FAILED`, `PERMISSION_DENIED`, `RECORD_NOT_FOUND`, `CONCURRENT_UPDATE`, `DELETE_RESTRICTED`, …). See the [API Overview](/docs/api#error-handling) and [Wire Format](/docs/api/wire-format#7-error-response-format) for both wire formats in use, and the [Error Catalog](/docs/api/error-catalog) for the full `StandardErrorCode` list.
+**Error Contract:** ObjectStack defines a standardized error envelope, `ErrorResponseSchema` (exported from `@objectstack/spec/api`). It wraps an `EnhancedApiError` with a machine-readable `code`, `httpStatus`, optional `category`, and `fields` (one entry per offending value). This is the spec's target contract for plugin/hook authors to throw against — but the kernel REST server (`@objectstack/rest`) that serves `/api/v1/data/*` does not auto-translate an arbitrary thrown error into this envelope today. It emits a flatter `{ error, code }` shape and only recognizes a small, fixed set of SCREAMING_SNAKE_CASE codes (`VALIDATION_FAILED`, `PERMISSION_DENIED`, `RECORD_NOT_FOUND`, `CONCURRENT_UPDATE`, `DELETE_RESTRICTED`, …). See the [API Overview](/docs/api#error-handling) and [Wire Format](/docs/api/wire-format#7-error-response-format) for both wire formats in use, and the [Error Catalog](/docs/api/error-catalog) for the full `StandardErrorCode` list.
 </Callout>
 
 ---
@@ -18,7 +18,7 @@ This guide covers best practices for handling and throwing errors within ObjectS
 ObjectStack does not ship a base error class — there is no `ObjectStackError`
 export. Instead, define a small server-side helper that extends the native
 `Error` and carries the fields from the `EnhancedApiError` schema (`code`,
-`httpStatus`, `fieldErrors`; `category` is optional). The valid `code` values are
+`httpStatus`, `fields`; `category` is optional). The valid `code` values are
 SCREAMING_SNAKE (ADR-0112): a `StandardErrorCode` member (e.g. `VALIDATION_ERROR`,
 `RESOURCE_CONFLICT`, `PERMISSION_DENIED`) or a code your package registered in
 `ERROR_CODE_LEDGER` (see `@objectstack/spec/api`).
@@ -27,15 +27,15 @@ SCREAMING_SNAKE (ADR-0112): a `StandardErrorCode` member (e.g. `VALIDATION_ERROR
 ```typescript
 import type { ErrorResponse, StandardErrorCode } from '@objectstack/spec/api';
 
-type FieldError = NonNullable<ErrorResponse['error']['fieldErrors']>[number];
+type FieldError = NonNullable<ErrorResponse['error']['fields']>[number];
 
 // Domain helper: a throwable error that maps cleanly onto EnhancedApiError.
 class AppError extends Error {
   constructor(
     public code: StandardErrorCode,
     message: string,
     public httpStatus: number,
-    public fieldErrors?: FieldError[],
+    public fields?: FieldError[],
   ) {
     super(message);
     this.name = 'AppError';
@@ -165,20 +165,25 @@ Format validation errors so the client can map them to specific form fields:
 ```typescript
 import { z } from 'zod';
 import { Hook } from '@objectstack/spec/data';
+import { zodIssuesToFields } from '@objectstack/rest';
 
 // Map a ZodError onto an AppError carrying field-level errors.
-function createValidationError(zodError: z.ZodError): AppError {
-  const fieldErrors = zodError.issues.map((issue) => ({
-    field: issue.path.join('.'),
-    message: issue.message,
-    code: 'invalid_field' as const,
-  }));
+//
+// Do NOT hand-roll this mapping, and do not reach for a top-level code here: a
+// per-field `code` is a `FieldErrorCode` naming the CONSTRAINT the value violated
+// (ADR-0114), and Zod's own issue codes are Zod's API rather than the wire's.
+// `zodIssuesToFields` does the translation the platform's own routes use —
+// `too_small` becomes `min_length` / `min_value` / `min_items` depending on what
+// was too small, and a MISSING property becomes `required` instead of the
+// `invalid_type` Zod reports for it.
+function createValidationError(zodError: z.ZodError, input?: unknown): AppError {
+  const fields = zodIssuesToFields(zodError.issues, input);
 
   return new AppError(
     'VALIDATION_ERROR',
-    `Validation failed: ${fieldErrors.length} error(s)`,
+    `Validation failed: ${fields.length} error(s)`,
     400,
-    fieldErrors,
+    fields,
   );
 }
 

content/docs/references/api/errors.mdx

@@ -53,7 +53,8 @@ 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: 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) |
+| **fields** | `{ 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 | One entry per offending value |
+| **fieldErrors** | `any` | optional | [REMOVED] `EnhancedApiError.fieldErrors` was renamed to `fields` in @objectstack/spec 17 (ADR-0114 D4, #3977) — the array is unchanged, only the property name. Every producer already emitted `fields`; `fieldErrors` was declared and never emitted, so a reader keying on it was reading a field no server sent. |
 | **timestamp** | `string` | optional | When the error occurred |
 | **requestId** | `string` | optional | Request ID for tracking |
 | **traceId** | `string` | optional | Distributed trace ID |