@objectstack/types 17.2.0 → 17.3.0

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { TenancyPosture } from '@objectstack/spec/security';
 import { ErrorCode, ApiError, FieldErrorCode } from '@objectstack/spec/api';
+import { Logger } from '@objectstack/spec/contracts';
 
 /**
  * Degraded-boot reporting, shared by every subsystem that can be told to boot
@@ -44,6 +45,47 @@ import { ErrorCode, ApiError, FieldErrorCode } from '@objectstack/spec/api';
  */
 declare function emitDegradedBootBanner(message: string): void;
 
+/**
+ * [#11343 / #12751] Verified-email predicate over a stored `sys_user` row — a
+ * fail-closed ALLOW-LIST over the representations a driver may hand back for
+ * the `sys_user.email_verified` boolean column (JS `true`, SQLite `1`, and
+ * their stringified forms). Everything else — `false`/`0`, `null`, an ABSENT
+ * field on an imported/legacy row, or any representation not listed — reads
+ * as UNVERIFIED. Absent-means-unverified is deliberate: treating a missing
+ * column as verified would re-open the exact hole this predicate closes for
+ * every row that predates the column.
+ *
+ * ONE resolution, several consumers, by design (#12751) — and since the
+ * #11663 platform-admin re-anchor (leg L4) the walled platform-admin
+ * ELEVATION GATE this paragraph used to name first is RETIRED: under a
+ * walled posture `bootstrapPlatformAdmin` writes no grant row and elevates
+ * nobody, it reports. Standing is derived PER REQUEST instead — from a
+ * config-anchored verified email, or the legacy unscoped grant row — so the
+ * consumer set now includes the authorization derivation itself:
+ *
+ *  - `matchesConfiguredPlatformAdmin` (`@objectstack/core`
+ *    `security/platform-admin.ts`), read at the one derivation site
+ *    (`resolve-authz-context.ts` §6b-config), where an UNVERIFIED account
+ *    holding a declared address confers nothing — and, through it,
+ *    `plugin-auth`'s last-admin guard, whose administrator enumeration must
+ *    answer the same question the resolver does;
+ *  - `resolvePlatformAdminStanding` (`plugin-security`
+ *    `platform-admin-service.ts`), the read-only standing/audit answer the
+ *    walled boot reports from, and `isVerifiedPlatformOwnerRow` beside it
+ *    (`platform-owner-wall-bypass.ts`), the Layer 0 wall bypass;
+ *  - the walled owner-verification boot diagnostic (`plugin-auth`
+ *    `walled-owner-verification-path.ts`, where the check decides whether the
+ *    declared owner's account is already past needing a verification path).
+ *
+ * They must all answer "is this row verified?" identically — a drift is no
+ * longer just a boot warning forecasting a refusal that will not be made, it
+ * is a diagnostic, an audit surface or a guard disagreeing with who actually
+ * resolves PLATFORM_ADMIN on the next request. `@objectstack/types` is the
+ * shared home every one of those packages already resolves
+ * `OS_PLATFORM_OWNER_EMAIL` from (`env.ts`).
+ */
+declare function isEmailVerifiedUserRow(row: unknown): boolean;
+
 /**
  * Environment-variable helpers shared across `@objectstack/*` packages.
  *
@@ -142,6 +184,49 @@ declare function resolveMultiOrgEnabled(): boolean;
  * enforced is the `tenancy` service's answer (`isolationActive` / `degraded`).
  */
 declare function resolveTenancyPosture(): TenancyPosture;
+/**
+ * The env variable naming the deployment's PLATFORM OWNER account
+ * (#11184, the framework leg of cloud#1509).
+ *
+ * Exported as a constant so every message that names it quotes exactly one
+ * spelling: the walled boot guard in plugin-auth, and plugin-security's
+ * `bootstrapPlatformAdmin` — its fail-closed backstop for an undeclared or
+ * refused config, and the config-derived standing it logs beside it.
+ *
+ * ⚠️ That second site is no longer an ELEVATION refusal. Since the #11663
+ * platform-admin re-anchor (leg L4) the walled `bootstrapPlatformAdmin` writes
+ * no grant row and elevates nobody — it reports. Standing is derived PER
+ * REQUEST at `resolve-authz-context.ts` §6b-config, from a declared address
+ * held on a VERIFIED `sys_user` row.
+ */
+declare const PLATFORM_OWNER_EMAIL_ENV = "OS_PLATFORM_OWNER_EMAIL";
+/**
+ * [#11184 / cloud#1509] Resolve the env-declared platform OWNER email —
+ * `OS_PLATFORM_OWNER_EMAIL`.
+ *
+ * Under a WALLED tenancy posture (`group` / `isolated`) the "first registrant
+ * becomes owner/platform admin" bootstrap path is REMOVED (maintainer ruling
+ * 2026-08-23, verbatim: 「1509 选择 env 指定 owner 邮箱」): on a walled
+ * deployment with self-registration reachable, whoever curls the sign-up
+ * endpoint first would otherwise receive the cross-tenant `admin_full_access`
+ * grant — measured on a real walled SaaS in cloud#1509. Platform admin is
+ * granted ONLY to the account whose email matches this variable, and a walled
+ * posture with no value declared REFUSES STARTUP (fail-closed, same reasoning
+ * as {@link resolveTenancyPosture}'s throw and ADR-0093 D5) rather than
+ * silently reverting to first-registrant elevation.
+ *
+ * The `single` posture never consults this: "first user is owner" is ruled
+ * reasonable there and unchanged.
+ *
+ * Returns the operator's value trimmed, or `undefined` when unset/blank.
+ * Comparison against `sys_user.email` is the CONSUMER's job and must be
+ * case-insensitive (this resolver echoes what the operator typed so refusal
+ * messages can quote it verbatim).
+ *
+ * Reads `process.env` live on each call, through `globalThis` like the other
+ * resolvers here (this package targets non-Node runtimes too).
+ */
+declare function resolvePlatformOwnerEmail(): string | undefined;
 /**
  * Escape hatch for the degraded-tenancy boot guard (ADR-0093 D5).
  *
@@ -257,6 +342,27 @@ declare function resolveMcpStdioAutoStart(): {
  * Deployments that let users self-create orgs SHOULD set a generous cap.
  */
 declare function resolveOrgLimit(): number | undefined;
