@owlmeans/server-api 0.1.18-rc.31 → 0.1.18-rc.33

package/README.md

@@ -10,7 +10,7 @@ only when composing a context without that package. WebSocket routes belong to
 ## Installation
 
 ```bash
-bun add @owlmeans/server-api@^0.1.18-rc.27
+bun add @owlmeans/server-api@^0.1.18-rc.33
 ```
 
 ## Concepts
@@ -27,7 +27,12 @@ bun add @owlmeans/server-api@^0.1.18-rc.27
 - **Validation** — the contract's schemas are compiled with AJV (`removeAdditional`, `useDefaults`,
   `coerceTypes`), so a handler receives cleaned, coerced input.
 - **Error mapping** — `AuthForbidden` / `AccessError` answer 403, `AuthorizationError` /
-  `AuthFailedError` answer 401, anything else 500, with the marshalled `ResilientError` as the body.
+  `AuthFailedError` answer 401, a class declaring `static httpStatus` as an integer 4xx answers that
+  status, and anything else 500 — always with the marshalled `ResilientError` as the body. A refusal
+  of the caller's condition declares its status; a fault declares nothing and stays 500. The status
+  is taken from the error as thrown first, and from the ensured (rebuilt) error only when that
+  answers 500. An auth family is matched by class or by exact registered type name (the instance's
+  `type` or a `typeName` on its constructor chain), so duplicate module copies answer the same.
 
 ## Usage
 
