@objectstack/types 17.0.0-rc.6 → 17.1.0

package/dist/index.d.mts

@@ -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 };