+/**
+ * Maximum number of MEMBERS a single organization may hold, from
+ * `OS_ORG_MEMBERSHIP_LIMIT`. A different question from {@link resolveOrgLimit},
+ * which caps how many organizations one user may create.
+ *
+ * Unset → `undefined`, which the auth plugin forwards as "no cap". That default
+ * is a product decision, not an omission: seat entitlements are metered on AI
+ * seats, and plain membership is not a billed axis, so nothing about the
+ * platform wants a member ceiling.
+ *
+ * It has to be stated explicitly because better-auth's organization plugin
+ * substitutes a vendor default of **100** for an absent `membershipLimit`
+ * (`count >= (membershipLimit || 100)`), which reaches the operator as
+ * `Organization membership limit reached` — a refusal nobody in this codebase
+ * ever chose, on an axis the product does not limit.
+ *
+ * A deployment that DOES want a ceiling (a pilot, a trial tenant) sets a
+ * positive integer here. Non-positive or unparsable values read as unset rather
+ * than as zero: a typo must not be the thing that locks an organization.
+ */
+declare function resolveOrgMembershipLimit(): number | undefined;
 /**
  * SINGLE decision point for "is pinyin search recall on?" (#2486).
  *
@@ -667,7 +773,8 @@ declare function sendOk(res: EnvelopeResponse, data: unknown, status?: number):
  * ## `extra` is `ApiError`'s own optional fields, not a `Record`
  *
  * Merged into `error`, and typed as exactly what `ApiErrorSchema` declares
- * beside `code` and `message` — `details`, `category`, `requestId`, `httpStatus`.
+ * beside `code` and `message` — `details`, `category`, `requestId`,
+ * `httpStatus`, `declaredCode`, `userMessage`.
  * `details` is the slot for structured context: `package-routes` puts a partial
  * delete's per-item failures there, `settings-routes` the whole
  * `SettingsActionResult`.
@@ -683,8 +790,80 @@ declare function sendOk(res: EnvelopeResponse, data: unknown, status?: number):
  * Closing it at the shared builder is the part that lasts: an undeclared sibling
  * is now a compile error in every module at once, rather than a key that quietly
  * evaporates at the schema boundary in whichever module reintroduces it.
+ *
+ * ## `declaredCode` — declared by the schema, barred by this writer
+ *
+ * ADR-0112's 2026-08-17 amendment (#9106, extended to the flat `/data` door by
+ * #9232) rules the demote at EVERY door: `code` stays the closed vocabulary,
+ * and a thrown code that is not a member is demoted to a declared sibling,
+ * `ApiError.declaredCode` — the open, author-authored channel that carries a
+ * metadata app's OWN `.code` across the QuickJS boundary (#7867) and onto the
+ * wire.
+ *
+ * `ApiErrorSchema` has declared that field since #9106 and the flat door emits
+ * it, but it was absent from the `Pick` above — so it was a COMPILE ERROR for
+ * any route answering the NESTED envelope to pass one, and every such route
+ * dropped the producer's spelling. Nothing invalid shipped (the closed `code`
+ * still carried the derived member), which is what made the loss silent and
+ * one-directional: the author's spelling gone, and a consumer told by the ADR
+ * to read `declaredCode` finding nothing there. Declared-but-unemittable is a
+ * `declared = enforced` gap, and admitting the field closes it at the ONE
+ * writer rather than in each module that later notices.
+ *
+ * ⛔ Presence MEANS demotion, and this writer does not re-derive that — the
+ * CALLER does, with `demotedDeclaredCode` (`thrown-http-error.ts`, one file
+ * over), exactly as the flat door's `thrownCodeFields` already does. That
+ * helper answers `undefined` when the producer's spelling IS the vocabulary
+ * member already sitting in `code`, which is what stops a registered refusal
+ * from carrying two spellings of one fact — `ApiErrorSchema.declaredCode`'s
+ * documented invariant. Passing a raw `thrown.declaredCode` re-opens exactly
+ * that, and no type here can catch it: vocabulary and position stay two
+ * decisions (#9232), so the demotion rule stays with the resolver that owns
+ * it rather than being restated in the envelope writer.
+ *
+ * ## `userMessage` — the second declared channel, and why this `Pick` stays explicit
+ *
+ * #9934's producer-side opt-in (maintainer ruling 2026-08-19 on objectui#5210,
+ * option 1) declares `ApiError.userMessage`: the text a producer marked, AT
+ * THROW TIME, as addressed to the END USER. Presence IS the marking — a
+ * consumer that sees the field renders it verbatim and keeps its generic
+ * substitution (#3821) for everything unmarked.
+ *
+ * The schema declared it and this writer barred it, with the same
+ * one-directional silence `declaredCode` had: the other two doors already emit
+ * it — the flat `/data` door through `withDeclaredUserMessage`
+ * (`rest/error-response.ts`) and the dispatcher door through
+ * `thrown.userMessage` (`runtime/http-dispatcher.ts`) — while a route
+ * answering the NESTED envelope could not, so an author's deliberate,
+ * localized refusal text was dropped on this door alone. Nothing invalid
+ * shipped; the text simply was not there.
+ *
+ * The channel is live on both ends, which is what makes admitting it a repair
+ * rather than a new declared-but-dead surface: a hook sets it at throw time —
+ * host-side, or a metadata app's sandboxed body whose `e.userMessage` crosses
+ * the QuickJS boundary through `SANDBOX_ERROR_PASSTHROUGH`
+ * (`runtime/sandbox/quickjs-runner.ts`) — and `resolveThrownHttpError` already
+ * carries it onto `ThrownHttpError` for every caller of the shared resolver.
+ *
+ * ⛔ Unlike `declaredCode`, this field carries NO invariant for the caller to
+ * re-derive. `declaredCode`'s presence MEANS demotion, so its caller passes
+ * `demotedDeclaredCode(thrown)` rather than the raw field; `userMessage`'s
+ * presence means only that the producer opted in, and `declaredUserMessage`
+ * has already decided that (a non-empty string, or nothing at all). The caller
+ * passes `thrown.userMessage` straight through, exactly as the dispatcher door
+ * does.
+ *
+ * That difference is why `extra` stays an explicit `Pick` rather than becoming
+ * "every optional field of `ApiError`". A derivation would admit each future
+ * optional on the day it lands, with nobody asked whether that channel should
+ * cross this door or what obligation it hands the caller — and the two fields
+ * above needed opposite answers to exactly that question. Recorded for the next
+ * reader, because it is the honest cost: with `userMessage` admitted the `Pick`
+ * now names ALL SIX of `ApiError`'s optional fields, so this gate has to date
+ * rejected none. What it has produced is a different caller obligation per
+ * field, which a derivation cannot produce at all.
  */