@@ -82,6 +87,22 @@ export const rename = api.body(projectProtocols.rename, async ({ name }, context
 })
 ```
 
+A refusal that is not about permission declares its own 4xx on the class. The declaring package
+never imports this one — the static property is read structurally and inherited by subclasses:
+
+```ts
+import { ResilientError } from '@owlmeans/error'
+
+export class ProjectBusy extends ResilientError {
+  public static override typeName = 'ProjectBusy'
+  public static httpStatus = 409 // honoured only as an integer 400–499; anything else answers 500
+
+  constructor(message: string = 'error') {
+    super(ProjectBusy.typeName, `project-busy:${message}`)
+  }
+}
+```
+
 ### File upload
 
 `uploadedFile(request)` is the only place a handler touches the Fastify multipart API. The protocol
@@ -171,7 +192,10 @@ code does not need it.
 | `canServeModule(context, module)` | function | Whether an entrypoint belongs on this HTTP server |
 | `provideRequest(alias, req, provision?)` | function | Build an `AbstractRequest` from a Fastify request |
 | `executeResponse(response, reply, throwOnError?)` | function | Send an `AbstractResponse` onto a reply |
-| `handleError(error, reply)` | function | Map an error onto 401 / 403 / 500 |
+| `handleError(error, reply)` | function | Answer an error with `errorStatus` and the marshalled body |
+| `errorStatus(error)` | function | 403 / 401 for auth errors (by class or type name), else the class's declared 4xx, else 500 |
+| `declaredErrorStatus(error)` | function | The integer 4xx a class declares through `static httpStatus`, or `null` |
+| `HttpStatusDeclaration` | type | `{ httpStatus?: unknown }` — the structural shape a declaring class has |
 | `fixFormatDates(schema)` | function | Rewrite `date-time` object schemas as strings |
 | `populateContext(req, context)`, `extractContext(req, ctx?, location?)` | function | Carry the request-scoped context on the raw request |
 
@@ -216,7 +240,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.26
+npx @owlmeans/agent-skills@^0.1.18-rc.28
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/server-api",
-  "version": "0.1.18-rc.31",
-  "generatedAt": "2026-09-15T13:12:48.098Z",
+  "version": "0.1.18-rc.33",
+  "generatedAt": "2026-09-17T08:16:11.165Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/server-api/SKILL.md

@@ -7,7 +7,7 @@ user-invocable: false
 
 # @owlmeans/server-api
 
-**Install:** `bun add @owlmeans/server-api@^0.1.18-rc.27`
+**Install:** `bun add @owlmeans/server-api@^0.1.18-rc.33`
 
 Make handlers from the protocol declaration so input and output types stay coupled to the shared
 contract:
@@ -56,6 +56,49 @@ protocol unchanged, with a one-time warning; anything else that is not a plain f
 that one route with `HandlerMisconfiguredError`, instead of the opaque
 `TypeError: handler is not a function`.
 
+## The status a thrown error answers
+
+A thrown error (or a rejected response) is answered with the marshalled `ResilientError` as the
+body and a status from `errorStatus(error)` (`./utils`), resolved in this order:
+
+| Error | Status |
+|---|---|
+| `AuthForbidden`, `AccessError` or a subclass — by class or registered type name | 403 |
+| `AuthorizationError`, `AuthFailedError` or a subclass — by class or registered type name | 401 |
+| a class declaring `static httpStatus` as an integer 400–499 | that status |
+| anything else, including a declaration outside 400–499 | 500 |
+
+- **A refusal of the caller's condition declares its status; a fault declares nothing.** 400 a
+  malformed request, 402 an unpaid balance or plan, 404 an addressed target that does not exist
+  (or is another organization's), 409 a target whose current state conflicts, 422 content or a body
+  that is understood and refused — and a missing configuration, a broken peer, a timeout or a bug
+  stays 500, because monitoring, logs, proxies and retry logic read a 5xx as the server failing.
+  The table and the leaf-class rule are the `error` skill's.
+- Declare it on the class: `public static httpStatus = 409` (`override` only when an ancestor
+  already declares one). The declaration is structural — the package declaring an error never
+  imports `@owlmeans/server-api` — and a static property is inherited, so a subclass answers its
+  nearest declaring ancestor's status and redeclares to change it.
+- The auth branches win over a declaration, in that order (`AuthForbidden extends
+  AuthorizationError`, so 403 is tested first). An entitlement or permission refusal extends
+  `AuthForbidden` rather than declaring 403.
+- `handleError` resolves the status on the error AS THROWN first, and asks the ENSURED
+  (`ResilientError.ensure`) error only when that answers 500. The thrown object is the one whose
+  class is certainly what was raised; the rebuild is what gives a status to a marshalled error that
+  crossed a hop as a plain `Error`. `ensure` returns an error from any `@owlmeans/error` copy
+  untouched, so the body keeps the thrown class's `type` (`AuthFailedError|||api:auth:…`) even in a
+  process holding duplicate module copies (`bun --preserve-symlinks`). `executeResponse` ensures
+  nothing and answers the rejected error's status. `@owlmeans/server-socket` answers an upgrade
+  through the same `handleError`.
+- An auth family is recognised by `instanceof` OR by an exact registered type name — the instance's
+  `type` or any static `typeName` on its constructor chain — so a class from another module copy
+  answers the same status. Match whole names, never substrings: a subclass's `typeName` does not
+  reliably embed its parent's (`EntitlementRefusal` extends `AuthForbidden`). A declared
+  `httpStatus` is a structural static read and survives duplicate copies as it is.
+- The status never changes what a client rebuilds: `@owlmeans/api` rehydrates the class from the
+  body for any non-2xx answer, so a caller branches on the class, never on the number. Nothing in
+  the framework treats a 404 specially — a missing route is a Fastify JSON body the client turns
+  into `ApiClientError('404')`, a refusal is a marshalled string rebuilt as its class.
+
 `uploadedFile(request)` is the Fastify multipart boundary. Keep raw Fastify access there rather
 than reaching through `request.original` in application code.
 

package/build/utils/error.d.ts

@@ -1,16 +1,51 @@
 import type { FastifyReply } from 'fastify';
 /**
- * Map a thrown error onto an HTTP status.
+ * What an error class may declare about the HTTP status it is answered with.
+ *
+ * Structural on purpose: the classes that declare it live in packages that must not depend on an
+ * HTTP server (`@owlmeans/payment`, a product's contract package), so they write a plain
+ * `public static httpStatus = 409` and nothing imports this type.
+ */
+export interface HttpStatusDeclaration {
+    httpStatus?: unknown;
+}
+/**
+ * The 4xx status an error's class declares, or `null` when it declares none that may be honoured.
+ *
+ * Read through the constructor chain — a static property is inherited, so a subclass answers what
+ * its nearest declaring ancestor says, and redeclares to change it. Only an integer 4xx is honoured:
+ * a declaration is how a class says "this is the caller's condition, not a fault", and a 5xx, a 2xx,
+ * a string or a fraction says nothing a boundary can act on. The read is structural, so a class from
+ * a duplicate module copy declares exactly what the imported one does.
+ */
+export declare const declaredErrorStatus: (error: unknown) => number | null;
+/**
+ * The HTTP status an error is answered with, read off the error exactly as given.
  *
  * Two families reach here and both must be recognised. `AuthFailedError` / `AccessError` are this
  * package's own, raised by the request pipeline itself. `AuthorizationError` / `AuthForbidden`
  * come from `@owlmeans/auth` and are what the guards and gates actually throw — an unrecognised
  * one answers 500, which reports a refused request as a crashed server: the client cannot tell
  * "sign in again" from "the service is broken", and a consumer watching statuses concludes the
- * application fell over.
+ * application fell over. A family member is recognised by class OR by registered type name
+ * ({@link typeNamesOf}), so a class from a duplicate module copy answers the same status.
  *
  * **Order matters.** `AuthForbidden extends AuthorizationError`, so the 403 branch has to be
- * tested first or every refusal of a permission is reported as a failure to authenticate.
+ * tested first or every refusal of a permission is reported as a failure to authenticate. Both
+ * auth branches come before a class's own declaration, so an auth refusal can never be restated
+ * as something else. Everything that is neither an auth error nor a class declaring a 4xx
+ * {@link declaredErrorStatus} answers 500.
+ */
+export declare const errorStatus: (error: unknown) => number;
+/**
+ * Answer a thrown error: a status, and the marshalled `ResilientError` as the body.
+ *
+ * The status is resolved in two steps. The error AS THROWN comes first: it is the one object whose
+ * class is certainly the class that was raised, while `ResilientError.ensure` rebuilds through the
+ * registry of whichever `@owlmeans/error` copy this module loaded — under duplicate module copies
+ * that turns a perfectly recognisable auth refusal into a plain `ResilientError` answering 500.
+ * Only when the thrown error answers 500 is the ENSURED error asked, because the rebuild is what
+ * gives a status to a marshalled error that crossed a hop as a plain `Error`.
  */
 export declare const handleError: (error: Error, reply: FastifyReply) => void;
 //# sourceMappingURL=error.d.ts.map

package/build/utils/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/utils/error.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAK3C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,UAAW,KAAK,SAAS,YAAY,SAe5D,CAAA"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/utils/error.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAK3C;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAKD;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,UAAW,OAAO,KAAG,MAAM,GAAG,IAW7D,CAAA;AAkCD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,WAAW,UAAW,OAAO,KAAG,MAkB5C,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,UAAW,KAAK,SAAS,YAAY,SAO5D,CAAA"}

package/build/utils/error.js

@@ -2,32 +2,107 @@ import { FORBIDDEN_ERROR, SERVER_ERROR, UNAUTHORIZED_ERROR } from '@owlmeans/api
 import { AccessError, AuthFailedError } from '../errors.js';
 import { AuthForbidden, AuthorizationError } from '@owlmeans/auth';
 import { ResilientError } from '@owlmeans/error';
+const CLIENT_ERROR_FIRST = 400;
+const CLIENT_ERROR_LAST = 499;
 /**
- * Map a thrown error onto an HTTP status.
+ * The 4xx status an error's class declares, or `null` when it declares none that may be honoured.
+ *
+ * Read through the constructor chain — a static property is inherited, so a subclass answers what
+ * its nearest declaring ancestor says, and redeclares to change it. Only an integer 4xx is honoured:
+ * a declaration is how a class says "this is the caller's condition, not a fault", and a 5xx, a 2xx,
+ * a string or a fraction says nothing a boundary can act on. The read is structural, so a class from
+ * a duplicate module copy declares exactly what the imported one does.
+ */
+export const declaredErrorStatus = (error) => {
+    if (error == null || typeof error !== 'object') {
+        return null;
+    }
+    const status = error.constructor?.httpStatus;
+    if (typeof status !== 'number' || !Number.isInteger(status)
+        || status < CLIENT_ERROR_FIRST || status > CLIENT_ERROR_LAST) {
+        return null;
+    }
+    return status;
+};
+/**
+ * The registered type names an error carries: its own `type`, and the static `typeName` of every
+ * class on its constructor chain.
+ *
+ * This is how a class is recognised when `instanceof` cannot see it. A process that loads a package
+ * twice — `bun --preserve-symlinks` over a linked workspace resolves one package through several
+ * `node_modules` paths — holds several copies of every error class, and an error built by one copy
+ * is not an instance of another. The registered names are the same in every copy. A subclass's
+ * `typeName` does not reliably embed its parent's (`EntitlementRefusal` extends `AuthForbidden`), so
+ * a family is recognised by walking the chain and matching names exactly, never by a substring.
+ */
+const typeNamesOf = (error) => {
+    const names = new Set();
+    const type = error.type;
+    if (typeof type === 'string') {
+        names.add(type);
+    }
+    let ctor = error.constructor;
+    while (typeof ctor === 'function') {
+        const name = ctor.typeName;
+        if (typeof name === 'string') {
+            names.add(name);
+        }
+        ctor = Object.getPrototypeOf(ctor);
+    }
+    return names;
+};
+const isOfFamily = (names, family) => family.some(typeName => names.has(typeName));
+/**
+ * The HTTP status an error is answered with, read off the error exactly as given.
  *
  * Two families reach here and both must be recognised. `AuthFailedError` / `AccessError` are this
  * package's own, raised by the request pipeline itself. `AuthorizationError` / `AuthForbidden`
  * come from `@owlmeans/auth` and are what the guards and gates actually throw — an unrecognised
  * one answers 500, which reports a refused request as a crashed server: the client cannot tell
  * "sign in again" from "the service is broken", and a consumer watching statuses concludes the
- * application fell over.
+ * application fell over. A family member is recognised by class OR by registered type name
+ * ({@link typeNamesOf}), so a class from a duplicate module copy answers the same status.
  *
  * **Order matters.** `AuthForbidden extends AuthorizationError`, so the 403 branch has to be
- * tested first or every refusal of a permission is reported as a failure to authenticate.
+ * tested first or every refusal of a permission is reported as a failure to authenticate. Both
+ * auth branches come before a class's own declaration, so an auth refusal can never be restated
+ * as something else. Everything that is neither an auth error nor a class declaring a 4xx
+ * {@link declaredErrorStatus} answers 500.
  */
-export const handleError = (error, reply) => {
-    let code = SERVER_ERROR;
-    if (error instanceof AuthForbidden || error instanceof AccessError) {
+export const errorStatus = (error) => {
+    if (error == null || typeof error !== 'object') {
+        return SERVER_ERROR;
+    }
+    const names = typeNamesOf(error);
+    if (error instanceof AuthForbidden || error instanceof AccessError
+        || isOfFamily(names, [AuthForbidden.typeName, AccessError.typeName])) {
         // An established identity that lacks the permission. Re-authenticating changes nothing.
-        code = FORBIDDEN_ERROR;
+        return FORBIDDEN_ERROR;
     }
-    else if (error instanceof AuthorizationError || error instanceof AuthFailedError) {
+    if (error instanceof AuthorizationError || error instanceof AuthFailedError
+        || isOfFamily(names, [AuthorizationError.typeName, AuthFailedError.typeName])) {
         // No usable credential — absent, expired, revoked, or naming a session this server no longer
         // holds. The caller is told to sign in, not that signing in would not help.
-        code = UNAUTHORIZED_ERROR;
+        return UNAUTHORIZED_ERROR;
     }
+    return declaredErrorStatus(error) ?? SERVER_ERROR;
+};
+/**
+ * Answer a thrown error: a status, and the marshalled `ResilientError` as the body.
+ *
+ * The status is resolved in two steps. The error AS THROWN comes first: it is the one object whose
+ * class is certainly the class that was raised, while `ResilientError.ensure` rebuilds through the
+ * registry of whichever `@owlmeans/error` copy this module loaded — under duplicate module copies
+ * that turns a perfectly recognisable auth refusal into a plain `ResilientError` answering 500.
+ * Only when the thrown error answers 500 is the ENSURED error asked, because the rebuild is what
+ * gives a status to a marshalled error that crossed a hop as a plain `Error`.
+ */
+export const handleError = (error, reply) => {
     if (!reply.sent) {
-        reply.code(code).send(ResilientError.marshal(ResilientError.ensure(error)).message);
+        const resilient = ResilientError.ensure(error);
+        const thrown = errorStatus(error);
+        reply.code(thrown !== SERVER_ERROR ? thrown : errorStatus(resilient))
+            .send(ResilientError.marshal(resilient).message);
     }
 };
 //# sourceMappingURL=error.js.map

package/build/utils/error.js.map

@@ -1 +1 @@
-{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/utils/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAEjF,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAC3D,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAY,EAAE,KAAmB,EAAE,EAAE;IAC/D,IAAI,IAAI,GAAW,YAAY,CAAA;IAC/B,IAAI,KAAK,YAAY,aAAa,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;QACnE,wFAAwF;QACxF,IAAI,GAAG,eAAe,CAAA;IACxB,CAAC;SAAM,IAAI,KAAK,YAAY,kBAAkB,IAAI,KAAK,YAAY,eAAe,EAAE,CAAC;QACnF,6FAA6F;QAC7F,4EAA4E;QAC5E,IAAI,GAAG,kBAAkB,CAAA;IAC3B,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAChB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CACnB,cAAc,CAAC,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,KAAc,CAAC,CAAC,CAAC,OAAO,CACtE,CAAA;IACH,CAAC;AACH,CAAC,CAAA"}
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/utils/error.ts"],"names":[],"mappings":"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"}

package/build/utils/payload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../src/utils/payload.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC7E,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,KAAK,CAAA;AAE1C,eAAO,MAAM,cAAc,UAAW,MAAM,OAAO,OAAO,cAAc,OAAO,KAAG,eAejF,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,YAAY,gBAAgB,CAAC,CAAC,CAAC,SAAS,QAAQ,iBAAiB,OAAO,KAAG,OAuB3G,CAAA;AAGD,eAAO,MAAM,cAAc,WAAY,eAAe,oBAgBrD,CAAA"}
+{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../src/utils/payload.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC7E,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,KAAK,CAAA;AAG1C,eAAO,MAAM,cAAc,UAAW,MAAM,OAAO,OAAO,cAAc,OAAO,KAAG,eAejF,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,YAAY,gBAAgB,CAAC,CAAC,CAAC,SAAS,QAAQ,iBAAiB,OAAO,KAAG,OA0B3G,CAAA;AAGD,eAAO,MAAM,cAAc,WAAY,eAAe,oBAgBrD,CAAA"}

package/build/utils/payload.js

@@ -1,5 +1,6 @@
 import { EntrypointOutcome } from '@owlmeans/entrypoint';
-import { ACCEPTED, CREATED, OK, SERVER_ERROR } from '@owlmeans/api';
+import { ACCEPTED, CREATED, OK } from '@owlmeans/api';
+import { errorStatus } from './error.js';
 export const provideRequest = (alias, req, provision) => {
     provision = provision ?? false;
     return {
@@ -30,7 +31,10 @@ export const executeResponse = (response, reply, throwOnError) => {
         if (throwOnError ?? false) {
             throw response.error;
         }
-        reply.code(SERVER_ERROR).send(response.error.message);
+        // The status of the error as rejected, resolved like `handleError`'s first step — every pipeline
+        // caller passes `throwOnError` and lands there; a caller that does not must not report a refusal
+        // as a crash either. Nothing is ensured here, so there is no rebuilt error to ask second.
+        reply.code(errorStatus(response.error)).send(response.error.message);
         return true;
     }
     else if (response.outcome != null) {

package/build/utils/payload.js.map

@@ -1 +1 @@
-{"version":3,"file":"payload.js","sourceRoot":"","sources":["../../src/utils/payload.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"payload.js","sourceRoot":"","sources":["../../src/utils/payload.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-api",
-  "version": "0.1.18-rc.31",
+  "version": "0.1.18-rc.33",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -33,15 +33,15 @@
     "@fastify/helmet": "^13.1.0",
     "@fastify/middie": "^9.0.2",
     "@fastify/multipart": "^9.0.1",
-    "@owlmeans/api": "^0.1.18-rc.27",
-    "@owlmeans/auth": "^0.1.18-rc.23",
-    "@owlmeans/auth-common": "^0.1.18-rc.27",
-    "@owlmeans/context": "^0.1.18-rc.22",
-    "@owlmeans/error": "^0.1.18-rc.22",
-    "@owlmeans/entrypoint": "^0.1.18-rc.25",
-    "@owlmeans/route": "^0.1.18-rc.23",
-    "@owlmeans/server-context": "^0.1.18-rc.26",
-    "@owlmeans/server-entrypoint": "^0.1.18-rc.25",
+    "@owlmeans/api": "^0.1.18-rc.29",
+    "@owlmeans/auth": "^0.1.18-rc.27",
+    "@owlmeans/auth-common": "^0.1.18-rc.29",
+    "@owlmeans/context": "^0.1.18-rc.25",
+    "@owlmeans/error": "^0.1.18-rc.27",
+    "@owlmeans/entrypoint": "^0.1.18-rc.28",
+    "@owlmeans/route": "^0.1.18-rc.26",
+    "@owlmeans/server-context": "^0.1.18-rc.28",
+    "@owlmeans/server-entrypoint": "^0.1.18-rc.27",
     "ajv-errors": "^3.0.0",
     "fastify": "^5.0.0",
     "fastify-raw-body": "^5.0.0",

package/src/utils/error.ts

@@ -5,31 +5,125 @@ import { AuthForbidden, AuthorizationError } from '@owlmeans/auth'
 import { ResilientError } from '@owlmeans/error'
 
 /**
- * Map a thrown error onto an HTTP status.
+ * What an error class may declare about the HTTP status it is answered with.
+ *
+ * Structural on purpose: the classes that declare it live in packages that must not depend on an
+ * HTTP server (`@owlmeans/payment`, a product's contract package), so they write a plain
+ * `public static httpStatus = 409` and nothing imports this type.
+ */
+export interface HttpStatusDeclaration {
+  httpStatus?: unknown
+}
+
+const CLIENT_ERROR_FIRST = 400
+const CLIENT_ERROR_LAST = 499
+
+/**
+ * The 4xx status an error's class declares, or `null` when it declares none that may be honoured.
+ *
+ * Read through the constructor chain — a static property is inherited, so a subclass answers what
+ * its nearest declaring ancestor says, and redeclares to change it. Only an integer 4xx is honoured:
+ * a declaration is how a class says "this is the caller's condition, not a fault", and a 5xx, a 2xx,
+ * a string or a fraction says nothing a boundary can act on. The read is structural, so a class from
+ * a duplicate module copy declares exactly what the imported one does.
+ */
+export const declaredErrorStatus = (error: unknown): number | null => {
+  if (error == null || typeof error !== 'object') {
+    return null
+  }
+  const status = (error.constructor as HttpStatusDeclaration | undefined)?.httpStatus
+  if (typeof status !== 'number' || !Number.isInteger(status)
+    || status < CLIENT_ERROR_FIRST || status > CLIENT_ERROR_LAST) {
+    return null
+  }
+
+  return status
+}
+
+/**
+ * The registered type names an error carries: its own `type`, and the static `typeName` of every
+ * class on its constructor chain.
+ *
+ * This is how a class is recognised when `instanceof` cannot see it. A process that loads a package
+ * twice — `bun --preserve-symlinks` over a linked workspace resolves one package through several
+ * `node_modules` paths — holds several copies of every error class, and an error built by one copy
+ * is not an instance of another. The registered names are the same in every copy. A subclass's
+ * `typeName` does not reliably embed its parent's (`EntitlementRefusal` extends `AuthForbidden`), so
+ * a family is recognised by walking the chain and matching names exactly, never by a substring.
+ */
+const typeNamesOf = (error: object): Set<string> => {
+  const names = new Set<string>()
+  const type = (error as { type?: unknown }).type
+  if (typeof type === 'string') {
+    names.add(type)
+  }
+  let ctor: unknown = error.constructor
+  while (typeof ctor === 'function') {
+    const name = (ctor as { typeName?: unknown }).typeName
+    if (typeof name === 'string') {
+      names.add(name)
+    }
+    ctor = Object.getPrototypeOf(ctor)
+  }
+
+  return names
+}
+
+const isOfFamily = (names: Set<string>, family: string[]): boolean =>
+  family.some(typeName => names.has(typeName))
+
+/**
+ * The HTTP status an error is answered with, read off the error exactly as given.
  *
  * Two families reach here and both must be recognised. `AuthFailedError` / `AccessError` are this
  * package's own, raised by the request pipeline itself. `AuthorizationError` / `AuthForbidden`
  * come from `@owlmeans/auth` and are what the guards and gates actually throw — an unrecognised
  * one answers 500, which reports a refused request as a crashed server: the client cannot tell
  * "sign in again" from "the service is broken", and a consumer watching statuses concludes the
- * application fell over.
+ * application fell over. A family member is recognised by class OR by registered type name
+ * ({@link typeNamesOf}), so a class from a duplicate module copy answers the same status.
  *
  * **Order matters.** `AuthForbidden extends AuthorizationError`, so the 403 branch has to be
- * tested first or every refusal of a permission is reported as a failure to authenticate.
+ * tested first or every refusal of a permission is reported as a failure to authenticate. Both
+ * auth branches come before a class's own declaration, so an auth refusal can never be restated
+ * as something else. Everything that is neither an auth error nor a class declaring a 4xx
+ * {@link declaredErrorStatus} answers 500.
  */
-export const handleError = (error: Error, reply: FastifyReply) => {
-  let code: number = SERVER_ERROR
-  if (error instanceof AuthForbidden || error instanceof AccessError) {
+export const errorStatus = (error: unknown): number => {
+  if (error == null || typeof error !== 'object') {
+    return SERVER_ERROR
+  }
+  const names = typeNamesOf(error)
+  if (error instanceof AuthForbidden || error instanceof AccessError
+    || isOfFamily(names, [AuthForbidden.typeName, AccessError.typeName])) {
     // An established identity that lacks the permission. Re-authenticating changes nothing.
-    code = FORBIDDEN_ERROR
-  } else if (error instanceof AuthorizationError || error instanceof AuthFailedError) {
+    return FORBIDDEN_ERROR
+  }
+  if (error instanceof AuthorizationError || error instanceof AuthFailedError
+    || isOfFamily(names, [AuthorizationError.typeName, AuthFailedError.typeName])) {
     // No usable credential — absent, expired, revoked, or naming a session this server no longer
     // holds. The caller is told to sign in, not that signing in would not help.
-    code = UNAUTHORIZED_ERROR
+    return UNAUTHORIZED_ERROR
   }
+
+  return declaredErrorStatus(error) ?? SERVER_ERROR
+}
+
+/**
+ * Answer a thrown error: a status, and the marshalled `ResilientError` as the body.
+ *
+ * The status is resolved in two steps. The error AS THROWN comes first: it is the one object whose
+ * class is certainly the class that was raised, while `ResilientError.ensure` rebuilds through the
+ * registry of whichever `@owlmeans/error` copy this module loaded — under duplicate module copies
+ * that turns a perfectly recognisable auth refusal into a plain `ResilientError` answering 500.
+ * Only when the thrown error answers 500 is the ENSURED error asked, because the rebuild is what
+ * gives a status to a marshalled error that crossed a hop as a plain `Error`.
+ */
+export const handleError = (error: Error, reply: FastifyReply) => {
   if (!reply.sent) {
-    reply.code(code).send(
-      ResilientError.marshal(ResilientError.ensure(error as Error)).message
-    )
+    const resilient = ResilientError.ensure(error as Error)
+    const thrown = errorStatus(error)
+    reply.code(thrown !== SERVER_ERROR ? thrown : errorStatus(resilient))
+      .send(ResilientError.marshal(resilient).message)
   }
 }

package/src/utils/payload.ts

@@ -1,8 +1,9 @@
 import { EntrypointOutcome } from '@owlmeans/entrypoint'
 import type { AbstractResponse, AbstractRequest } from '@owlmeans/entrypoint'
 import type { Request, Response } from '../types.js'
-import { ACCEPTED, CREATED, OK, SERVER_ERROR } from '@owlmeans/api'
+import { ACCEPTED, CREATED, OK } from '@owlmeans/api'
 import type { AnySchemaObject } from 'ajv'
+import { errorStatus } from './error.js'
 
 export const provideRequest = (alias: string, req: Request, provision?: boolean): AbstractRequest => {
   provision = provision ?? false
@@ -35,7 +36,10 @@ export const executeResponse = <T>(response: AbstractResponse<T>, reply: Respons
     if (throwOnError ?? false) {
       throw response.error
     }
-    reply.code(SERVER_ERROR).send(response.error.message)
+    // The status of the error as rejected, resolved like `handleError`'s first step — every pipeline
+    // caller passes `throwOnError` and lands there; a caller that does not must not report a refusal
+    // as a crash either. Nothing is ensured here, so there is no rebuilt error to ask second.
+    reply.code(errorStatus(response.error)).send(response.error.message)
     return true
   } else if (response.outcome != null) {
     switch (response.outcome) {

package/tests/error-status.spec.ts

@@ -0,0 +1,222 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import Fastify from 'fastify'
+import type { FastifyInstance } from 'fastify'
+import { AuthForbidden, AuthorizationError } from '@owlmeans/auth'
+import { ResilientError } from '@owlmeans/error'
+import { provideResponse } from '@owlmeans/entrypoint'
+import { errorStatus, handleError } from '../src/utils/error.js'
+import { executeResponse } from '../src/utils/payload.js'
+import { AccessError, AuthFailedError } from '../src/errors.js'
+
+class OutOfCredit extends ResilientError {
+  public static override typeName = 'ServerApiSpecOutOfCredit'
+  public static httpStatus = 402
+
+  constructor(message: string = 'error') {
+    super(OutOfCredit.typeName, `out-of-credit:${message}`)
+  }
+}
+
+/** Inherits 402 without redeclaring it. */
+class OutOfCreditForStory extends OutOfCredit {
+  public static override typeName = 'ServerApiSpecOutOfCreditForStory'
+
+  constructor() {
+    super('story')
+    this.type = OutOfCreditForStory.typeName
+  }
+}
+
+/** Redeclares its parent's status to a conflict. */
+class Busy extends OutOfCredit {
+  public static override typeName = 'ServerApiSpecBusy'
+  public static override httpStatus = 409
+
+  constructor() {
+    super('busy')
+    this.type = Busy.typeName
+  }
+}
+
+/** An auth refusal that also declares a status: the auth mapping still wins. */
+class DeclaringForbidden extends AuthForbidden {
+  public static override typeName = 'ServerApiSpecDeclaringForbidden'
+  public static httpStatus = 402
+
+  constructor() {
+    super('declaring')
+    this.type = DeclaringForbidden.typeName
+  }
+}
+
+const declaring = (typeName: string, httpStatus: unknown) => {
+  class Declaring extends ResilientError {
+    public static override typeName = typeName
+    public static httpStatus = httpStatus
+
+    constructor(message: string = 'error') {
+      super(typeName, message)
+    }
+  }
+  return Declaring
+}
+
+/**
+ * A duplicate module copy of the error family — what a process loading `@owlmeans/error` through
+ * several `node_modules` paths holds: the same registered names, none of the imported classes.
+ */
+class ForeignResilientError extends Error {
+  public static typeName = 'ResilientError'
+  public type: string
+
+  constructor(type: string, message: string) {
+    super(message)
+    this.type = type
+  }
+}
+
+class ForeignAuthFailedError extends ForeignResilientError {
+  public static override typeName = 'AuthFailedError'
+
+  constructor() {
+    super(ForeignAuthFailedError.typeName, 'api:auth:error')
+  }
+}
+
+class ForeignAuthorizationError extends ForeignResilientError {
+  public static override typeName = 'AuthorizationError'
+
+  constructor(message: string = 'error') {
+    super(ForeignAuthorizationError.typeName, `auth:authorization:${message}`)
+  }
+}
+
+class ForeignAuthForbidden extends ForeignAuthorizationError {
+  public static override typeName = 'ForbiddenAuthorizationError'
+
+  constructor(message: string = 'error') {
+    super(`forbidden:${message}`)
+    this.type = ForeignAuthForbidden.typeName
+  }
+}
+
+/** A subclass whose own name embeds nothing of its parent's, like `EntitlementRefusal`. */
+class ForeignEntitlementRefusal extends ForeignAuthForbidden {
+  public static override typeName = 'EntitlementRefusal'
+
+  constructor() {
+    super('entitlement')
+    this.type = ForeignEntitlementRefusal.typeName
+  }
+}
+
+/** A declared refusal no registry of this process knows. */
+class ForeignOutOfCredit extends ForeignResilientError {
+  public static override typeName = 'ServerApiSpecForeignOutOfCredit'
+  public static httpStatus = 402
+
+  constructor() {
+    super(ForeignOutOfCredit.typeName, 'out-of-credit:foreign')
+  }
+}
+
+const typed = (type: string) => Object.assign(new Error('typed'), { type })
+
+ResilientError.registerErrorClass(OutOfCredit)
+ResilientError.registerErrorClass(OutOfCreditForStory)
+ResilientError.registerErrorClass(Busy)
+ResilientError.registerErrorClass(DeclaringForbidden)
+
+let server: FastifyInstance
+let thrown: unknown
+
+beforeAll(async () => {
+  server = Fastify()
+  server.get('/handle', async (_req, reply) => {
+    handleError(thrown as Error, reply)
+    return reply
+  })
+  server.get('/execute', async (_req, reply) => {
+    const response = provideResponse(reply)
+    response.reject(thrown as Error)
+    executeResponse(response, reply)
+    return reply
+  })
+  await server.ready()
+})
+
+afterAll(async () => {
+  await server.close()
+})
+
+const answer = async (error: unknown, path: string = '/handle') => {
+  thrown = error
+  const reply = await server.inject({ method: 'GET', url: path })
+  return { status: reply.statusCode, body: reply.body }
+}
+
+describe('@owlmeans/server-api — handleError status', () => {
+  test('keeps the auth mappings: forbidden 403, unauthenticated 401', async () => {
+    expect((await answer(new AuthForbidden('x'))).status).toBe(403)
+    expect((await answer(new AccessError())).status).toBe(403)
+    expect((await answer(new AuthorizationError('x'))).status).toBe(401)
+    expect((await answer(new AuthFailedError())).status).toBe(401)
+    expect((await answer(new DeclaringForbidden())).status).toBe(403)
+  })
+
+  test('honours a 4xx a class declares — inherited, redeclared, or after a marshal hop', async () => {
+    const refused = await answer(new OutOfCredit('create'))
+    expect(refused.status).toBe(402)
+    expect(ResilientError.ensure(new Error(refused.body))).toBeInstanceOf(OutOfCredit)
+
+    expect((await answer(new OutOfCreditForStory())).status).toBe(402)
+    expect((await answer(new Busy())).status).toBe(409)
+    expect((await answer(ResilientError.marshal(new Busy()))).status).toBe(409)
+    expect((await answer(new ForeignOutOfCredit())).status).toBe(402)
+  })
+
+  test('answers 500 for no declaration, or one outside the client-error range', async () => {
+    expect((await answer(new ResilientError('Plain', 'plain'))).status).toBe(500)
+    expect((await answer(new Error('boom'))).status).toBe(500)
+    for (const status of [500, 503, 200, 302, 399, 600, 402.5, '402', null]) {
+      const Declaring = declaring(`ServerApiSpecDeclaring${String(status)}`, status)
+      expect((await answer(new Declaring())).status).toBe(500)
+    }
+    for (const type of ['AuthFailedErrorX', 'NotAuthorizationError', 'Forbidden', 'ResilientError']) {
+      expect((await answer(typed(type))).status).toBe(500)
+      expect((await answer(new ForeignResilientError(type, 'near-miss'))).status).toBe(500)
+    }
+  })
+
+  test('executeResponse answers a rejected response with the same status', async () => {
+    expect((await answer(new OutOfCredit('create'), '/execute')).status).toBe(402)
+    expect((await answer(new AuthForbidden('x'), '/execute')).status).toBe(403)
+    expect((await answer(new ResilientError('Plain', 'plain'), '/execute')).status).toBe(500)
+  })
+})
+
+describe('@owlmeans/server-api — auth status across a rebuild and duplicate module copies', () => {
+  test('an AuthFailedError answers 401 as thrown and after a marshal round trip', async () => {
+    expect((await answer(new AuthFailedError())).status).toBe(401)
+    expect((await answer(ResilientError.marshal(new AuthFailedError()))).status).toBe(401)
+    expect(errorStatus(ResilientError.ensure(ResilientError.marshal(new AuthFailedError())))).toBe(401)
+    expect((await answer(new AuthFailedError(), '/execute')).status).toBe(401)
+  })
+
+  test('a class from another module copy answers by its registered type name', async () => {
+    // The rebuild alone loses it — the regression this resolution exists for.
+    expect(errorStatus(ResilientError.ensure(new ForeignAuthFailedError()))).toBe(500)
+    expect((await answer(new ForeignAuthFailedError())).status).toBe(401)
+    expect((await answer(new ForeignAuthorizationError())).status).toBe(401)
+    expect((await answer(new ForeignAuthForbidden())).status).toBe(403)
+    expect((await answer(new ForeignAuthForbidden(), '/execute')).status).toBe(403)
+  })
+
+  test('the family is read off the instance type or the constructor chain, 403 before 401', async () => {
+    expect((await answer(typed('AuthFailedError'))).status).toBe(401)
+    expect((await answer(typed('ForbiddenAuthorizationError'))).status).toBe(403)
+    expect((await answer(typed('AccessAuthFailedError'))).status).toBe(403)
+    // Its own type names nothing of the family; only the chain does.
+    expect((await answer(new ForeignEntitlementRefusal())).status).toBe(403)
+  })
+})