@objectstack/types 17.0.0-rc.6 → 17.1.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { TenancyPosture } from '@objectstack/spec/security';
-import { ErrorCode, ApiError } from '@objectstack/spec/api';
+import { ErrorCode, ApiError, FieldErrorCode } from '@objectstack/spec/api';
 
 /**
  * Degraded-boot reporting, shared by every subsystem that can be told to boot
@@ -391,12 +391,18 @@ declare const INTERNAL_ERROR_MESSAGE = "Internal server error";
  *
  * Matches: dialect error codes (`SQLSTATE`, `sqlite_*`), bare statements
  * (a message that *starts* as `SELECT`/`INSERT INTO`/`UPDATE`/`DELETE FROM` —
- * drivers prefix the offending SQL to their message), and constraint-violation
- * dumps, which name physical tables and columns.
+ * drivers prefix the offending SQL to their message), constraint-violation
+ * dumps, which name physical tables and columns, and the
+ * {@link DIALECT_LEAK_PHRASINGS} the list covers — the SQLite family, Postgres
+ * and, since #8739, MySQL/MariaDB. A dialect outside that coverage (MSSQL and
+ * Oracle are the standing examples) makes this return FALSE without meaning the
+ * text is safe; read {@link DIALECT_LEAK_PHRASINGS}' note before sizing
+ * anything on a `false`.
  *
  * Does NOT match ordinary business or validation messages, which is why the
- * statement forms are anchored with `startsWith`: a legitimate message may
- * *mention* "update" without being one.
+ * statement forms are anchored with `startsWith` and the dialect phrasings on
+ * the driver's template: a legitimate message may *mention* "update", or say
+ * "does not exist" about a business record, without being either.
  */
 declare function looksLikeInternalErrorLeak(message: string | undefined | null): boolean;
 /**
@@ -680,6 +686,283 @@ declare function sendOk(res: EnvelopeResponse, data: unknown, status?: number):
  */
 declare function sendError(res: EnvelopeResponse, status: number, code: ErrorCode, message: string, extra?: Pick<ApiError, 'category' | 'httpStatus' | 'details' | 'requestId'>): void;
 