-declare function sendError(res: EnvelopeResponse, status: number, code: ErrorCode, message: string, extra?: Pick<ApiError, 'category' | 'httpStatus' | 'details' | 'requestId'>): void;
+declare function sendError(res: EnvelopeResponse, status: number, code: ErrorCode, message: string, extra?: Pick<ApiError, 'category' | 'httpStatus' | 'details' | 'requestId' | 'declaredCode' | 'userMessage'>): void;
 
 /**
  * The ONE rule for "what HTTP answer does a THROWN error declare?" (#8016).
@@ -756,6 +935,14 @@ declare function sendError(res: EnvelopeResponse, status: number, code: ErrorCod
  * answers come from ONE function, which is what keeps agreement a construction
  * rather than two suites agreeing about literals.
  *
+ * [#12509] And the channel has a SCOPE, ruled 2026-08-27 (option D): on a 5xx
+ * the producer did not declare, the demoted spelling came off an undeclared
+ * producer and is withheld with the prose, while an author-declared code
+ * survives. The discriminator is {@link serverFaultProvenance} — one function,
+ * read by {@link demotedDeclaredCode}, which every door already calls, so no
+ * registrar carries a variant. Read that function's note for why the status
+ * channel is the only honest signal here.
+ *
  * ## What this deliberately does NOT decide
  *
  *  - **Message disclosure.** A 5xx message may name physical tables or carry a
@@ -814,6 +1001,11 @@ interface ThrownHttpError {
      * every door (#9106) — but for the wire's `declaredCode` channel when the
      * spelling is not a vocabulary member ({@link demotedDeclaredCode}). See the
      * module note on why there are two.
+     *
+     * ⚠️ This field records what the producer WROTE, not what a boundary may
+     * emit: since #12509 a demoted spelling is withheld on an undeclared 5xx.
+     * ⛔ Read {@link demotedDeclaredCode}, never this field, when deciding what
+     * goes on a wire.
      */
     declaredCode?: string;
     /** The thrown message, UNSANITISED — see the module note on disclosure. */
