fix(rest,service-settings,service-datasource): adopt ADR-0112 codes and refresh the console pin (#3843)

Merging main brought in ADR-0112 batch 1 (#3841 (#3988)) and #3842, both of
which landed while this PR was in review. Two of this PR's stated decisions were
premised on #3841 being UNDECIDED, so they no longer hold.

`ApiErrorSchema.code` is now the closed `ErrorCode` union, not `z.string()`, so
the nine lowercase codes this PR deliberately carried over failed schema parse —
which failed its own conformance suites (6 in service-datasource, 1 in
service-settings). Re-spelled per ADR-0112, with generic conditions going to the
STANDARD catalog rather than becoming registered synonyms of it, which is what
the ledger asks for:

  datasource_admin_unavailable  → SERVICE_UNAVAILABLE      (standard)
  external_service_unavailable  → SERVICE_UNAVAILABLE      (standard)
  not_found / PACKAGE_NOT_FOUND → RESOURCE_NOT_FOUND       (standard)
  PUBLISH_FIELDS_MISSING        → MISSING_REQUIRED_FIELD   (standard)
  INTERNAL                      → INTERNAL_ERROR           (standard)
  datasource_admin_error        → DATASOURCE_ADMIN_ERROR   (registered)
  external_import_error         → EXTERNAL_IMPORT_ERROR    (registered)
  PUBLISH_MANIFEST_INVALID      → PACKAGE_MANIFEST_INVALID (registered)
  PUBLISH_FAILED                → PACKAGE_PUBLISH_FAILED   (registered)
  PACKAGE_DELETE_PARTIAL / PACKAGE_DELETE_FAILED / SETTINGS_ACTION_FAILED

Which service is unavailable is carried by `message` — the ledger explicitly
asks generic conditions to reuse the catalog instead of registering a per-service
503. The seven registered codes go into ERROR_CODE_LEDGER under their owning
packages, including a new @objectstack/service-datasource entry.

Also bumps .objectui-sha a136322 → e651c93 now that objectui#2972 has merged, so
the bundled Setup console carries the envelope tolerance this change needs. The
pin only moves two commits because main had already refreshed it to a136322 —
an earlier attempt from this branch's stale base would have swept in eleven
unrelated frontend commits including two breaking ones.

The route-envelope guard, the conformance suites and their doc comments are
updated to match. Guard: 8 modules, 5 conformant / 2 ratcheted / 1 exempt.

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

Author: claude

.changeset/console-e651c936870e.md

@@ -0,0 +1,10 @@
+---
+"@objectstack/console": patch
+---
+
+Console (objectui) refreshed to `e651c936870e`. Frontend changes in this range:
+
+- fix(app-shell): unwrap the declared response envelope on the datasource page and the api-action runner (objectstack#3843) (#2972)
+- fix(actions): read objectstack#3962's single-wrapped /actions responses (#2971)
+
+objectui range: `a136322f8723...e651c936870e`

.changeset/route-envelope-four-more-modules.md

@@ -54,16 +54,28 @@ answered a bare `{ success: false }` and a bare
 `PACKAGE_DELETE_PARTIAL`, with the per-item `failed` / `cleanups` arrays under
 `error.details`.
 
-**Codes: carried over, not renamed.** `admin-routes.ts` and
-`external-datasource-routes.ts` keep their existing lowercase snake codes
-(`datasource_admin_unavailable`, `external_service_unavailable`, `not_found`, …)
-even though they sit beside SCREAMING_SNAKE in the already-converted siblings.
-Which vocabulary wins is #3841's call — a decision about ~240 codes repo-wide —
-and re-spelling nine of them here would pick that dialect by accident. Only
-`package-routes.ts` needed *minted* codes, because its `error` strings were human
-messages with no code to carry; those follow the SCREAMING_SNAKE the two
-converted siblings emit and #3841 will re-spell them with everything else. This
-is the envelope only, the same split #3687 / #3837 made deliberately.
+**Codes follow ADR-0112.** #3841 settled the vocabulary while this was in review:
+`error.code` is SCREAMING_SNAKE and `ApiErrorSchema.code` is now the closed
+`ErrorCode` union, so an unregistered code fails schema parse. Generic conditions
+reuse the STANDARD catalog rather than becoming registered synonyms of it, per the
+ledger's own guidance:
+
+```
+datasource_admin_unavailable  → SERVICE_UNAVAILABLE      (standard)
+external_service_unavailable  → SERVICE_UNAVAILABLE      (standard)
+not_found / PACKAGE_NOT_FOUND → RESOURCE_NOT_FOUND       (standard)
+PUBLISH_FIELDS_MISSING        → MISSING_REQUIRED_FIELD   (standard)
+INTERNAL                      → INTERNAL_ERROR           (standard)
+datasource_admin_error        → DATASOURCE_ADMIN_ERROR   (registered)
+external_import_error         → EXTERNAL_IMPORT_ERROR    (registered)
+PUBLISH_MANIFEST_INVALID      → PACKAGE_MANIFEST_INVALID (registered)
+PUBLISH_FAILED                → PACKAGE_PUBLISH_FAILED   (registered)
+PACKAGE_DELETE_PARTIAL / PACKAGE_DELETE_FAILED / SETTINGS_ACTION_FAILED (registered)
+```
+
+Which service is unavailable is carried by `message`. The seven registered codes are
+added to `ERROR_CODE_LEDGER` under their owning packages — including a new
+`@objectstack/service-datasource` entry.
 
 **`POST /external/validate` keeps its `ok`.** Unlike the `{ ok: true, key }`
 #3689 retired from storage — a private second word for `success` — this `ok` is a

.objectui-sha

@@ -1 +1 @@
-a136322f872314a74462ac7e7142f424e1124400
+e651c936870e26ef0c15252baad479d293fb3cf3

packages/rest/src/external-datasource-envelope.conformance.test.ts

@@ -8,7 +8,7 @@
  * arms, no `success` flag on any body, and — on `POST /validate` — its own
  * private success word:
  *
- *     res.status(503).json({ error: 'external_service_unavailable' });
+ *     res.status(503).json({ error: 'SERVICE_UNAVAILABLE' });
  *     res.json({ ok: results.every((r: any) => r.ok), results });
  *
  * The `ok` is the interesting one, because it is NOT the `ok` #3689 retired from
@@ -181,13 +181,13 @@ describe('external-datasource envelope (#3843) — error bodies', () => {
     {
       name: 'federation is not wired into the host',
       status: 503,
-      code: 'external_service_unavailable',
+      code: 'SERVICE_UNAVAILABLE',
       run: () => drive(mount(undefined), 'GET', `${EXT}/tables`),
     },
     {
       name: 'an import the service refuses',
       status: 400,
-      code: 'external_import_error',
+      code: 'EXTERNAL_IMPORT_ERROR',
       run: () => drive(
         mount({ importObject: async () => { throw new Error('metadata store is read-only'); } }),
         'POST',
@@ -239,7 +239,7 @@ describe('external-datasource envelope (#3843) — error bodies', () => {
       const { status, body } = await drive(routes, method, path, req);
       expect(status, `${method} ${path}`).toBe(503);
       expect(body.success, `${method} ${path}`).toBe(false);
-      expect(body.error.code, `${method} ${path}`).toBe('external_service_unavailable');
+      expect(body.error.code, `${method} ${path}`).toBe('SERVICE_UNAVAILABLE');
     }
   });
 });

packages/rest/src/external-datasource-routes.ts

@@ -8,7 +8,7 @@ import type { IHttpServer } from '@objectstack/spec/contracts';
  *
  * Mounted under `/api/v1/datasources/:name/external/*` and served by the
  * `external-datasource` service. Every route degrades gracefully
- * (`503 external_service_unavailable`) when federation is not wired into the
+ * (`503 SERVICE_UNAVAILABLE`) when federation is not wired into the
  * host, so the routes are safe to register unconditionally.
  *
  *   GET  /datasources/:name/external/tables             → listRemoteTables
@@ -47,9 +47,14 @@ export function registerExternalDatasourceRoutes(
    *
    * Before #3843 this module emitted the pre-#3675 `{ error: '<string>' }`,
    * with the message a SIBLING of `error` on the import path — so a caller
-   * reading `body.error.message` got `undefined`. The `code` strings are carried
-   * over unchanged; picking a vocabulary is #3841's call (see the same note on
-   * `admin-routes.ts`).
+   * reading `body.error.message` got `undefined`.
+   *
+   * Codes follow ADR-0112 (#3841, settled while this was in review):
+   * `external_service_unavailable` → the standard `SERVICE_UNAVAILABLE`, since the
+   * ledger asks generic conditions to reuse the catalog rather than register a
+   * per-service synonym; `external_import_error` → `EXTERNAL_IMPORT_ERROR`,
+   * registered under this package because a refused federated import is specific
+   * to it.
    */
   const sendError = (res: any, status: number, code: string, message: string) =>
     res.status(status).json({ success: false, error: { code, message } });
@@ -68,7 +73,7 @@ export function registerExternalDatasourceRoutes(
     res.status(status).json({ success: true, data });
 
   const unavailable = (res: any) =>
-    sendError(res, 503, 'external_service_unavailable', 'The external-datasource service is not available.');
+    sendError(res, 503, 'SERVICE_UNAVAILABLE', 'The external-datasource service is not available.');
 
   // List remote tables (optionally filtered by ?schema=).
   server.get(`${ext}/tables`, async (req: any, res: any) => {
@@ -109,7 +114,7 @@ export function registerExternalDatasourceRoutes(
       sendError(
         res,
         400,
-        'external_import_error',
+        'EXTERNAL_IMPORT_ERROR',
         err instanceof Error ? err.message : String(err),
       );
     }

packages/rest/src/package-envelope.conformance.test.ts

@@ -202,19 +202,19 @@ describe('packages envelope (#3843) — error bodies', () => {
     {
       name: 'publish without manifest/metadata',
       status: 400,
-      code: 'PUBLISH_FIELDS_MISSING',
+      code: 'MISSING_REQUIRED_FIELD',
       run: () => drive(mount({}), 'POST', `${PKGS}/publish`, { body: {} }),
     },
     {
       name: 'publish with a manifest missing id/version',
       status: 400,
-      code: 'PUBLISH_MANIFEST_INVALID',
+      code: 'PACKAGE_MANIFEST_INVALID',
       run: () => drive(mount({}), 'POST', `${PKGS}/publish`, { body: { manifest: {}, metadata: {} } }),
     },
     {
       name: 'a publish the service refuses',
       status: 400,
-      code: 'PUBLISH_FAILED',
+      code: 'PACKAGE_PUBLISH_FAILED',
       run: () => drive(
         mount({ publish: async () => ({ success: false, error: 'version already published' }) }),
         'POST',
@@ -225,7 +225,7 @@ describe('packages envelope (#3843) — error bodies', () => {
     {
       name: 'reading a package that does not exist',
       status: 404,
-      code: 'PACKAGE_NOT_FOUND',
+      code: 'RESOURCE_NOT_FOUND',
       run: () => drive(
         mount({ get: async () => undefined }),
         'GET',
@@ -272,7 +272,7 @@ describe('packages envelope (#3843) — error bodies', () => {
       // unreachable that way (pinned below). `GET /:id` has no inner catch.
       name: 'an unexpected throw from the package service',
       status: 500,
-      code: 'INTERNAL',
+      code: 'INTERNAL_ERROR',
       run: () => drive(
         mount({ get: async () => { throw new Error('db down'); } }),
         'GET',

packages/rest/src/package-routes.ts

@@ -61,13 +61,16 @@ export interface PackageRoutesOptions {
  * Two of them carried no error at all, only a bare `{ success: false }`, so a
  * caller was told it failed and never told why.
  *
- * Because there were no codes here to preserve, these had to be MINTED — unlike
- * `admin-routes.ts` / `external-datasource-routes.ts`, whose existing codes are
- * carried over untouched so #3841 can pick a vocabulary for the whole repo at
- * once. The dialect chosen is the SCREAMING_SNAKE that the two already-converted
- * siblings (`storage-routes.ts`, `settings-routes.ts`) emit, on the grounds that
- * it adds no new information to #3841's decision; expect that sweep to re-spell
- * them along with everything else.
+ * Because there were no codes here to preserve, these had to be MINTED. They
+ * follow ADR-0112 (#3841, settled while this was in review): SCREAMING_SNAKE, and
+ * registered in `ERROR_CODE_LEDGER` under `@objectstack/rest` — an unregistered
+ * code fails `ApiErrorSchema` parse, which fails the conformance suite.
+ *
+ * Generic conditions reuse the STANDARD catalog rather than becoming registered
+ * synonyms of it: a missing request field is `MISSING_REQUIRED_FIELD`, an absent
+ * package is `RESOURCE_NOT_FOUND`, an unexpected throw is `INTERNAL_ERROR`. Only
+ * the package-specific outcomes are registered — `PACKAGE_MANIFEST_INVALID`,
+ * `PACKAGE_PUBLISH_FAILED`, `PACKAGE_DELETE_PARTIAL`, `PACKAGE_DELETE_FAILED`.
  */
 function sendError(res: any, status: number, code: string, message: string, details?: unknown) {
   res.status(status).json({
@@ -104,12 +107,12 @@ export function registerPackageRoutes(
       const { manifest, metadata } = req.body || {};
 
       if (!manifest || !metadata) {
-        sendError(res, 400, 'PUBLISH_FIELDS_MISSING', 'Missing required fields: manifest, metadata');
+        sendError(res, 400, 'MISSING_REQUIRED_FIELD', 'Missing required fields: manifest, metadata');
         return;
       }
 
       if (!manifest.id || !manifest.version) {
-        sendError(res, 400, 'PUBLISH_MANIFEST_INVALID', 'Invalid manifest: id and version are required');
+        sendError(res, 400, 'PACKAGE_MANIFEST_INVALID', 'Invalid manifest: id and version are required');
         return;
       }
 
@@ -126,9 +129,9 @@ export function registerPackageRoutes(
         return;
       }
 
-      sendError(res, 400, 'PUBLISH_FAILED', result.error ?? `Failed to publish ${manifest.id}.`);
+      sendError(res, 400, 'PACKAGE_PUBLISH_FAILED', result.error ?? `Failed to publish ${manifest.id}.`);
     } catch (error) {
-      sendError(res, 500, 'INTERNAL', (error as Error).message);
+      sendError(res, 500, 'INTERNAL_ERROR', (error as Error).message);
     }
   });
 
@@ -181,7 +184,7 @@ export function registerPackageRoutes(
       const packages = Array.from(packagesMap.values());
       sendOk(res, { packages, total: packages.length });
     } catch (error) {
-      sendError(res, 500, 'INTERNAL', (error as Error).message);
+      sendError(res, 500, 'INTERNAL_ERROR', (error as Error).message);
     }
   });
 
@@ -214,9 +217,9 @@ export function registerPackageRoutes(
         }
       }
 
-      sendError(res, 404, 'PACKAGE_NOT_FOUND', `Package "${packageId}" was not found.`);
+      sendError(res, 404, 'RESOURCE_NOT_FOUND', `Package "${packageId}" was not found.`);
     } catch (error) {
-      sendError(res, 500, 'INTERNAL', (error as Error).message);
+      sendError(res, 500, 'INTERNAL_ERROR', (error as Error).message);
     }
   });
 
@@ -276,7 +279,7 @@ export function registerPackageRoutes(
         `Failed to delete ${packageId}${version ? `@${version}` : ''}.`,
       );
     } catch (error) {
-      sendError(res, 500, 'INTERNAL', (error as Error).message);
+      sendError(res, 500, 'INTERNAL_ERROR', (error as Error).message);
     }
   });
 }

packages/services/service-datasource/src/__tests__/admin-routes.test.ts

@@ -145,7 +145,7 @@ describe('registerDatasourceAdminRoutes (real HonoHttpServer)', () => {
     expect(await res.json()).toEqual({
       success: false,
       error: {
-        code: 'datasource_admin_unavailable',
+        code: 'SERVICE_UNAVAILABLE',
         message: 'The datasource-admin service is not available.',
       },
     });
@@ -167,7 +167,7 @@ describe('registerDatasourceAdminRoutes (real HonoHttpServer)', () => {
     // asymmetry that made `body.error.message` read `undefined` here.
     expect(await res.json()).toEqual({
       success: false,
-      error: { code: 'datasource_admin_error', message: 'duplicate name' },
+      error: { code: 'DATASOURCE_ADMIN_ERROR', message: 'duplicate name' },
     });
   });
 });

packages/services/service-datasource/src/__tests__/envelope.conformance.test.ts

@@ -7,7 +7,7 @@
  * merely a missing `success` flag, but the pre-#3675 `{ error: '<string>' }`,
  * with the message a SIBLING of `error` rather than a field of it —
  *
- *     res.status(400).json({ error: 'datasource_admin_error', message });
+ *     res.status(400).json({ error: 'DATASOURCE_ADMIN_ERROR', message });
  *
  * so a caller reading `body.error.message` got `undefined` here and the real
  * message from the dispatcher. That is the identical asymmetry #3675 opened on,
@@ -162,37 +162,37 @@ describe('datasource-admin envelope (#3843) — error bodies', () => {
     {
       name: 'the datasource-admin service is not wired',
       status: 503,
-      code: 'datasource_admin_unavailable',
+      code: 'SERVICE_UNAVAILABLE',
       run: () => drive(mount(undefined), '/api/v1/datasources'),
     },
     {
       name: 'a lifecycle failure carries the service message',
       status: 400,
-      code: 'datasource_admin_error',
+      code: 'DATASOURCE_ADMIN_ERROR',
       run: () => drive(mount({ createDatasource: async () => { throw new Error('duplicate name'); } }), '/api/v1/datasources', { method: 'POST', body: JSON.stringify({ name: 'pg' }) }),
     },
     {
       name: 'a missing required body field',
       status: 400,
-      code: 'datasource_admin_error',
+      code: 'DATASOURCE_ADMIN_ERROR',
       run: () => drive(mount({ generateObjectDraft: async () => ({}) }), '/api/v1/datasources/ext/object-draft', { method: 'POST', body: '{}' }),
     },
     {
       name: 'reading a datasource that does not exist',
       status: 404,
-      code: 'not_found',
+      code: 'RESOURCE_NOT_FOUND',
       run: () => drive(mount({ getDatasource: async () => undefined }), '/api/v1/datasources/nope'),
     },
     {
       name: 'a remote-table introspection failure',
       status: 400,
-      code: 'datasource_admin_error',
+      code: 'DATASOURCE_ADMIN_ERROR',
       run: () => drive(mount({ listRemoteTables: async () => { throw new Error('no such schema'); } }), '/api/v1/datasources/ext/remote-tables'),
     },
     {
       name: 'a removal failure',
       status: 400,
-      code: 'datasource_admin_error',
+      code: 'DATASOURCE_ADMIN_ERROR',
       run: () => drive(mount({ removeDatasource: async () => { throw new Error('not runtime-origin'); } }), '/api/v1/datasources/pg', { method: 'DELETE' }),
     },
   ];

packages/services/service-datasource/src/admin-routes.ts

@@ -9,7 +9,7 @@ import { DRIVER_CATALOG } from './driver-catalog.js';
  *
  * Mounted under `/api/v1/datasources` and served by the `datasource-admin`
  * service. Every route degrades gracefully
- * (`503 datasource_admin_unavailable`) when the service is not wired in, and
+ * (`503 SERVICE_UNAVAILABLE`) when the service is not wired in, and
  * lifecycle/validation failures surface as `400` with the service's message.
  *
  *   GET    /datasources              → listDatasources (provenance + health)
@@ -66,13 +66,21 @@ export function registerDatasourceAdminRoutes(
    * difference; that shim is the consumer-side symptom Prime Directive #12 says
    * to cure at the producer.
    *
-   * The `code` strings are carried over UNCHANGED (`datasource_admin_error`,
-   * `not_found`, …) even though they are lowercase snake while
-   * `storage-routes.ts` and `settings-routes.ts` emit SCREAMING_SNAKE. Which
-   * vocabulary wins is #3841's call, and it is a decision about ~240 codes
-   * repo-wide, not about these four; re-spelling them here would pick that
-   * dialect by accident and make #3841's sweep harder to verify. This change is
-   * the envelope only — the same split #3687 / #3837 made deliberately.
+   * The codes follow ADR-0112, which #3841 settled while this was in review:
+   * `error.code` is SCREAMING_SNAKE and `ApiErrorSchema.code` is now the closed
+   * `ErrorCode` union, so an unregistered code fails schema parse. The old
+   * lowercase trio was re-spelled accordingly, and the generic conditions went to
+   * the STANDARD catalog rather than becoming registered synonyms of it:
+   *
+   *   datasource_admin_unavailable → SERVICE_UNAVAILABLE   (standard)
+   *   not_found                    → RESOURCE_NOT_FOUND    (standard)
+   *   datasource_admin_error       → DATASOURCE_ADMIN_ERROR (registered — a
+   *                                  lifecycle/validation refusal specific to
+   *                                  this service, so not a standard synonym)
+   *
+   * Which service is unavailable is carried by `message`; the ledger explicitly
+   * asks generic conditions to reuse the catalog instead of registering a
+   * per-service 503.
    */
   const sendError = (res: any, status: number, code: string, message: string) =>
     res.status(status).json({ success: false, error: { code, message } });
@@ -90,10 +98,10 @@ export function registerDatasourceAdminRoutes(
     res.status(status).json({ success: true, data });
 
   const unavailable = (res: any) =>
-    sendError(res, 503, 'datasource_admin_unavailable', 'The datasource-admin service is not available.');
+    sendError(res, 503, 'SERVICE_UNAVAILABLE', 'The datasource-admin service is not available.');
 
   const badRequest = (res: any, err: unknown) =>
-    sendError(res, 400, 'datasource_admin_error', err instanceof Error ? err.message : String(err));
+    sendError(res, 400, 'DATASOURCE_ADMIN_ERROR', err instanceof Error ? err.message : String(err));
 
   /** Split an inline `{ secret, ...draft }` body into (draft, secret). */
   const splitSecret = (body: any): { draft: any; secret: any } => {
@@ -151,7 +159,7 @@ export function registerDatasourceAdminRoutes(
     if (!svc?.getDatasource) return unavailable(res);
     try {
       const datasource = await svc.getDatasource(req.params.name);
-      if (!datasource) return sendError(res, 404, 'not_found', `Datasource "${req.params.name}" does not exist.`);
+      if (!datasource) return sendError(res, 404, 'RESOURCE_NOT_FOUND', `Datasource "${req.params.name}" does not exist.`);
       sendOk(res, { datasource });
     } catch (err) {
       badRequest(res, err);