+/**
+ * The ONE rule for "what HTTP answer does a THROWN error declare?" (#8016).
+ *
+ * A service or protocol throw that carries its own `.status` / `.statusCode`
+ * and its own semantic `.code` is a *refusal*, not a fault: the caller asked
+ * for something the platform will not do, and the honest answer is that status
+ * with that code. A throw carrying neither is a fault, and the honest answer is
+ * the caller's fallback — 500 `INTERNAL_ERROR` at an HTTP boundary.
+ *
+ * ## Why this is shared rather than restated per door
+ *
+ * `/api/v1/packages` has **two** HTTP doors. The runtime dispatcher's
+ * `HttpDispatcher.errorFromThrown` read `.status` first and answered `409
+ * DESTRUCTIVE_CHANGE` for a `metadata-protocol` refusal. The direct-mount REST
+ * registrar (`packages/rest/src/package-routes.ts`) had four catch-alls that
+ * answered `500 INTERNAL_ERROR` regardless — and *that* registrar mounts first
+ * in the production stack, so 500 was what production actually returned. One
+ * throw, two answers, and the wrong one was the live one (#8016).
+ *
+ * The rule therefore lives in ONE function that both doors call. It could not
+ * live in `packages/runtime`: `@objectstack/runtime` depends on
+ * `@objectstack/rest`, so the arrow only points one way and `errorFromThrown`
+ * is unreachable from the REST door by construction. `@objectstack/types`
+ * depends on nothing but `@objectstack/spec`, which is exactly why the other
+ * shared HTTP-boundary helpers already live here — `looksLikeInternalErrorLeak`
+ * ("do not ship driver internals to clients") and `sendOk`/`sendError` ("write
+ * the declared envelope"). "What status does this throw mean?" is the same kind
+ * of property: it belongs to the boundary, not to one router.
+ *
+ * ## Two spellings of the code, because the two envelopes are not equally closed
+ *
+ * {@link ThrownHttpError.code} is narrowed to `StandardErrorCode ∪
+ * ERROR_CODE_LEDGER` — the union `ApiErrorSchema` validates against — so a
+ * throw whose `.code` is not a registered member does not get to name itself;
+ * it falls to the code the status derives. That is the same rule
+ * `metadata-protocol`'s `toRowApiError` applies to a per-row batch error, and
+ * it is what lets `sendError`'s closed `ErrorCode` parameter be satisfied
+ * without a cast. The direct-mount REST door needs exactly this: its bodies are
+ * parsed against `BaseResponseSchema` by its own conformance suite, so an
+ * unregistered code there is a failing test, not a wire answer.
+ *
+ * {@link ThrownHttpError.declaredCode} is the producer's own string, verbatim
+ * and un-narrowed. Until #9106 it was what the dispatcher door put in
+ * `error.code`; since the #9106 ruling it is what BOTH doors surface as the
+ * wire's `declaredCode` when it is not a vocabulary member (see below).
+ *
+ * [#8087] The first ruling on that gap (maintainer, 2026-08-12) kept the
+ * dispatcher's verbatim spelling and delivered a GATE — the unregistered
+ * producers are measured and classified
+ * (`packages/runtime/src/dispatcher-error-vocabulary.ts`,
+ * `pnpm check:dispatcher-error-vocabulary`) instead of named in prose here.
+ * The gate's own first derivation then measured the limb no registration can
+ * close: a metadata app's action code crosses the sandbox boundary carrying
+ * the app's OWN `.code` (#7867), authored by tenants at runtime.
+ *
+ * [#9106] That limb was ruled (maintainer, 2026-08-16): **`error.code` is a
+ * closed vocabulary at every door.** The dispatcher door now takes
+ * {@link ThrownHttpError.code} — the demote this resolver has always computed,
+ * and the REST door's spelling since #8016 — and a producer's unregistered
+ * string rides the wire's `declaredCode` (declared on `ApiErrorSchema`)
+ * instead of `error.code`. #7867's capability is preserved: the author's code
+ * still crosses the sandbox and still reaches the wire — in the open,
+ * author-authored channel, not the closed one. Use
+ * {@link demotedDeclaredCode} to read the spelling a boundary should surface
+ * beside the closed `code`.
+ *
+ * So the doors agree on **status** and on **code** unconditionally now — both
+ * answers come from ONE function, which is what keeps agreement a construction
+ * rather than two suites agreeing about literals.
+ *
+ * ## What this deliberately does NOT decide
+ *
+ *  - **Message disclosure.** A 5xx message may name physical tables or carry a
+ *    driver dump; withholding it is `looksLikeInternalErrorLeak`'s job, applied
+ *    by the caller (the dispatcher does; see #3867). This function returns the
+ *    thrown message verbatim.
+ *  - **Whether a declared status is *plausible*.** No 400-599 band is imposed,
+ *    because the dispatcher never imposed one and this function exists to make
+ *    the two doors agree. Narrowing the accepted band is a change to the rule,
+ *    and it belongs here — in one place, for both doors — if it is ever made.
+ */
+
+/** The HTTP answer a thrown error declares. See {@link resolveThrownHttpError}. */
+interface ThrownHttpError {
+    /** The producer's own `status`/`statusCode`, or the caller's fallback. */
+    status: number;
+    /**
+     * The status the THROW ITSELF declared — `.status`, `.statusCode`, or the
+     * 400 a validation-shaped throw declares by shape — and **absent** when it
+     * declared none, i.e. when {@link ThrownHttpError.status} above is the
+     * caller's `fallbackStatus`.
+     *
+     * ## Why `status` cannot answer this
+     *
+     * A producer that declares `500` and one that declares nothing both resolve
+     * to `status: 500`, so a caller that must tell "the producer said so" from
+     * "I supplied the default" cannot read it off the value. The workaround in
+     * the repo was to probe this function with a fallback no producer declares
+     * — `resolveThrownHttpError(e, 0).status !== 0`. That is a magic number
+     * standing in for a fact this function already computed, and it fails
+     * silently the day a producer declares the sentinel. So the fact is stated;
+     * `packages/rest`'s publish-classification suite now reads
+     * `resolveThrownHttpError(error).declaredStatus !== undefined` instead of
+     * hand-spelling the workaround.
+     *
+     * ## Who needs the distinction
+     *
+     * A sink that mirrors the status onto RESPONSE DATA instead of into the
+     * response's own status line — where the fallback would not be a default but
+     * an invention. `metadata-protocol`'s `toRowApiError` is the measured one
+     * (#8570): a batch row rides a **200**, so stamping `status` there would put
+     * `httpStatus: 500` on every undeclared driver fault, an ADDITION to the
+     * wire, where stamping `declaredStatus` restores only what a producer really
+     * declared. Boundaries that answer with the status itself keep reading
+     * `status` — the fallback is exactly what they want.
+     */
+    declaredStatus?: number;
+    /**
+     * A member of the declared ADR-0112 vocabulary — for a boundary whose
+     * envelope is checked against it. Never the HTTP status.
+     */
+    code: ErrorCode;
+    /**
+     * The producer's own code, verbatim and un-narrowed, or `undefined` when it
+     * declared none. Never for `error.code` — that slot takes {@link code} at
+     * 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.
+     */
+    declaredCode?: string;
+    /** The thrown message, UNSANITISED — see the module note on disclosure. */
+    message: string;
+    /**
+     * The producer's user-facing refusal text, verbatim — present exactly when
+     * the throw carried a non-empty string `userMessage` (#9934).
+     *
+     * This is the producer-side opt-in the objectui#5210 ruling asked for
+     * (maintainer, 2026-08-19, option 1): an application hook's refusal has no
+     * way to distinguish author-written user guidance from platform diagnostics,
+     * so the console substitutes a generic string on 403 (the recorded #3821
+     * fix) and every author-written remedy is suppressed with the diagnostics.
+     * A producer that sets `userMessage` on the thrown error is saying, at throw
+     * time, "this exact text is addressed to the END USER" — a consumer renders
+     * it verbatim and keeps the generic substitution for everything unmarked.
+     *
+     * Deliberately a FIELD carrying the text, not a boolean beside `message`:
+     * the mark and the marked text are one value, so a boundary that rewraps or
+     * substitutes `message` (sanitisation, truncation, the sandbox debug
+     * wrapper) can never accidentally promote platform prose into the marked
+     * channel — the #3821 protection holds by construction. Read through
+     * {@link declaredUserMessage}, never with an inline `typeof` probe.
+     *
+     * Status-agnostic on purpose (the ruling's second constraint): a 400, 403,
+     * 409 or 503 refusal may all carry it. It never REPLACES `message` — the
+     * diagnostic channel keeps its wording for logs and developers.
+     */
+    userMessage?: string;
+    /**
+     * Structured context: spec-validation `issues[]`, record-validation
+     * `fields[]`. Absent rather than `{}` when the throw carried none, so an
+     * empty object never reads as "there is context here".
+     */
+    details?: Record<string, unknown>;
+}
+/**
+ * Resolve a thrown error into the status, code, message and structured context
+ * an HTTP boundary should answer with.
+ *
+ * Precedence, in order:
+ *
+ * | Question | Answer |
+ * |---|---|
+ * | status | `.status` → `.statusCode` → 400 if it is a validation failure → `fallbackStatus` |
+ * | declaredStatus | the same chain WITHOUT the fallback — absent when the throw declared none |
+ * | code | `VALIDATION_FAILED` if it is one → a REGISTERED `.code` → derived from the status |
+ * | declaredCode | `VALIDATION_FAILED` if it is one → any non-empty string `.code` → absent |
+ * | message | `.message` when it is a string → `String(error)` |
+ * | userMessage | a non-empty string `.userMessage` → absent (see {@link declaredUserMessage}) |
+ *
+ * Both status spellings are read because both are produced in this repo:
+ * `plugin-approvals`' lifecycle hooks and `metadata-protocol` throw
+ * `statusCode`, `metadata-protocol`'s conflicts throw `status`. Reading one
+ * spelling is how `/api/v1/data` answered 500 for a deliberate `409
+ * RECORD_LOCKED` until #7525.
+ */
+declare function resolveThrownHttpError(error: unknown, fallbackStatus?: number): ThrownHttpError;
+/**
+ * The user-facing refusal text a thrown error DECLARED, or `undefined` when it
+ * declared none (#9934). See {@link ThrownHttpError.userMessage} for what the
+ * declaration means and why it is a text-carrying field rather than a flag.
+ *
+ * The ONE read every boundary applies — the REST classification door, the
+ * dispatcher door, and the sandbox side-channel all call this rather than
+ * probing `error.userMessage` themselves, so "what counts as marked" cannot
+ * fork per door the way the `status`/`statusCode` spelling once did (#7525).
+ *
+ * A non-string or blank `userMessage` is NOT a declaration: `undefined`, a
+ * number, `''` and whitespace-only all answer `undefined`, so nothing invents
+ * a marked message for a producer that never wrote one — absent means the
+ * consumer keeps its generic substitution (#3821 preserved by construction).
+ */
+declare function declaredUserMessage(error: unknown): string | 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.
+ */
+declare function demotedDeclaredCode(thrown: ThrownHttpError): string | undefined;
+
+/** The HTTP status a validation failure maps to when the error names none. */
+declare const VALIDATION_FAILED_STATUS = 400;
+interface ValidationFailureDetails {
+    code: 'VALIDATION_FAILED';
+    /** Per-field envelopes, passed through verbatim. `[]` when absent/malformed. */
+    fields: unknown[];
+}
+/**
+ * Structured `details` for a thrown validation failure, or `undefined` when
+ * `err` is not one. Callers use the `undefined` result as the predicate and the
+ * returned object as the `details` payload, so the two can never disagree.
+ */
+declare function validationFailureDetails(err: any): ValidationFailureDetails | undefined;
+/**
+ * [#3878/#3899] The CONSTRUCTOR for the shape {@link validationFailureDetails}
+ * recognises — kept in the same module so the two can never drift. Thrown from
+ * a domain handler, both dispatcher error exits map it to
+ * `400 VALIDATION_FAILED` + `details.fields[]` (#3918) with no new error
+ * channel and no runtime dependency on objectql's `ValidationError` class.
+ * First built inline by the analytics domain; hoisted here when notifications
+ * and automation grew the same entry gates rather than a third copy.
+ */
+declare function validationFailure(message: string, fields: unknown[]): Error;
+/**
+ * Zod issues → the dispatcher's `fields[]` envelope entries
+ * (`{ field, code, message }`). `'(body)'` names a root-level failure — a body
+ * that is the wrong TYPE entirely has no path to point at.
+ *
+ * ## The `code` is an ADR-0114 `FieldErrorCode`, not Zod's (#8124)
+ *
+ * This used to assign `issue.code` verbatim, which put Zod's own vocabulary
+ * (`unrecognized_keys`, `too_small`, …) on a wire position
+ * `FieldErrorSchema.code` declares as a CLOSED catalog — the exact
+ * pass-through ADR-0114 D3 closed on the REST transport. It now maps through
+ * `zodIssuesToFields`, the one D3 implementation in the repo, which lives in
+ * `@objectstack/spec` beside the catalog it is total over (this package cannot
+ * import `@objectstack/rest`, where the compliant copy grew up — the
+ * dependency arrow points the other way, which is what #8124 moved it for).
+ *
+ * Two things ride along, both additive:
+ *
+ * - **The optional `input`** (the value that was parsed) buys the D3
+ *   `invalid_type` split: with it a MISSING required property is reported as
+ *   `required` instead of the `invalid_type` Zod spells it as. Callers without
+ *   the input at hand degrade per the D3 table — every code is still a
+ *   catalog member.
+ * - **Union expansion (#5014)**: a rejection behind a `z.union` yields the
+ *   union's own entry PLUS the branch entries that explain it, so entry count
+ *   is not issue count. Read `fields.length` as the number of field errors.
+ */
+declare function fieldsFromZodIssues(issues: Array<{
+    path: Array<string | number | symbol>;
+    code: string;
+    message: string;
+}>, ...input: [] | [unknown]): Array<{
+    field: string;
+    code: FieldErrorCode;
+    message: string;
+}>;
+
 /**
  * The one home for Postgres' `«sub-object» "x" of relation "y" …` phrasing
  * (#6615).
@@ -871,6 +1154,35 @@ declare function isUniqueViolationError(error: unknown): boolean;
  */
 declare function uniqueViolationColumn(error: unknown): string | undefined;
 