@@ -888,21 +1080,206 @@ declare function resolveThrownHttpError(error: unknown, fallbackStatus?: number)
  * consumer keeps its generic substitution (#3821 preserved by construction).
  */
 declare function declaredUserMessage(error: unknown): string | undefined;
+/**
+ * [#12509] WHO named this 5xx — the producer, or this resolver's fallback.
+ * `undefined` for anything below 500, where nothing is sanitised at all.
+ *
+ * This is the ONE definition of the distinction ADR-0112's 5xx-sanitisation
+ * scope turns on (maintainer ruling 2026-08-27, option D), and it exists as a
+ * named function rather than as an inline conjunction because TWO rules read
+ * it and they read opposite limbs:
+ *
+ *  - `'undeclared'` — the throw declared no HTTP answer, so
+ *    {@link ThrownHttpError.status} is the caller's `fallbackStatus` and
+ *    EVERYTHING this resolver picked up off that throw is the producer's
+ *    internals rather than an answer it composed. A driver errno
+ *    (`SQLITE_ERROR`, `42P01`) is the measured case, and it is why
+ *    {@link demotedDeclaredCode} withholds the code here: the spelling names
+ *    the backend, which is one of the two disclosures the 5xx message
+ *    withhold exists to prevent (`looksLikeInternalErrorLeak`; the other,
+ *    identifiers, is already covered).
+ *  - `'declared'` — the producer named a 5xx ITSELF, so its code is authored
+ *    and survives. #11718's `{ status: 503, code: 'SERVICE_UNAVAILABLE' }`
+ *    relay is this limb, and so is a metadata app's own 5xx refusal spelling
+ *    (#7867), which the ADR-0112 amendment wrote `declaredCode` for.
+ *
+ * ⚠️ The DISCRIMINATOR is the status channel, not the code's shape. There is
+ * no other structural signal: a driver errno and an app's own spelling both
+ * arrive on `.code` as a plain string, so anything that told them apart by
+ * LOOKING at the string would be a heuristic over an open channel — the
+ * consumer-side tolerance ADR-0112 exists to forbid, and unfalsifiable besides
+ * (nothing stops an app from spelling `SQLITE_ERROR`). The cost of the
+ * structural answer is stated rather than hidden: a producer that spells a
+ * code but declares NO status loses that code on a 5xx. It keeps it by
+ * declaring the status it means, which is the shape the ADR already asks for.
+ *
+ * ⛔ NOT gated on whether `looksLikeInternalErrorLeak` actually fired on the
+ * message. That predicate is a heuristic over a DIFFERENT channel, and gating
+ * here on it would leak the errno for exactly the dialects whose prose the
+ * heuristic misses — the ceiling `sendThrownError`'s note records. The 5xx
+ * sanitisation REGIME is the condition, not one of its two outcomes.
+ *
+ * ⭐ #12281 — the prose axis of the same 2026-08-27 ruling — is the
+ * `'declared'` limb of this same function: the dispatcher door withholds the
+ * message of EVERY declared 5xx, aligning to `/data`. It is a separate card
+ * with its own measurement-first step, so nothing here applies it; this
+ * function is the shape it will read rather than a second copy it would have
+ * to grow.
+ */
+type ServerFaultProvenance = 'declared' | 'undeclared';
+/** See {@link ServerFaultProvenance}. */
+declare function serverFaultProvenance(thrown: ThrownHttpError): ServerFaultProvenance | undefined;
 /**
  * The producer's spelling a boundary should surface as the wire's
  * `declaredCode` beside the closed `code` — or `undefined` when there is
  * nothing to surface (#9106).
  *
  * Present exactly when the throw spelled a code that did NOT survive into
- * {@link ThrownHttpError.code} — i.e. the demote happened. A registered code
- * is already in `code`, so emitting it again would put two spellings of one
- * fact on every refusal; a throw with no code has nothing to declare. Spelled
- * once here rather than as three `!==` comparisons at three exits, so
- * "presence means demotion" (`ApiErrorSchema.declaredCode`'s documented
- * semantics) has one definition.
+ * {@link ThrownHttpError.code} — i.e. the demote happened — AND the answer is
+ * not an undeclared server fault. A registered code is already in `code`, so
+ * emitting it again would put two spellings of one fact on every refusal; a
+ * throw with no code has nothing to declare. Spelled once here rather than as
+ * three `!==` comparisons at three exits, so "presence means demotion"
+ * (`ApiErrorSchema.declaredCode`'s documented semantics) has one definition.
+ *
+ * [#12509] The withhold limb, ruled 2026-08-27 (option D): on a 5xx the
+ * producer did NOT declare, the spelling this resolver demoted came off an
+ * undeclared producer — a driver errno, measured on the wire at three of this
+ * repo's doors — and it is withheld along with the prose. An AUTHOR-declared
+ * code survives at every status. The judgement lives in
+ * {@link serverFaultProvenance}; it is applied HERE, in the one read every
+ * boundary already makes, so all of them inherit it without a door growing a
+ * rule of its own. ⛔ Do not re-derive the condition at a door: a per-door
+ * variant is the divergence this channel has now been repaired for twice.
  */
 declare function demotedDeclaredCode(thrown: ThrownHttpError): string | undefined;
 
+/**
+ * [#14310] The one rule for "a 5xx must never be silent", shared by every
+ * transport that turns a fault into an HTTP envelope.
+ *
+ * ## The hole this closes
+ *
+ * A 500 that leaves no server-side line is diagnosed from the browser or not
+ * at all. Measured on `main`: a plain `Error` thrown out of a dispatcher route
+ * answered `500 INTERNAL_ERROR` with **zero** log records at any level — the
+ * only evidence was the client's console and the response body. The failure
+ * that motivated this had been reachable for a week and nobody saw it, which
+ * is AGENTS.md "Route & surface ownership §3 — absence must be loud" inverted.
+ *
+ * The reporting that DID exist was not a substitute, in two independent ways:
+ *
+ *  1. `ErrorReporter.captureException` is an APM channel and defaults to
+ *     `NoopErrorReporter`. A dev server — the surface an operator actually
+ *     watches — wires no reporter, so the capture was a no-op every time.
+ *  2. It is fed by `res.__obsRecordedError`, which only the THROWN exit sets.
+ *     A dispatcher route that catches its own fault and RETURNS a 5xx envelope
+ *     (`deps.errorFromThrown`, which is how every `/packages` handler answers)
+ *     records nothing, so even a wired reporter never saw those.
+ *
+ * This module is the log half, and it is deliberately not the reporter half:
+ * an APM capture is opt-in telemetry, a log line is the operator's floor.
+ *
+ * ## Why it lives here
+ *
+ * Same argument, and the same package, as `resolveThrownHttpError` one file
+ * over: a rule two doors must agree on cannot live inside one of them.
+ * `@objectstack/runtime` depends on `@objectstack/rest`, so an import between
+ * the two doors could only ever point one way — which is exactly why the
+ * "what status does this throw mean" rule was moved here in #8016. "Is this
+ * answer worth an operator's attention" is the same kind of rule, read by the
+ * same two doors, so it gets the same home rather than a second one.
+ *
+ * Living beside {@link sendError} is what makes the REST side automatic: that
+ * writer is the single exit for every nested-envelope 5xx, so the direct-mount
+ * registrars need no per-door call and cannot forget one. Each transport logs
+ * at its own single exit, so a fault costs one line and never two.
+ *
+ * ## `error` level, and why that clears the default
+ *
+ * The requirement is that the line survives `--log-level`'s DEFAULT. The CLI
+ * default is `warn` (`packages/cli/src/utils/log-level.ts`) and `error` (40)
+ * outranks `warn` (30) in `LEVEL_PRIORITY`, so an `error` record passes the
+ * default threshold without any bypass of the level system. An operator who
+ * asks for `--log-level silent` still gets silence: that is a deliberate
+ * instruction, not the default this issue is about.
+ *
+ * ## 5xx only
+ *
+ * 4xx stays quiet, deliberately and at this one gate rather than at each call
+ * site. A client error is the caller's mistake and the response already
+ * explains it; logging them is how the `/meta` `?state=draft` probe once
+ * printed 45 stack traces in one browsing session. `isServerFault` is the
+ * whole rule: at or above 500.
+ */
+
+/** The request coordinates an operator needs to find the failing call. */
+interface ServerFaultRequest {
+    /** HTTP method, e.g. `GET`. */
+    method?: string;
+    /** Request path as served, e.g. `/api/v1/packages`. */
+    path?: string;
+    /** Correlation id — the `X-Request-Id` echoed on the response. */
+    requestId?: string;
+}
+/** One fault, as the emitting door knows it. */
+interface ServerFaultLogInput {
+    /** The HTTP status about to be written. Below 500 nothing is logged. */
+    status: number;
+    /**
+     * The original thrown value, when the door still holds it. Carries the
+     * stack; the wire body never does, because a 5xx message is withheld.
+     */
+    error?: unknown;
+    /** The envelope's `code`, when the door resolved one. */
+    code?: string;
+    /**
+     * The message to print when {@link ServerFaultLogInput.error} carries
+     * none — a declared fault built from a string rather than a throw.
+     */
+    message?: string;
+    /** Where the call came in. */
+    request?: ServerFaultRequest;
+}
+/** The prefix every fault line carries, so an operator can grep one token. */
+declare const SERVER_FAULT_LOG_PREFIX = "[5xx]";
+/**
+ * THE predicate. A response is a server fault worth a line exactly when its
+ * status is 5xx. Exported so a door can decide without restating `>= 500`.
+ */
+declare function isServerFault(status: number): boolean;
+/**
+ * The human half of the line: `[5xx] 500 GET /api/v1/packages — <message>`.
+ * Split out so both the emitted record and a test can name the same string.
+ */
+declare function serverFaultLogMessage(input: ServerFaultLogInput): string;
+/**
+ * The structured half. `status`/`code`/`requestId` are what a log search keys
+ * on; `method`/`path` repeat the message's coordinates because a JSON sink
+ * indexes fields, not prose.
+ */
+declare function serverFaultLogMeta(input: ServerFaultLogInput): Record<string, unknown>;
+/**
+ * Emit EXACTLY ONE `error`-level record for a 5xx, or nothing at all.
+ *
+ * Returns whether a record was emitted, so a caller that must not double-log
+ * can branch on the answer rather than re-deriving the 5xx test.
+ *
+ * `logger` is optional: a door with no injected logger falls back to
+ * `console.error`, because the point of this function is that the line exists
+ * even on a surface nobody configured. Emission never throws — a logging
+ * failure must not become a second fault on top of the one being reported.
+ */
+declare function logServerFault(input: ServerFaultLogInput, logger?: Logger): boolean;
+/**
+ * Read request coordinates off whatever request object the transport hands
+ * the door. Adapters disagree on the spelling (`path` / `url` /
+ * `originalUrl`), and the request id may be on the object (set by
+ * `instrumentRouteHandler`) or only on the incoming header — so both are
+ * read here, once, instead of at each call site.
+ */
+declare function describeFaultRequest(req: unknown): ServerFaultRequest;
+
 /** The HTTP status a validation failure maps to when the error names none. */
 declare const VALIDATION_FAILED_STATUS = 400;
 interface ValidationFailureDetails {
@@ -1154,6 +1531,153 @@ declare function isUniqueViolationError(error: unknown): boolean;
  */
 declare function uniqueViolationColumn(error: unknown): string | undefined;
 
+/**
+ * [#13438] The physical table a driver's statement TARGETED, declared on the
+ * error envelope by the producer that knows it.
+ *
+ * `readObject` closed the #13324 hole for callers that can name what they read
+ * — and left a residual one layer down. A caller names its OBJECT (the API
+ * name); a driver compiles the statement against the PHYSICAL table, and for a
+ * federated object (ADR-0015, `external.remoteName`) those are two different
+ * names. `driver-sql` reads `crm_order` from `legacy_orders`, so when that
+ * remote is genuinely absent the dialect phrase names `legacy_orders`, the
+ * caller names `crm_order`, and the comparison called a real missing table
+ * "about something else" — loud, for the one case the licence was built for.
+ *
+ * Nothing at a call site can fold that away: the mapping lives on the driver
+ * instance, and asking every caller to consult it is the guessing this channel
+ * exists to remove (maintainer ruling 2026-09-01, option 2 on the card). So the
+ * fact is declared where it is known — the driver that composed the envelope
+ * stamps the table its statement targeted onto it — and the predicate PREFERS
+ * a declared table over the caller-supplied `readObject`. The caller never
+ * needs to know a federated object's remote name, and a driver that declares
+ * nothing gets exactly the #13324 behaviour.
+ *
+ * A symbol key from the global registry, held non-enumerable: the carrier
+ * discipline `driver-sql` already applies to its withheld-diagnostic symbols
+ * and to the envelope's own `cause`. Readable by code; invisible to
+ * `JSON.stringify`, `{ ...err }`, `Object.keys`, `for…in` and the
+ * structured-clone boundary — so the physical table name, the very thing the
+ * envelope's composed message withholds, can never ride back onto a wire that
+ * serialises the error. `Symbol.for` so a duplicated copy of this package
+ * resolves the same key.
+ *
+ * ⚠️ A declaration is EVIDENCE, so it also narrows the one-argument form: an
+ * envelope declaring `legacy_orders` whose dialect phrase names some other
+ * relation reads not-benign even with no `readObject` — the driver supplied
+ * the fact the caller could not. That is the #13324 verdict reached without
+ * the caller's help, in the direction the module docblock calls cheap.
+ */
+declare const DRIVER_TARGETED_TABLE: symbol;
+/**
+ * Declare, on `error`, the physical table the statement that raised it targeted.
+ *
+ * The producer's half of {@link DRIVER_TARGETED_TABLE} — for a driver composing
+ * an error envelope over a dialect failure. `table` is the name the statement
+ * was compiled against (a federated object's `external.remoteName`, otherwise
+ * the object's own table), bare: the comparison folds away schema and database
+ * qualifiers on both sides, so none is needed here.
+ *
+ * Non-enumerable and non-writable, and the FIRST declaration wins: the actor
+ * that compiled the statement is the one that knows its target, and a later,
+ * more distant wrapper re-declaring it would be re-introducing the guess. (The
+ * predicate applies the same rule across a `cause` chain: the declaration
+ * NEAREST the dialect phrase is the one compared.) An empty or non-string
+ * `table` declares nothing — silently, because this runs on an error path
+ * where a thrown `TypeError` would replace the envelope it was meant to
+ * annotate; the predicate then falls back to `readObject` exactly as if no
+ * driver had spoken.
+ *
+ * @returns `error`, for chaining.
+ */
+declare function declareTargetedTable<E extends object>(error: E, table: string): E;
+/**
+ * The table `error` declares its statement targeted, or `null` when it declares
+ * none — the reading half of {@link declareTargetedTable}. Tolerant of bare
+ * input: any non-object, and any object without a non-empty string under the
+ * key, is "no declaration".
+ */
+declare function targetedTableOf(error: unknown): string | null;
+/**
+ * Is this DDL error the benign "already provisioned" case?
+ *
+ * @param error - The value thrown by `syncSchema()` (or any DDL call).
+ * @param depth - Internal `cause`-chain recursion counter; callers pass nothing.
+ * @returns `true` only when the error positively identifies as
+ *          table/column/index-already-exists. Anything else — including an
+ *          unrecognised error, `undefined`, or a permission/connection failure —
+ *          returns `false` and MUST be reported loudly by the caller.
+ */
+declare function isSchemaAlreadyExistsError(error: unknown, depth?: number): boolean;
+/**
+ * Is this READ error the benign "table has not been provisioned yet" case?
+ *
+ * The only failure that licenses a caller to treat an empty table as the truth
+ * — there are no rows, so there is nothing to be inconsistent with. A
+ * connection drop, a timeout, a permission denial or a query error all mean the
+ * rows may well exist and simply were not seen; those return `false` and the
+ * caller must report the consequence and give up rather than compute an answer
+ * from data it never read (#4825).
+ *
+ * A failure about a **column** of a relation is never this case, in either of
+ * Postgres' two phrasings — the relation is right there in the message because
+ * it exists (#6347). See {@link MISSING_TABLE}'s `excludes`.
+ *
+ * [#13324] Neither is a failure that names a **different relation**, and that
+ * one cannot be seen without `readObject`. The message test asks what the
+ * phrase LOOKS like and never which table it names, so a read of a view whose
+ * base table has been dropped — `no such table: main.<base>`, measured on
+ * libsql for a view that itself exists — answered benign for a relation that is
+ * present and may be backed by rows. Naming the read closes it: the phrase must
+ * be about the table the caller asked for, or it is not evidence about it.
+ *
+ * Pass `readObject` from every in-repo call site. It is **optional** so that
+ * omitting it is exactly the pre-#13324 behaviour rather than a new loud
+ * failure — this is a published export (`@objectstack/types`, and still
+ * `@objectstack/metadata/errors` by re-export), and a required parameter would
+ * be a breaking change to it. The cost of the choice
+ * is that the narrowing is opt-in per call site: a new caller that forgets it
+ * silently gets the old, wider verdict.
+ *
+ * [#13440] That last sentence is no longer only a warning. In-repo callers are
+ * held to it by `driver-error-classification.callers.test.ts`, which walks every
+ * TypeScript source under `packages/` and fails any call of this function that
+ * omits `readObject` or passes it as `undefined`/`null`. The exemption is this
+ * module's own contract tests, which exercise the one-argument PUBLISHED form on
+ * purpose; read that file's header before adding to the exemption, because
+ * widening it is how the enforcement becomes prose again. External consumers are
+ * untouched: the signature below is unchanged, and the gate binds only callers
+ * inside this repository.
+ *
+ * [#13438] `readObject` is the caller's name for what it read, and for a
+ * federated object (ADR-0015) that is not the name the driver put in the
+ * statement — `crm_order` reads `external.remoteName: 'legacy_orders'`, so a
+ * genuinely absent remote raised a phrase naming `legacy_orders` against a
+ * caller naming `crm_order`, and the #13324 comparison read it loud. A driver
+ * that knows the table it targeted now DECLARES it on the envelope
+ * ({@link declareTargetedTable}), and a declared table is preferred over
+ * `readObject` outright: the phrase is compared against the declared name, and
+ * the caller-supplied one is not consulted at that node or below it. Absent a
+ * declaration the comparison is the #13324 one, unchanged. Two consequences,
+ * both pinned: a genuinely absent federated remote reads benign again without
+ * the caller learning the mapping; and — because a declaration is evidence the
+ * caller did not have — an envelope whose phrase names a relation other than
+ * its declared table reads NOT benign even through the one-argument form.
+ *
+ * @param error - The value thrown by a driver/engine read (`find`, `findOne`, …).
+ * @param readObject - The object/table whose emptiness the caller is about to
+ *          treat as the truth — its own API name is fine, the comparison folds
+ *          away schema qualifiers, the legacy `ns__short` prefix and case.
+ *          Omitted (or not a string) means "cannot say", never "be loud".
+ *          Superseded, at any node of the `cause` chain that declares the
+ *          table its statement targeted, by that declaration (#13438).
+ * @param depth - Internal `cause`-chain recursion counter; callers pass nothing.
+ * @returns `true` only when the error positively identifies as
+ *          table/relation-does-not-exist **for the table that was read** —
+ *          the declared target where a driver supplied one, else `readObject`.
+ */
+declare function isMissingTableError(error: unknown, readObject?: string, depth?: number): boolean;
+
 /**
  * Whether a thrown driver error says the `ON CONFLICT` target it was given is
  * backed by no PRIMARY KEY or UNIQUE index.
@@ -1407,4 +1931,4 @@ interface RuntimePlugin {
     onStart?: (ctx: RuntimeContext) => void | Promise<void>;
 }
 
-export { type EnvelopeResponse, GLOBAL_UNIQUE_CONFIRMATION_REQUIRED, GLOBAL_UNIQUE_ISOLATED_PRESCRIPTION, type GlobalUniqueAttestation, type GlobalUniqueFinding, type IKernel, INTERNAL_ERROR_MESSAGE, type KeysetPageQuery, type KeysetWalk, type KeysetWalkOptions, type RuntimeContext, type RuntimePlugin, type ThrownHttpError, VALIDATION_FAILED_STATUS, type ValidationFailureDetails, _resetEnvDeprecationWarnings, buildGlobalUniqueStopMessage, collectConfiguredLocales, collectGlobalUniques, declaredIndexUniqueIsGlobal, declaredUserMessage, declaresServerFault, demotedDeclaredCode, describeGlobalUniqueFinding, emitDegradedBootBanner, fieldUniqueIsGlobal, fieldsFromZodIssues, globalUniqueFindingId, isMcpServerEnabled, isModuleNotFoundError, isPlatformOwnedObject, isRelationSubObjectPhrase, isUnbackedConflictTargetError, isUniqueViolationError, keysetWalk, looksLikeInternalErrorLeak, matchMissingColumnOfRelation, postureGatesGlobalUniques, readEnvWithDeprecation, recordGlobalUniqueAttestation, resolveAllowDegradedTenancy, resolveAllowDevPlugin, resolveAllowDriverConnectFailure, resolveMcpStdioAutoStart, resolveMultiOrgEnabled, resolveOrgLimit, resolveSandboxTimeoutMs, resolveSearchPinyinEnabled, resolveTenancyPosture, resolveThrownHttpError, sendError, sendOk, stampSearchPinyinEnabled, unconfirmedGlobalUniques, uniqueViolationColumn, validationFailure, validationFailureDetails };
+export { DRIVER_TARGETED_TABLE, type EnvelopeResponse, GLOBAL_UNIQUE_CONFIRMATION_REQUIRED, GLOBAL_UNIQUE_ISOLATED_PRESCRIPTION, type GlobalUniqueAttestation, type GlobalUniqueFinding, type IKernel, INTERNAL_ERROR_MESSAGE, type KeysetPageQuery, type KeysetWalk, type KeysetWalkOptions, PLATFORM_OWNER_EMAIL_ENV, type RuntimeContext, type RuntimePlugin, SERVER_FAULT_LOG_PREFIX, type ServerFaultLogInput, type ServerFaultProvenance, type ServerFaultRequest, type ThrownHttpError, VALIDATION_FAILED_STATUS, type ValidationFailureDetails, _resetEnvDeprecationWarnings, buildGlobalUniqueStopMessage, collectConfiguredLocales, collectGlobalUniques, declareTargetedTable, declaredIndexUniqueIsGlobal, declaredUserMessage, declaresServerFault, demotedDeclaredCode, describeFaultRequest, describeGlobalUniqueFinding, emitDegradedBootBanner, fieldUniqueIsGlobal, fieldsFromZodIssues, globalUniqueFindingId, isEmailVerifiedUserRow, isMcpServerEnabled, isMissingTableError, isModuleNotFoundError, isPlatformOwnedObject, isRelationSubObjectPhrase, isSchemaAlreadyExistsError, isServerFault, isUnbackedConflictTargetError, isUniqueViolationError, keysetWalk, logServerFault, looksLikeInternalErrorLeak, matchMissingColumnOfRelation, postureGatesGlobalUniques, readEnvWithDeprecation, recordGlobalUniqueAttestation, resolveAllowDegradedTenancy, resolveAllowDevPlugin, resolveAllowDriverConnectFailure, resolveMcpStdioAutoStart, resolveMultiOrgEnabled, resolveOrgLimit, resolveOrgMembershipLimit, resolvePlatformOwnerEmail, resolveSandboxTimeoutMs, resolveSearchPinyinEnabled, resolveTenancyPosture, resolveThrownHttpError, sendError, sendOk, serverFaultLogMessage, serverFaultLogMeta, serverFaultProvenance, stampSearchPinyinEnabled, targetedTableOf, unconfirmedGlobalUniques, uniqueViolationColumn, validationFailure, validationFailureDetails };