@ultimat3/http 22.15.0 → 23.0.0

package/CLAUDE.md

@@ -203,7 +203,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 | `navigation.ts` | the client router's server half: the gate `context` runs after the match (a prefetch to a route whose `meta.navigation` did not opt in → `204`; a soft GET to anything but a page of the router's `<app>:<surface>` → `204` + `x-ultimate-location`, before auth or app code) and the `response` stage's rewrite of a 3xx to a router request into the same hand-over, cookies kept |
 | `error-map.ts` | the code → status table, closed, plus the app's half (`registerErrorStatus`) |
 | `error-facts.ts` | every RENDERING of a throwable: `factsOf()`, the problem document (including the issue list and the opacity rule over it), the three terminal lines |
-| `hooks.ts` | the seams: `authenticate`, `authorize`, `devNotices` + the app's `configureAuthenticator()` |
+| `hooks.ts` | the seams: `authenticate`, `authorize`, `devNotices`, `errorPage`, `explainMiss` (asked ONLY on a `not-found` match, synchronously, with the request line alone; its error replaces `X_ROUTE_NOT_FOUND`) + the app's `configureAuthenticator()` |
 | `type-pins.ts` | compile-time claims about `AuthzDecision`'s shape — source, because `tsc` never reads a `.test.ts` |
 | `overlay.ts` | the dev error page: the same code/cause/fix as the terminal, plus any notices |
 | `overlay-style.ts` | the overlay's one stylesheet, split out so `security-headers.ts` hashes it |

package/README.md

@@ -303,6 +303,9 @@ exactly three things. Apps declare it through `defineApi({ http: { mounts } })`
 
 `RouteMeta.authenticate` is the mechanism: a route that states one is reached only through it.
 
+For API keys, `resolveToken` is `@ultimat3/auth`'s `apiKeyResolver(() => store)` — a live key is
+`{ actor, scopes }`, every wrong one is the same `null`, and a store fault stays a throw.
+
 ## Inbound webhooks
 
 `verifyWebhookSignature(request, { secret })` is the receiving half of the framework's webhook