+/**
+ * Whether a thrown driver error says the `ON CONFLICT` target it was given is
+ * backed by no PRIMARY KEY or UNIQUE index.
+ *
+ * Reads the message channel, then one step at a time down the `cause` chain —
+ * pool and query-builder layers re-throw with the original attached, and the
+ * refusal this predicate gates keeps the raw error as its own `cause`. A plain
+ * string is judged directly, so a caller that already unwrapped `err.message`
+ * can pass it in.
+ *
+ * **Unrecognised is always `false`.** A false positive is the expensive
+ * direction: it tells a caller to go add an index when the real failure was a
+ * syntax error, a missing table, or — worst — a genuine unique violation on an
+ * index that exists and works. A false negative costs only the raw error that
+ * was the status quo before recognition existed.
+ *
+ * @param error - the thrown value, of any shape.
+ *
+ * @example
+ * ```ts
+ * catch (error) {
+ *   // ⚠️ NOT isUniqueViolationError — that is the opposite condition.
+ *   if (isUnbackedConflictTargetError(error)) throw refuseUnbackedConflictTarget(object, keys, error);
+ *   throw error;
+ * }
+ * ```
+ */
+declare function isUnbackedConflictTargetError(error: unknown): boolean;
+
 /**
  * [ADR-0120 D5e] The `isolated`-posture install gate for `'global'` uniqueness.
  *
@@ -1095,4 +1407,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, _resetEnvDeprecationWarnings, buildGlobalUniqueStopMessage, collectConfiguredLocales, collectGlobalUniques, declaredIndexUniqueIsGlobal, declaresServerFault, describeGlobalUniqueFinding, emitDegradedBootBanner, fieldUniqueIsGlobal, globalUniqueFindingId, isMcpServerEnabled, isModuleNotFoundError, isPlatformOwnedObject, isRelationSubObjectPhrase, isUniqueViolationError, keysetWalk, looksLikeInternalErrorLeak, matchMissingColumnOfRelation, postureGatesGlobalUniques, readEnvWithDeprecation, recordGlobalUniqueAttestation, resolveAllowDegradedTenancy, resolveAllowDevPlugin, resolveAllowDriverConnectFailure, resolveMcpStdioAutoStart, resolveMultiOrgEnabled, resolveOrgLimit, resolveSandboxTimeoutMs, resolveSearchPinyinEnabled, resolveTenancyPosture, sendError, sendOk, stampSearchPinyinEnabled, unconfirmedGlobalUniques, uniqueViolationColumn };
+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 };

package/dist/index.js

@@ -23,20 +23,25 @@ __export(index_exports, {
   GLOBAL_UNIQUE_CONFIRMATION_REQUIRED: () => GLOBAL_UNIQUE_CONFIRMATION_REQUIRED,
   GLOBAL_UNIQUE_ISOLATED_PRESCRIPTION: () => GLOBAL_UNIQUE_ISOLATED_PRESCRIPTION,
   INTERNAL_ERROR_MESSAGE: () => INTERNAL_ERROR_MESSAGE,
+  VALIDATION_FAILED_STATUS: () => VALIDATION_FAILED_STATUS,
   _resetEnvDeprecationWarnings: () => _resetEnvDeprecationWarnings,
   buildGlobalUniqueStopMessage: () => buildGlobalUniqueStopMessage,
   collectConfiguredLocales: () => collectConfiguredLocales,
   collectGlobalUniques: () => collectGlobalUniques,
   declaredIndexUniqueIsGlobal: () => declaredIndexUniqueIsGlobal,
+  declaredUserMessage: () => declaredUserMessage,
   declaresServerFault: () => declaresServerFault,
+  demotedDeclaredCode: () => demotedDeclaredCode,
   describeGlobalUniqueFinding: () => describeGlobalUniqueFinding,
   emitDegradedBootBanner: () => emitDegradedBootBanner,
   fieldUniqueIsGlobal: () => fieldUniqueIsGlobal,
+  fieldsFromZodIssues: () => fieldsFromZodIssues,
   globalUniqueFindingId: () => globalUniqueFindingId,
   isMcpServerEnabled: () => isMcpServerEnabled,
   isModuleNotFoundError: () => isModuleNotFoundError,
   isPlatformOwnedObject: () => isPlatformOwnedObject,
   isRelationSubObjectPhrase: () => isRelationSubObjectPhrase,
+  isUnbackedConflictTargetError: () => isUnbackedConflictTargetError,
   isUniqueViolationError: () => isUniqueViolationError,
   keysetWalk: () => keysetWalk,
   looksLikeInternalErrorLeak: () => looksLikeInternalErrorLeak,
@@ -53,11 +58,14 @@ __export(index_exports, {
   resolveSandboxTimeoutMs: () => resolveSandboxTimeoutMs,
   resolveSearchPinyinEnabled: () => resolveSearchPinyinEnabled,
   resolveTenancyPosture: () => resolveTenancyPosture,
+  resolveThrownHttpError: () => resolveThrownHttpError,
   sendError: () => sendError,
   sendOk: () => sendOk,
   stampSearchPinyinEnabled: () => stampSearchPinyinEnabled,
   unconfirmedGlobalUniques: () => unconfirmedGlobalUniques,
-  uniqueViolationColumn: () => uniqueViolationColumn
+  uniqueViolationColumn: () => uniqueViolationColumn,
+  validationFailure: () => validationFailure,
+  validationFailureDetails: () => validationFailureDetails
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -196,10 +204,47 @@ function _resetEnvDeprecationWarnings() {
 
 // src/error-leak.ts
 var INTERNAL_ERROR_MESSAGE = "Internal server error";
+var DIALECT_LEAK_PHRASINGS = [
+  // Postgres 42P01 / 42703 (and, as a superstring, the `… of relation "…"`
+  // sub-object family: 42704 and friends). The quotes are required because
+  // Postgres always emits them here.
+  /\b(?:relation|column)\s+["'`][^"'`]+["'`]\s+does not exist/i,
+  // Postgres 42501. Restricted to physical object kinds: `schema`, `view`,
+  // `function` and `column` are all ObjectStack AUTHORING vocabulary, so a
+  // product message could legitimately use them and a miss is the cheap
+  // direction (the outcome is already a 5xx).
+  /\bpermission denied for (?:table|relation|sequence|database)\b/i,
+  // SQLite/libsql, message-only form. The `sqlite_` limb below catches these
+  // only when the driver prefixed its code; `better-sqlite3` and libsql both
+  // raise them bare, which is the shape measured across this repo.
+  /\bno such (?:table|column):/i,
+  // [#8739] MySQL/MariaDB ER_NO_SUCH_TABLE (1146): `Table 'app.t' doesn't
+  // exist`. Its own template, not a spelling of the Postgres one — MySQL
+  // contracts the verb and quotes `db.table` as a single identifier — so the
+  // `relation|column … does not exist` limb above cannot reach it. The quotes
+  // are required for the same reason they are there: the driver always emits
+  // them and prose about a table usually does not.
+  /\btable\s+["'`][^"'`]+["'`]\s+doesn't exist/i,
+  // [#8739] MySQL/MariaDB ER_BAD_FIELD_ERROR (1054): `Unknown column 'c' in
+  // 'field list'`. BOTH quoted parts are required. The second is MySQL's clause
+  // name — `field list`, `where clause`, `order clause`, `on clause` — and it
+  // is the half that makes this the driver's template rather than a sentence
+  // that merely calls a column unknown, which an import or mapping feature has
+  // every right to say.
+  /\bunknown column\s+["'`][^"'`]+["'`]\s+in\s+["'`][^"'`]+["'`]/i,
+  // [#8739] MySQL/MariaDB ER_DUP_ENTRY (1062): `Duplicate entry
+  // 'acme@example.com' for key 'crm_account.email'`. `for key` + a quoted index
+  // is the anchor; the VALUE half is matched loosely and lazily because it is
+  // the caller's own text and MySQL does not escape a quote inside it
+  // (`Duplicate entry 'O'Brien' for key 'i'` is a real shape). A bare
+  // `duplicate entry` with no `for key '…'` tail is not this template and is
+  // left alone.
+  /\bduplicate entry\s+["'`].*?["'`]\s+for key\s+["'`][^"'`]+["'`]/i
+];
 function looksLikeInternalErrorLeak(message) {
   if (!message) return false;
   const lower = String(message).toLowerCase();
-  return lower.includes("sqlite_") || lower.includes("sqlstate") || lower.startsWith("insert into ") || lower.startsWith("update ") || lower.startsWith("select ") || lower.startsWith("delete from ") || lower.includes("constraint failed") || lower.includes("unique constraint") || lower.includes("foreign key");
+  return lower.includes("sqlite_") || lower.includes("sqlstate") || lower.startsWith("insert into ") || lower.startsWith("update ") || lower.startsWith("select ") || lower.startsWith("delete from ") || lower.includes("constraint failed") || lower.includes("unique constraint") || lower.includes("foreign key") || DIALECT_LEAK_PHRASINGS.some((pattern) => pattern.test(lower));
 }
 function declaresServerFault(err) {
   if (typeof err !== "object" || err === null) return false;
@@ -284,6 +329,71 @@ function sendError(res, status, code, message, extra) {
   res.status(status).json({ success: false, error: { code, message, ...extra } });
 }
 
+// src/thrown-http-error.ts
+var import_api2 = require("@objectstack/spec/api");
+
+// src/validation-failure.ts
+var import_api = require("@objectstack/spec/api");
+var VALIDATION_FAILED_STATUS = 400;
+function validationFailureDetails(err) {
+  if (!err) return void 0;
+  if (err.code !== "VALIDATION_FAILED" && err.name !== "ValidationError") return void 0;
+  return {
+    code: "VALIDATION_FAILED",
+    fields: Array.isArray(err.fields) ? err.fields : []
+  };
+}
+function validationFailure(message, fields) {
+  const err = new Error(message);
+  err.name = "ValidationError";
+  err.code = "VALIDATION_FAILED";
+  err.fields = fields;
+  return err;
+}
+function fieldsFromZodIssues(issues, ...input) {
+  return (0, import_api.zodIssuesToFields)(issues, ...input).map(
+    (entry) => entry.field === "" ? { ...entry, field: "(body)" } : entry
+  );
+}
+
+// src/thrown-http-error.ts
+function resolveThrownHttpError(error, fallbackStatus = 500) {
+  const e = error;
+  const validation = validationFailureDetails(e);
+  const declaredStatus = typeof e?.status === "number" ? e.status : typeof e?.statusCode === "number" ? e.statusCode : validation ? VALIDATION_FAILED_STATUS : void 0;
+  const status = declaredStatus ?? fallbackStatus;
+  const spelled = typeof e?.code === "string" && e.code !== "" ? e.code : void 0;
+  const registered = spelled !== void 0 && import_api2.ErrorCode.safeParse(spelled).success ? spelled : void 0;
+  const code = validation ? validation.code : registered ?? (0, import_api2.standardErrorCodeForHttpStatus)(status);
+  const declaredCode = validation ? validation.code : spelled;
+  const issues = Array.isArray(e?.issues) ? e.issues : void 0;
+  const details = {
+    // A truthy NON-string `code` (a driver errno, say) is context and stays
+    // context — promoting it would put a number in the field callers branch on,
+    // which is the drift #3842 removed.
+    ...!validation && e?.code && typeof e.code !== "string" ? { code: e.code } : {},
+    ...issues ? { issues } : {},
+    ...validation ? { fields: validation.fields } : {}
+  };
+  const userMessage = declaredUserMessage(error);
+  return {
+    status,
+    ...declaredStatus !== void 0 ? { declaredStatus } : {},
+    code,
+    ...declaredCode !== void 0 ? { declaredCode } : {},
+    message: typeof e?.message === "string" ? e.message : String(error),
+    ...userMessage !== void 0 ? { userMessage } : {},
+    ...Object.keys(details).length > 0 ? { details } : {}
+  };
+}
+function declaredUserMessage(error) {
+  const declared = error?.userMessage;
+  return typeof declared === "string" && declared.trim().length > 0 ? declared : void 0;
+}
+function demotedDeclaredCode(thrown) {
+  return thrown.declaredCode !== void 0 && thrown.declaredCode !== thrown.code ? thrown.declaredCode : void 0;
+}
+
 // src/relation-sub-object.ts
 function matchMissingColumnOfRelation(message) {
   return MISSING_COLUMN_OF_RELATION.exec(message)?.[1];
@@ -298,7 +408,7 @@ var RELATION_SUB_OBJECT = /["'`][^"'`]+["'`]\s+of relation\s/i;
 var UNIQUE_VIOLATION = {
   codes: /* @__PURE__ */ new Set(["23505", "ER_DUP_ENTRY", "SQLITE_CONSTRAINT_UNIQUE"]),
   errnos: /* @__PURE__ */ new Set([1062]),
