@objectstack/types 17.0.0 → 17.1.0

package/dist/index.d.ts

@@ -393,7 +393,11 @@ declare const INTERNAL_ERROR_MESSAGE = "Internal server error";
  * (a message that *starts* as `SELECT`/`INSERT INTO`/`UPDATE`/`DELETE FROM` —
  * drivers prefix the offending SQL to their message), constraint-violation
  * dumps, which name physical tables and columns, and the
- * {@link DIALECT_LEAK_PHRASINGS} of the engines this repo ships.
+ * {@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` and the dialect phrasings on
@@ -724,17 +728,33 @@ declare function sendError(res: EnvelopeResponse, status: number, code: ErrorCod
  * unregistered code there is a failing test, not a wire answer.
  *
  * {@link ThrownHttpError.declaredCode} is the producer's own string, verbatim
- * and un-narrowed, which is what the dispatcher door has always put on the
- * wire — `STORAGE_FAILURE`, `FLOW_FAILED` and `DUPLICATE` are all unregistered
- * and all pinned by existing dispatcher tests. Narrowing it here would rewrite
- * a behaviour three suites assert, which is a contract decision (should the
- * dispatcher's `error.code` be closed too?) and not this function's to take.
- *
- * So the doors agree on **status** unconditionally and on **code** for every
- * registered code, and differ only where a producer emits a code the ledger
- * does not know — a case that is already a contract violation on either door.
- * Both answers come from ONE function, which is what keeps that difference a
- * documented one rather than a drift.
+ * 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
  *
@@ -764,10 +784,12 @@ interface ThrownHttpError {
      * 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`, still spelled by hand in
-     * `packages/rest`'s publish-classification suite. That is a magic number
+     * — `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.
+     * 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
      *
@@ -788,12 +810,39 @@ interface ThrownHttpError {
     code: ErrorCode;
     /**
      * The producer's own code, verbatim and un-narrowed, or `undefined` when it
-     * declared none. For the dispatcher door, whose `error.code` is not closed in
-     * practice. See the module note on why there are two.
+     * 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
@@ -814,6 +863,7 @@ interface ThrownHttpError {
  * | 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
@@ -822,6 +872,36 @@ interface ThrownHttpError {
  * 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;
@@ -1327,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, type ThrownHttpError, VALIDATION_FAILED_STATUS, type ValidationFailureDetails, _resetEnvDeprecationWarnings, buildGlobalUniqueStopMessage, collectConfiguredLocales, collectGlobalUniques, declaredIndexUniqueIsGlobal, declaresServerFault, 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 { 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

@@ -29,7 +29,9 @@ __export(index_exports, {
   collectConfiguredLocales: () => collectConfiguredLocales,
   collectGlobalUniques: () => collectGlobalUniques,
   declaredIndexUniqueIsGlobal: () => declaredIndexUniqueIsGlobal,
+  declaredUserMessage: () => declaredUserMessage,
   declaresServerFault: () => declaresServerFault,
+  demotedDeclaredCode: () => demotedDeclaredCode,
   describeGlobalUniqueFinding: () => describeGlobalUniqueFinding,
   emitDegradedBootBanner: () => emitDegradedBootBanner,
   fieldUniqueIsGlobal: () => fieldUniqueIsGlobal,
@@ -215,7 +217,29 @@ var DIALECT_LEAK_PHRASINGS = [
   // 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
+  /\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;
@@ -351,15 +375,24 @@ function resolveThrownHttpError(error, fallbackStatus = 500) {
     ...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) {
@@ -375,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) {
@@ -562,7 +595,9 @@ function postureGatesGlobalUniques(posture) {
   collectConfiguredLocales,
   collectGlobalUniques,
   declaredIndexUniqueIsGlobal,
+  declaredUserMessage,
   declaresServerFault,
+  demotedDeclaredCode,
   describeGlobalUniqueFinding,
   emitDegradedBootBanner,
   fieldUniqueIsGlobal,