docs(types,metadata-protocol,changeset): state the split, and name the one surviving fallback

The census by rule found two claims carried in more than one place: a false
universal about what `(e as Error).message` did to an undeclared throw, and a
record formula that one of the fourteen call sites does not follow.

Over the five values pinned at the operator-text fallback case, that expression
did not answer one way. It read `undefined` for the string, the number and
`{}`, and it threw a `TypeError` for `null` and `undefined`. The pin's title and
the comment under it now state that split, which the shipped
`operatorFacingErrorText` docblock and both site docblocks already stated.

`seed-tenancy-backfill`'s organization probe keeps
`operatorFacingErrorText(e) || 'unknown error'`, so for an EMPTY channel it
records `'unknown error'`, not `''`. The metadata-protocol docblock, the pin
title that claimed every site, and the changeset -- which ships as release
notes -- now name that fallback and scope the formula to the other thirteen
sites. The fallback is load-bearing rather than leftover: the site reads an
empty value as "the probe did not fail", and with it removed an empty channel
routes the run down the benign no-organization-yet path. Whether it should go
is a behaviour question, tracked by #17167.

Two more sentences of the same class: the recognizer docblock now reads "a
NON-EMPTY sentence this fragment does not match" rather than "a DIFFERENT,
NON-EMPTY sentence", and `messageChannelOf`'s docblock no longer attributes
`undefined` to an expression that threw.

No behaviour change. 58 changed .ts lines, 54 comment and 4 title, 0 other;
comment-stripped and title-blanked hashes identical on all 13 .ts files; and
packages/types/dist/index.mjs, dist/index.js and dist/index.d.ts are each
byte-identical across this round.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XTBcV7zZHmokdyQgXjbyEU

Author: claude

.changeset/operator-facing-raw-exec-cause-text.md

@@ -79,9 +79,12 @@ and never a type. The change these sites were made for is the declared raw-path
 the record gains the dialect's words in place of the driver's composed placeholder. Every
 other throw now reaches these records through the rule above rather than through the
 expression each site spelled out, so its text can move too — a consequence of the rule, not a
-bounded list of exceptions, and some shapes still record `''` — a thrown empty string, a
-thrown empty array, and an `Error` whose `name` and `message` are both empty are the ones
-measured. The
-sentence being replaced is not a value any consumer can have been parsing: it is an opaque
-human diagnostic. A consumer reading these records gets the dialect's words back where it had
-been getting a placeholder.
+bounded list of exceptions. At thirteen of the fourteen sites the rule is the whole record,
+and some shapes still record `''` there: a thrown empty string, a thrown empty array, and an
+`Error` whose `name` and `message` are both empty are the ones measured. The fourteenth is
+`seed-tenancy-backfill`'s organization probe, which keeps a `|| 'unknown error'` fallback on
+top of the rule, so those same three shapes record `'unknown error'` there rather than `''`;
+that fallback is deliberate — the site reads an empty value as "the probe did not fail" — and
+whether it should go is tracked by #17167. The sentence being replaced is not a value any
+consumer can have been parsing: it is an opaque human diagnostic. A consumer reading these
+records gets the dialect's words back where it had been getting a placeholder.

packages/metadata-protocol/src/migrations/raw-exec-operator-detail-16657.test.ts

@@ -25,9 +25,25 @@
  * The negative direction is pinned per site as well: a seam failure that is NOT
  * a declared raw-statement fault is NOT unwrapped — its `cause` is never walked
  * and the record reads the thrown value's own message channel,
- * `messageChannelOf(error) || String(error)` — because the alternative, a
- * helper that unwraps whatever it is handed, is the message sniffing #16019
- * exists to remove.
+ * `messageChannelOf(error) || String(error)`, at every site here but the one
+ * noted below — because the alternative, a helper that unwraps whatever it is
+ * handed, is the message sniffing #16019 exists to remove.
+ *
+ * ⚠️ That formula is the WHOLE record at eight of this package's nine call
+ * sites (thirteen of the fourteen across the change), not at all of them.
+ * `seed-tenancy-backfill`'s ORGANIZATION probe still spells
+ * `operatorFacingErrorText(e) || 'unknown error'` — the one surviving fallback
+ * — so where the channel is EMPTY that record reads `'unknown error'` and
+ * never `''`. Measured at that probe: a thrown `''`, a thrown `[]`, and an
+ * `Error` whose `name` and `message` are both empty each record
+ * `'unknown error'`; the control `new Error('boom')` records `'boom'`. The
+ * fallback is load-bearing rather than leftover — this site reads
+ * `organizationProbeError === ''` as "the probe did not fail", and with the
+ * fallback deleted a thrown `''` routes the run down the benign
+ * `no-organization-yet` path instead of the ambiguous one (measured by
+ * ablation), which is the "unknown read as zero" confusion #9261 exists to
+ * prevent. Whether this record SHOULD be `''` like the other eight is a
+ * BEHAVIOUR question, deliberately not taken here; #17167 carries it.
  *
  * ⚠️ That channel is a RULE, not byte-identity with what each site used to
  * compute. Every negative pin below throws a NON-EMPTY `new Error(…)`, the