@@ -439,3 +442,9 @@ Tier 2. Imports `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/i18n` and `@ult
 tiers 0 and 1, which is the whole rule. Authentication and policy evaluation arrive through
 `ServerHooks`, declared structurally, because `@ultimat3/policy` is a sibling tier. There is no
 plugin API: `Middleware` wraps a handler, the pipeline is everything else.
+
+`hooks.explainMiss(method, pathname)` is the same kind of seam for a request the router matched
+nothing for: the error it returns is thrown in place of `X_ROUTE_NOT_FOUND`, `undefined` keeps the
+plain miss. Synchronous, given only the request line, never asked about a matched route or a 405.
+`@ultimat3/action` answers it for a path that is one of its actions under a `pathStyle` this server
+does not serve (`X_CONTRACT_DRIFT`, 404).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/http",
-  "version": "22.15.0",
+  "version": "23.0.0",
   "description": "Owned request lifecycle over Bun.serve: router, ordered pipeline, problem+json errors",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -31,9 +32,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "22.15.0",
-    "@ultimat3/i18n": "22.15.0",
-    "@ultimat3/schema": "22.15.0",
-    "@ultimat3/time": "22.15.0"
+    "@ultimat3/core": "23.0.0",
+    "@ultimat3/i18n": "23.0.0",
+    "@ultimat3/schema": "23.0.0",
+    "@ultimat3/time": "23.0.0"
   }
 }

package/src/error-map.ts

@@ -103,6 +103,12 @@ export const ERROR_STATUS = {
   // it, and because a missing row made a typo'd uuid a 500: the caller was told the server broke,
   // and the `error-map` stage reported the caller's mistake to the on-call monitor.
   X_INPUT_INVALID: 400,
+  // The one way a SERVER answers this code: a POST to the path an action has under a path style
+  // this app does not serve (`hooks.explainMiss`). 404 because it is still a miss — nothing is
+  // routed there and nothing ran, so the status a proxy or a monitor counts is the one the plain
+  // `X_ROUTE_NOT_FOUND` had; the code and the `fix:` are what changed. Every other raise of it is
+  // client-side or a contract test, and never reaches this table.
+  X_CONTRACT_DRIFT: 404,
   // A retried `Idempotency-Key` naming a different payload, or one still in flight. 409 because
   // that is what the action's own OpenAPI operation publishes for it — the runtime answered 500
   // while the document promised 409, and a client written against the spec read the framework
@@ -215,6 +221,10 @@ export const ERROR_STATUS = {
   // 500, the same shelf as `X_SEARCH_UNDECLARED`: a column with no machine is a declaration the
   // app has not written, and no request changes that.
   X_STATE_UNDECLARED: 500,
+  // A sealed column named where the database would compare it, or in a view. Both are the app's
+  // own declaration or call, never the caller's input — the same shelf as the two above.
+  X_ENTITY_SEALED_PREDICATE: 500,
+  X_ENTITY_SEALED_IN_VIEW: 500,
   // @ultimat3/db — the constraints a request trips, both 409. db's own `fix:` for the unique
   // violation says "answer 409, which is what a raced signup is", and `X_ENTITY_DUPLICATE` — the
   // same event one layer up — is 409 above; a foreign key rides with it because both halves of it
@@ -313,6 +323,12 @@ export const ERROR_STATUS = {
   // reaching `formatDate` / `formatMoney` / `describeCron`. Those raised it and answered 500,
   // paging the on-call for a string the caller typed.
   X_LOCALE_INVALID: 400,
+  // @ultimat3/core — `seal()` / `open()`. All three are reachable from a request (a sealed column
+  // read inside an action) and none is the caller's doing: the deploy has no key, the ring lost a
+  // retired key, or a stored value did not authenticate. 500, stated rather than defaulted.
+  X_SEAL_INVALID: 500,
+  X_SEAL_KEY_MISSING: 500,
+  X_SEAL_KEY_UNKNOWN: 500,
   // @ultimat3/money — a well-formed code this process carries no row for. The currency table is
   // OPEN (`registerCurrency`), and every surface between the wire and the throw accepts any
   // `^[A-Z]{3}$`: `@ultimat3/schema`'s `CURRENCY_CODE_PATTERN`, the OpenAPI `pattern` emitted from
@@ -457,6 +473,12 @@ export const ERROR_STATUS = {
   X_RECORD_REJECTED: 500,
   X_SYNC_UNCONFIGURED: 500,
   X_INTERNAL: 500,
+  // @ultimat3/jobs — the job is running and cannot be removed
+  X_JOB_NOT_REMOVABLE: 409,
+  // @ultimat3/jobs — the job is not waiting on its run time
+  X_JOB_NOT_PROMOTABLE: 409,
+  // @ultimat3/jobs — a job list page was asked for outside its bounds
+  X_JOB_PAGE_INVALID: 400,
   // The keys are LITERAL — deliberately not `Readonly<Record<string, number>>`, which is what the
   // annotation used to say. This table is the closed one, so `ERROR_STATUS.X_QUERY_NOT_PAGABLE`
   // has to be a compile error rather than an `undefined` a test then asserts `toBeNumber()` on.

package/src/hooks.ts

@@ -3,7 +3,7 @@
 // be imported here), and — a seam of a different kind, deciding nothing — what a dev diagnostic
 // found. All three are declared structurally, which keeps the import boundary intact and keeps
 // the pipeline testable.
-import type { Actor } from '@ultimat3/core';
+import type { Actor, UltimateError } from '@ultimat3/core';
 import type { RequestContext } from './context';
 import type { OverlayNotice } from './overlay';
 import type { UltimateRequest } from './request';
@@ -51,6 +51,17 @@ export interface ServerHooks {
     status: number,
     ctx: RequestContext,
   ) => Promise<string | undefined> | string | undefined;
+  /**
+   * Why nothing is routed at this path, when a higher tier knows more than "no route". Consulted
+   * ONLY on a miss — never for a matched route, a refused method or an unreadable path — and the
+   * error it returns is thrown in place of `X_ROUTE_NOT_FOUND`; `undefined` keeps the plain miss.
+   * `@ultimat3/action` answers here for a path that is one of its actions under a path style this
+   * server does not serve.
+   *
+   * Synchronous and given only the request line: a miss is reached by any anonymous caller, so
+   * what runs on it must not read a body, a session or a database.
+   */
+  readonly explainMiss?: (method: string, pathname: string) => UltimateError | undefined;
 }
 
 export type Authenticator = NonNullable<ServerHooks['authenticate']>;

package/src/stages.ts

@@ -181,7 +181,9 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
       if (routed instanceof Response) return routed;
       const match = matchRoute(input.table, ctx.method, routed);
       if (!match.ok) {
-        if (match.reason === 'not-found') throw routeNotFound(ctx.method, pathname);
+        if (match.reason === 'not-found') {
+          throw hooks.explainMiss?.(ctx.method, pathname) ?? routeNotFound(ctx.method, pathname);
+        }
         if (match.reason === 'path-invalid') throw pathInvalid(pathname, match.segment);
         ctx.headers.set('allow', match.allow.join(', '));
         throw methodNotAllowed(ctx.method, pathname, match.allow);