-  message: /unique constraint|unique violation|duplicate key|duplicate entry/i
+  message: /unique constraint failed|violates unique constraint|unique violation|duplicate key|duplicate entry/i
 };
 var MAX_CAUSE_DEPTH = 4;
 function isUniqueViolationError(error) {
@@ -360,6 +470,23 @@ function uniqueViolationColumn(error) {
   return findUniqueViolationColumn(error, 0);
 }
 
+// src/unbacked-conflict-target.ts
+var UNBACKED_CONFLICT_TARGET = {
+  message: /ON CONFLICT clause does not match any PRIMARY KEY or UNIQUE constraint|there is no unique or exclusion constraint matching the ON CONFLICT specification/i
+};
+var MAX_CAUSE_DEPTH2 = 4;
+function isUnbackedConflictTargetError(error) {
+  return matchesUnbackedConflictTarget(error, 0);
+}
+function matchesUnbackedConflictTarget(error, depth) {
+  if (error === null || error === void 0 || depth > MAX_CAUSE_DEPTH2) return false;
+  if (typeof error === "string") return UNBACKED_CONFLICT_TARGET.message.test(error);
+  if (typeof error !== "object") return false;
+  const err = error;
+  if (typeof err.message === "string" && UNBACKED_CONFLICT_TARGET.message.test(err.message)) return true;
+  return matchesUnbackedConflictTarget(err.cause, depth + 1);
+}
+
 // src/unique-scope-install-gate.ts
 var import_security2 = require("@objectstack/spec/security");
 var SYS_OBJECT_PREFIXES = ["sys_", "base_"];
@@ -462,20 +589,25 @@ function postureGatesGlobalUniques(posture) {
   GLOBAL_UNIQUE_CONFIRMATION_REQUIRED,
   GLOBAL_UNIQUE_ISOLATED_PRESCRIPTION,
   INTERNAL_ERROR_MESSAGE,
+  VALIDATION_FAILED_STATUS,
   _resetEnvDeprecationWarnings,
   buildGlobalUniqueStopMessage,
   collectConfiguredLocales,
   collectGlobalUniques,
   declaredIndexUniqueIsGlobal,
+  declaredUserMessage,
   declaresServerFault,
+  demotedDeclaredCode,
   describeGlobalUniqueFinding,
   emitDegradedBootBanner,
   fieldUniqueIsGlobal,
+  fieldsFromZodIssues,
   globalUniqueFindingId,
   isMcpServerEnabled,
   isModuleNotFoundError,
   isPlatformOwnedObject,
   isRelationSubObjectPhrase,
+  isUnbackedConflictTargetError,
   isUniqueViolationError,
   keysetWalk,
   looksLikeInternalErrorLeak,
@@ -492,10 +624,13 @@ function postureGatesGlobalUniques(posture) {
   resolveSandboxTimeoutMs,
   resolveSearchPinyinEnabled,
   resolveTenancyPosture,
+  resolveThrownHttpError,
   sendError,
   sendOk,
   stampSearchPinyinEnabled,
   unconfirmedGlobalUniques,
-  uniqueViolationColumn
+  uniqueViolationColumn,
+  validationFailure,
+  validationFailureDetails
 });
 //# sourceMappingURL=index.js.map