@@ -303,7 +319,13 @@ describe('[#16657] seed-tenancy-backfill — the stored operator record', () =>
         expect(line?.meta?.error).toBe(DIALECT_TEXT);
     });
 
-    it('an UNDECLARED refusal reads its own message channel at every one of these sites', async () => {
+    it('an UNDECLARED refusal reads its own message channel at the sites without a fallback', async () => {
+        // "Without a fallback" is eight of this package's nine call sites. The
+        // exception is the ORGANIZATION probe (`|| 'unknown error'`), whose
+        // record for an EMPTY channel is `'unknown error'` rather than `''` —
+        // see the module docblock above, and #17167. This pin drives the
+        // duplicates warning, which carries no fallback, with a NON-EMPTY
+        // message, so it exercises the channel and not the fallback.
         const log = createLogger();
         const bare = async (sql: string): Promise<unknown> => {
             if (sql.includes('rows_holding')) throw new Error('connection terminated unexpectedly');

packages/types/src/driver-error-classification.operator-text.test.ts

@@ -140,9 +140,13 @@ describe('[#16657] operatorFacingErrorText — the fallback channel when no caus
         expect(operatorFacingErrorText(thrown)).not.toBe('');
     });
 
-    it('reads a thrown non-Error on its own channel, where `(e as Error).message` read `undefined`', () => {
+    it('reads a thrown non-Error on its own channel, where `(e as Error).message` read `undefined` or threw', () => {
         // `(e as Error).message` — the expression this helper replaces at five
-        // sites — evaluates to `undefined` for every one of these.
+        // sites — answered these five two different ways, neither of them a
+        // record worth storing. It evaluated to `undefined` for the string, the
+        // number and `{}`; for `null` and `undefined` it threw a `TypeError`
+        // out of the catch, so no record was written at all and the operation
+        // aborted. The helper reads a channel instead, so all five store text.
         expect(operatorFacingErrorText('no such column: foo')).toBe('no such column: foo');
         expect(operatorFacingErrorText(42)).toBe('42');
         expect(operatorFacingErrorText(undefined)).toBe('undefined');

packages/types/src/driver-error-classification.ts

@@ -685,10 +685,11 @@ const DECLARED_DATABASE_FAULT_CODE = 'DATABASE_ERROR';
  * half) untouched: it declares the very same code and status, composes a
  * DIFFERENT sentence, and whether its prose should be unwrapped is a separate
  * decision this helper deliberately does not take. An envelope that declares
- * the code and composes a DIFFERENT, NON-EMPTY sentence is returned exactly as
- * it arrived — it speaks at depth 0, so the walk stops on it. ⚠️ Not so for a
- * declared envelope whose own message is EMPTY: an empty node says nothing, so
- * the walk steps past it and that envelope IS unwrapped (measured:
+ * the code and composes a NON-EMPTY sentence this fragment does not match is
+ * returned exactly as it arrived — it speaks at depth 0, so the walk stops on
+ * it. ⚠️ Not so for a declared envelope whose own message is EMPTY: an empty
+ * node says nothing, so the walk steps past it and that envelope IS unwrapped
+ * (measured:
  * `{code:'DATABASE_ERROR', message:'', cause:{message:'walked'}}` answers
  * `'walked'`). ⛔ No claim is made about whether any producer composes an
  * empty-message `DATABASE_ERROR`; that was not measured.
@@ -707,11 +708,12 @@ const RAW_STATEMENT_FAULT_SENTENCE = /refused to run a raw statement/;
  * `message` for an object or function, the string itself for a string, and
  * `String()` for any other primitive; anything else reads `''`. So a non-Error
  * node reads whatever text it carries rather than the `undefined` that
- * `(e as Error).message` produced at the FIVE sites spelled that way — of the
- * fourteen this helper replaces; the other nine spell
- * `instanceof Error ? … : String()` (five) or `?.message ?? …` (four) and
- * already carried a fallback — and a node whose own text is empty, a thrown
- * empty string among them, reads `''`.
+ * `(e as Error).message` produced at the FIVE sites spelled that way (for
+ * `null` and `undefined` that expression produced nothing at all — it threw a
+ * `TypeError` out of the catch) — of the fourteen this helper replaces; the
+ * other nine spell `instanceof Error ? … : String()` (five) or
+ * `?.message ?? …` (four) and already carried a fallback — and a node whose own
+ * text is empty, a thrown empty string among them, reads `''`.
  */
 function messageChannelOf(node: unknown): string {
     if (typeof node === 'string') return node;