tina4-nodejs 3.13.92 → 3.13.94

package/packages/core/src/devMailbox.ts

@@ -15,8 +15,6 @@ import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 
 import type { SendResult, EmailMessage } from "./messenger.js";
-import { Messenger } from "./messenger.js";
-import { isTruthy } from "./dotenv.js";
 
 // ── DevMailbox ───────────────────────────────────────────────
 
@@ -38,20 +36,35 @@ export class DevMailbox {
 
   /**
    * Capture an email to the dev mailbox instead of sending it.
+   *
+   * The parameter order MATCHES Messenger.send() on purpose. It did not before:
+   * send()'s 5th positional was `text` and capture()'s was `cc`, so the same call
+   * meant different things depending on which door it came through -- that mismatch
+   * IS nodejs#42.
+   *
+   * BREAKING: `text` is now the 5th positional. A caller passing cc positionally
+   * must move it. Aligning the two signatures is the fix; leaving them apart would
+   * preserve the bug.
    */
   capture(
     to: string | string[],
     subject: string,
     body: string,
     html: boolean = false,
-    cc: string[] = [],
-    bcc: string[] = [],
+    text?: string,
+    cc: string | string[] = [],
+    bcc: string | string[] = [],
     replyTo?: string,
     attachments: string[] = [],
     from?: string,
   ): SendResult {
     const id = randomUUID();
     const toList = Array.isArray(to) ? to : [to];
+    // Normalised HERE, at the boundary, so a message is well formed however it
+    // arrived. A dev mailbox that stores a malformed message and reports success
+    // defeats its own purpose -- it exists to show you what you WOULD have sent.
+    const ccList = Array.isArray(cc) ? cc : (cc ? [cc] : []);
+    const bccList = Array.isArray(bcc) ? bcc : (bcc ? [bcc] : []);
     const now = new Date().toISOString();
 
     const message: EmailMessage = {
@@ -59,11 +72,12 @@ export class DevMailbox {
       type: "outbox",
       from: from ?? process.env.TINA4_MAIL_FROM ?? "dev@localhost",
       to: toList,
-      cc,
-      bcc,
+      cc: ccList,
+      bcc: bccList,
       reply_to: replyTo,
       subject,
       body,
+      text,
       html,
       attachments,
       date: now,
@@ -280,41 +294,3 @@ export class DevMailbox {
 }
 
 // ── Factory ──────────────────────────────────────────────────
-
-/**
- * Create a Messenger or DevMailbox based on the environment.
- *
- * Returns DevMailbox when:
- *   - TINA4_DEBUG is "true", OR
- *   - No TINA4_MAIL_HOST is configured
- *
- * Returns a real Messenger otherwise (SMTP configured + not debug mode).
- *
- * This follows the factory pattern from PHP's MessengerFactory.
- */
-export function createMessenger(): Messenger | DevMailbox {
-  const debug = process.env.TINA4_DEBUG;
-  const smtpHost = process.env.TINA4_MAIL_HOST;
-
-  // Production = NOT debug mode AND NODE_ENV is "production".
-  // Derived here (was previously referenced undefined → ReferenceError).
-  const isProd = !isTruthy(debug) && process.env.NODE_ENV === "production";
-
-  // Force dev mode when TINA4_DEBUG is truthy
-  if (isTruthy(debug)) {
-    return new DevMailbox();
-  }
-
-  // No SMTP configured — must use dev mailbox
-  if (!smtpHost) {
-    return new DevMailbox();
-  }
-
-  // Non-production environment — use dev mailbox
-  if (!isProd) {
-    return new DevMailbox();
-  }
-
-  // Production with SMTP configured — use real Messenger
-  return new Messenger();
-}

package/packages/core/src/index.ts

@@ -94,9 +94,9 @@ export {
   handleFeedbackWidgetJs,
   registerFeedbackRoutes,
 } from "./feedback.js";
-export { Messenger, MessengerConnectionError } from "./messenger.js";
+export { Messenger, MessengerConnectionError, createMessenger } from "./messenger.js";
 export type { SendResult, EmailMessage } from "./messenger.js";
-export { DevMailbox, createMessenger } from "./devMailbox.js";
+export { DevMailbox } from "./devMailbox.js";
 export { WSDLService, WSDLOperation } from "./wsdl.js";
 export type { WSDLOperationMeta } from "./wsdl.js";
 export { HtmlElement, htmlElement, addHtmlHelpers, Raw, SafeString } from "./htmlElement.js";

package/packages/core/src/messenger.ts

@@ -29,6 +29,7 @@ import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 import { randomUUID } from "node:crypto";
 import { isTruthy } from "./dotenv.js";
+import { DevMailbox } from "./devMailbox.js";
 import { Log } from "./logger.js";
 
 /**
@@ -77,6 +78,10 @@ export interface EmailMessage {
   reply_to?: string;
   subject: string;
   body: string;
+  /** Plain-text alternative. Carried on the dev path too, so the captured message
+   *  is the message: a mailbox that shows you something other than what you wrote
+   *  is worse than no mailbox. */
+  text?: string;
   html: boolean;
   attachments: string[];
   date: string;
@@ -328,6 +333,10 @@ export class Messenger {
   private fromName: string;
   private encryption: string;
   private useTls: boolean;
+  /** Whether an SMTP host was actually configured (see the constructor). */
+  private smtpConfigured: boolean = false;
+  /** The local mailbox, present only when this messenger captures. */
+  public devMailbox: DevMailbox | null = null;
   private imapHost: string;
   private imapPort: number;
   private imapUser: string;
@@ -337,6 +346,11 @@ export class Messenger {
   constructor(options?: MessengerOptions) {
     // Priority: constructor > TINA4_MAIL_* > sensible default.
     // Legacy SMTP_*/IMAP_* env vars were removed in v3.12 — boot guard rejects them.
+    // Whether a host was actually CONFIGURED, which is not the same as this.host
+    // being set: it falls back to "localhost", so it is never empty and cannot
+    // answer "can this messenger send?". The capture gate needs that answer, so
+    // record it here while the real inputs are still in scope.
+    this.smtpConfigured = Boolean(options?.host ?? process.env.TINA4_MAIL_HOST);
     this.host = options?.host
       ?? process.env.TINA4_MAIL_HOST
       ?? "localhost";
@@ -399,6 +413,31 @@ export class Messenger {
   /**
    * Send an email via SMTP.
    */
+  /**
+   * Should send() capture locally instead of talking to SMTP?
+   *
+   * Availability decides, not verbosity. With no SMTP host configured sending is
+   * impossible, so simulate it into a folder rather than failing -- that is what
+   * makes a laptop with no mail server usable. TINA4_MAIL_CAPTURE forces capture
+   * even when a host IS configured.
+   *
+   * TINA4_DEBUG deliberately does NOT gate this, and neither does NODE_ENV. Debug
+   * must still be able to send, and the old `NODE_ENV !== "production"` clause
+   * silently swallowed every staging email.
+   */
+  private shouldCapture(): boolean {
+    if (isTruthy(process.env.TINA4_MAIL_CAPTURE)) return true;
+    return !this.smtpConfigured;
+  }
+
+  /** The local mailbox, created on first capture and reused after. */
+  private getDevMailbox(): DevMailbox {
+    if (this.devMailbox === null) {
+      this.devMailbox = new DevMailbox();
+    }
+    return this.devMailbox;
+  }
+
   async send(
     to: string | string[],
     subject: string,
@@ -416,6 +455,17 @@ export class Messenger {
     const ccList = Array.isArray(options.cc) ? options.cc : (options.cc ? [options.cc] : []);
     const bccList = Array.isArray(options.bcc) ? options.bcc : (options.bcc ? [options.bcc] : []);
     const allRecipients = [...toList, ...ccList, ...bccList];
+
+    // Dev capture is a BRANCH here, not a different object returned by the factory.
+    // createMessenger() used to hand back a DevMailbox, which has capture() and no
+    // send(), so the documented call threw TypeError (nodejs#41).
+    if (this.shouldCapture()) {
+      return this.getDevMailbox().capture(
+        to, subject, body, html, text, ccList, bccList, replyTo,
+        attachments, this.fromAddress || undefined,
+      );
+    }
+
     const messageId = `${randomUUID()}@${this.host}`;
 
     if (allRecipients.length === 0) {
@@ -1069,3 +1119,25 @@ function parseFullMessage(uid: string, response: string): ImapFullMessage {
     headers,
   };
 }
+
+/**
+ * Create a Messenger configured for the current environment.
+ *
+ * Returns ONE concrete type, always. It used to return `Messenger | DevMailbox`,
+ * and those two shared NO sending method -- DevMailbox has capture(), Messenger has
+ * send() -- so the documented call threw TypeError whenever the dev branch was
+ * taken. That is nodejs#41. Capture is now a branch inside Messenger.send(), so the
+ * object you get back has one send() with one signature either way.
+ *
+ * The gate is availability, not verbosity:
+ *   - no TINA4_MAIL_HOST -> capture (sending is impossible, so simulate it)
+ *   - TINA4_MAIL_CAPTURE truthy -> capture even with SMTP configured
+ *   - otherwise -> send, EVEN WITH TINA4_DEBUG ON
+ *
+ * TINA4_DEBUG no longer forces capture: debug must still be able to send real mail.
+ * The `NODE_ENV !== "production"` clause is also gone -- it captured even with SMTP
+ * configured and debug off, which silently ate every staging email.
+ */
+export function createMessenger(): Messenger {
+  return new Messenger();
+}

package/packages/core/src/queueBackends/kafkaBackend.ts

@@ -497,12 +497,15 @@ export class KafkaBackend implements QueueBackend {
             if (errCode === 0) {
               finish("__PUBLISHED__", 0);
             } else {
+              // Report the CODE, not just "it failed" — the caller decides
+              // whether it is retriable (3/5, the async topic-creation race)
+              // or fatal (e.g. 29 TOPIC_AUTHORIZATION_FAILED).
               process.stderr.write("Produce error code " + errCode);
-              finish("__ERROR__" + errCode, 0);
+              finish("__PRODUCEERROR__" + errCode, 0);
             }
           } catch (e) {
             process.stderr.write("produce parse: " + e.message);
-            finish("__ERROR__", 0);
+            finish("__PARSEERROR__produce: " + e.message, 0);
           }
           return;
         } else if (operation === "get") {
@@ -516,6 +519,7 @@ export class KafkaBackend implements QueueBackend {
             pos += 4;                                   // throttleTimeMs (v1+)
             const topicCount = buffer.readInt32BE(pos); pos += 4;
             let out = "__EMPTY__";
+            let fatalCode = 0;
             for (let t = 0; t < topicCount; t++) {
               const tl = buffer.readInt16BE(pos); pos += 2 + tl;
               const pc = buffer.readInt32BE(pos); pos += 4;
@@ -527,6 +531,14 @@ export class KafkaBackend implements QueueBackend {
                 const abortedCount = buffer.readInt32BE(pos); pos += 4;
                 if (abortedCount > 0) pos += abortedCount * 16; // (-1 => none, skip)
                 const recSetSize = buffer.readInt32BE(pos); pos += 4;
+                // 3 = UNKNOWN_TOPIC_OR_PARTITION, 5 = LEADER_NOT_AVAILABLE:
+                // "nothing to read here yet", which a consumer that starts
+                // before its producer hits on every cold start. Any OTHER code
+                // (29 TOPIC_AUTHORIZATION_FAILED, 13 STALE_CONTROLLER_EPOCH, …)
+                // is a real failure and must NOT be reported as an empty queue.
+                if (errCode !== 0 && errCode !== 3 && errCode !== 5) {
+                  fatalCode = errCode;
+                }
                 if (errCode === 0 && recSetSize > 0) {
                   const val = firstRecordValue(buffer, pos, pos + recSetSize);
                   if (val !== null) out = val;
@@ -534,21 +546,33 @@ export class KafkaBackend implements QueueBackend {
                 pos += recSetSize > 0 ? recSetSize : 0;
               }
             }
+            if (fatalCode !== 0) {
+              process.stderr.write("Fetch error code " + fatalCode);
+              finish("__FETCHERROR__" + fatalCode, 0);
+              return;
+            }
             finish(out, 0);
           } catch (e) {
+            // A parse failure is NOT an empty queue either — say so.
             process.stderr.write("fetch parse: " + e.message);
-            finish("__EMPTY__", 0);
+            finish("__PARSEERROR__fetch: " + e.message, 0);
           }
           return;
         }
       });
 
+      // Report the reason on STDOUT and exit 0. Writing it to stderr and
+      // exiting non-zero LOST it: stderr to a pipe is an async write and
+      // process.exit() truncates it, so the parent saw an empty stderr and fell
+      // back to execFileSync's message -- which embeds this entire script.
+      // stdout is flushed by finish()'s write callback, so it survives.
       sock.on("error", (err) => {
-        process.stderr.write(err.message);
-        finish("", 1);
+        finish("__TRANSPORTERROR__" + err.message, 0);
       });
 
-      var timer = setTimeout(() => { finish("", 1); }, 10000);
+      var timer = setTimeout(() => {
+        finish("__TRANSPORTERROR__timed out after 10s talking to " + host + ":" + port, 0);
+      }, 10000);
     `;
 
     try {
@@ -558,8 +582,59 @@ export class KafkaBackend implements QueueBackend {
         stdio: ["pipe", "pipe", "pipe"],
       });
       return result;
-    } catch {
-      return "";
+    } catch (err) {
+      // Reached only when the child itself could not run (spawn failure, killed,
+      // the outer 15s timeout). The socket-level reasons come back through
+      // stdout as __TRANSPORTERROR__ instead. Swallowing this to "" made every
+      // failure indistinguishable from an empty queue.
+      //
+      // execFileSync's own message embeds the ENTIRE generated script, so it is
+      // truncated here -- a 20KB error that buries the cause is barely better
+      // than no error at all.
+      const e = err as { stderr?: Buffer | string; message?: string };
+      const reason = String(e.stderr ?? "").trim() || e.message || "unknown error";
+      const firstLine = reason.split("\n", 1)[0]!.slice(0, 200);
+      return "__TRANSPORTERROR__" + firstLine;
+    }
+  }
+
+  /**
+   * Sleep synchronously between produce retries.
+   *
+   * `push()` is synchronous (the whole backend drives its socket through a child
+   * process), so there is no event loop to await on. `Atomics.wait` on a
+   * SharedArrayBuffer is the stdlib way to block a thread for a fixed time --
+   * no dependency, no busy-wait burning CPU.
+   */
+  private static sleepSync(ms: number): void {
+    const shared = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(shared, 0, 0, ms);
+  }
+
+  /**
+   * Turn a sentinel from the protocol child into a thrown error, or return.
+   *
+   * The wording matches the Python and PHP backends exactly -- the parity rule
+   * covers user-visible error messages, not just behaviour.
+   */
+  private static assertNoError(result: string, operation: string, topic: string): void {
+    const fatal = /^__(PRODUCEERROR|FETCHERROR)__(\d+)/.exec(result);
+    if (fatal) {
+      throw new Error(
+        `Kafka rejected the ${operation} for topic ${topic}: error code ${fatal[2]}`,
+      );
+    }
+    if (result.startsWith("__TRANSPORTERROR__")) {
+      throw new Error(
+        `Kafka ${operation} for topic ${topic} failed: ` +
+          result.slice("__TRANSPORTERROR__".length),
+      );
+    }
+    if (result.startsWith("__PARSEERROR__")) {
+      throw new Error(
+        `Kafka ${operation} for topic ${topic} returned an unreadable response: ` +
+          result.slice("__PARSEERROR__".length),
+      );
     }
   }
 
@@ -576,15 +651,36 @@ export class KafkaBackend implements QueueBackend {
       delayUntil: null,
     };
 
-    const result = this.execSync("publish", queue, JSON.stringify(job));
-    if (!result.includes("__PUBLISHED__")) {
-      throw new Error("Kafka publish failed");
+    // Topic auto-creation is ASYNCHRONOUS, so a brand-new topic answers
+    // UNKNOWN_TOPIC_OR_PARTITION (3) or LEADER_NOT_AVAILABLE (5) on the first
+    // attempt while the controller is still electing a leader. Retry those
+    // (same 10 attempts / 200ms as the Python and PHP backends) instead of
+    // failing a cold-start push; every other code throws immediately.
+    const body = JSON.stringify(job);
+    let result = "";
+    for (let attempt = 1; attempt <= 10; attempt++) {
+      result = this.execSync("publish", queue, body);
+      if (result.includes("__PUBLISHED__")) {
+        return id;
+      }
+      const retriable = /^__PRODUCEERROR__(3|5)\b/.test(result);
+      if (!retriable || attempt === 10) {
+        break;
+      }
+      KafkaBackend.sleepSync(200);
     }
-    return id;
+
+    KafkaBackend.assertNoError(result, "produce", queue);
+    throw new Error(`Kafka publish failed for topic ${queue}: ${result || "no response"}`);
   }
 
   pop(queue: string): QueueJob | null {
     const result = this.execSync("get", queue);
+
+    // A real failure must NOT read as an empty queue: a mis-permissioned
+    // consumer would otherwise poll an "idle" topic forever.
+    KafkaBackend.assertNoError(result, "fetch", queue);
+
     if (!result || result === "__EMPTY__" || result === "__UNSUPPORTED__") return null;
 
     try {

package/packages/core/src/sessionHandlers/childError.ts

@@ -0,0 +1,72 @@
+/**
+ * Tina4 session handlers — turn a failed `execFileSync` child into a readable cause.
+ *
+ * The session-handler interface is synchronous but every backend client is async,
+ * so each command runs in a short-lived `node -e` child. When that child fails,
+ * `execFileSync` throws an error whose `.message` begins "Command failed:" and
+ * then embeds THE ENTIRE GENERATED SCRIPT — kilobytes of source with the real
+ * reason nowhere in it. Every handler used to throw exactly that, so an
+ * operator debugging a Redis outage got a wall of JavaScript instead of
+ * "connect ECONNREFUSED 127.0.0.1:6379".
+ *
+ * The children already write the real reason to stderr; `execFileSync` captures
+ * it on `err.stderr`. This module is the ONE place that prefers it, so the three
+ * call sites (respClient, mongoClient, redisHandler's npm path) cannot drift.
+ */
+
+/** Longest fallback we will pass through when there is no usable stderr. */
+const MAX_FALLBACK = 200;
+
+/**
+ * Extract the most useful one-line cause from a thrown `execFileSync` error.
+ *
+ * Order of preference:
+ *  1. the child's own stderr — what it actually reported;
+ *  2. a timeout, named as such (a SIGTERM kill leaves stderr empty, so without
+ *     this the caller would see the useless generic message);
+ *  3. a non-zero exit code with no output at all;
+ *  4. the error's own message, first line only and length-capped, so the
+ *     generated script can never be dumped into a log.
+ */
+export function childFailureReason(err: unknown): string {
+  const e = (err ?? {}) as {
+    stderr?: Buffer | string;
+    message?: string;
+    signal?: string | null;
+    status?: number | null;
+    code?: string;
+  };
+
+  const stderr = String(e.stderr ?? "").trim();
+  if (stderr !== "") {
+    return firstLine(stderr);
+  }
+
+  // execFileSync's `timeout` option kills the child with a signal, so it exits
+  // with NOTHING on stderr. Say "timed out" rather than "Command failed".
+  if (e.code === "ETIMEDOUT" || e.signal) {
+    return `timed out or was killed (${e.code ?? e.signal})`;
+  }
+
+  if (typeof e.status === "number" && e.status !== 0) {
+    return `child exited with code ${e.status} and no output`;
+  }
+
+  return firstLine(String(e.message ?? "unknown error"));
+}
+
+/** First line of `text`, capped at MAX_FALLBACK characters. */
+function firstLine(text: string): string {
+  const line = text.split("\n", 1)[0] ?? "";
+  return line.length > MAX_FALLBACK ? `${line.slice(0, MAX_FALLBACK)}...` : line;
+}
+
+/**
+ * Build the Error a session handler throws when its child command failed.
+ *
+ * `label` names the backend ("Redis", "Valkey", "MongoDB") so the message says
+ * which one broke; the wording is shared so all three read alike.
+ */
+export function childFailureError(label: string, err: unknown): Error {
+  return new Error(`${label} command failed: ${childFailureReason(err)}`);
+}

package/packages/core/src/sessionHandlers/mongoClient.ts

@@ -22,6 +22,7 @@
  * writes).
  */
 import { execFileSync } from "node:child_process";
+import { childFailureError } from "./childError.js";
 
 export interface MongoTarget {
   host: string;
@@ -90,8 +91,10 @@ export function mongoCommandSync(
           process.stdout.write(out, () => process.exit(0));
         } catch (err) {
           try { if (client) await client.close(); } catch (e) {}
-          process.stderr.write(String((err && err.message) || err));
-          process.exit(1);
+          // Exit from the write CALLBACK: stderr to a pipe is an async write and
+          // a bare process.exit() truncates it, which left the parent with an
+          // empty stderr and nothing but execFileSync's script-dump message.
+          process.stderr.write(String((err && err.message) || err), () => process.exit(1));
         }
       })();
     } else {
@@ -233,6 +236,9 @@ export function mongoCommandSync(
       stdio: ["pipe", "pipe", "pipe"],
     });
   } catch (err) {
-    throw new Error(`${label} command failed: ${(err as Error).message}`);
+    // The child's stderr carries the real reason (connection refused, auth
+    // failure, timeout); execFileSync's message carries the whole generated
+    // script. Prefer the former.
+    throw childFailureError(label, err);
   }
 }

package/packages/core/src/sessionHandlers/redisHandler.ts

@@ -17,6 +17,7 @@
  *   TINA4_SESSION_REDIS_DB       (default: 0)
  */
 import { execFileSync } from "node:child_process";
+import { childFailureError } from "./childError.js";
 import { createRequire } from "node:module";
 import type { SessionHandler } from "../session.js";
 import { respCommandSync } from "./respClient.js";
@@ -142,9 +143,17 @@ export class RedisNpmSessionHandler implements SessionHandler {
       (async () => {
         try {
           const redis = require("redis");
+          // reconnectStrategy: false — this child runs ONE command and exits, so
+          // retrying inside it is pointless: the handler is called again on the
+          // next request anyway. With the driver's default strategy a refused
+          // connection never rejects, the child hangs until execFileSync's 5s
+          // timeout kills it, and the caller is told "timed out" when the truth
+          // is "connection refused". Off, connect() rejects in ~5ms with the real
+          // reason -- a better message AND no 5s stall per request when Redis is
+          // down.
           const clientOpts = useUrl
-            ? { url }
-            : { socket: { host, port }, password: password || undefined, database: db };
+            ? { url, socket: { reconnectStrategy: false } }
+            : { socket: { host, port, reconnectStrategy: false }, password: password || undefined, database: db };
           const client = redis.createClient(clientOpts);
           client.on("error", () => {});
           await client.connect();
@@ -158,8 +167,10 @@ export class RedisNpmSessionHandler implements SessionHandler {
           const out = (result === null || result === undefined) ? "__NULL__" : String(result);
           process.stdout.write(out, () => process.exit(0));
         } catch (err) {
-          process.stderr.write(String((err && err.message) || err));
-          process.exit(1);
+          // Exit from the write CALLBACK: stderr to a pipe is an async write and
+          // a bare process.exit() truncates it, which left the parent with an
+          // empty stderr and nothing but execFileSync's script-dump message.
+          process.stderr.write(String((err && err.message) || err), () => process.exit(1));
         }
       })();
     `;
@@ -171,7 +182,9 @@ export class RedisNpmSessionHandler implements SessionHandler {
         stdio: ["pipe", "pipe", "pipe"],
       });
     } catch (err) {
-      throw new Error(`Redis command failed: ${(err as Error).message}`);
+      // The child's stderr carries the driver's real reason; execFileSync's
+      // message carries the whole generated script. Prefer the former.
+      throw childFailureError("Redis", err);
     }
     if (result === "__NULL__") return "";       // genuine key miss
     return result;

package/packages/core/src/sessionHandlers/respClient.ts

@@ -16,6 +16,7 @@
  * then returns the LAST (command) reply.
  */
 import { execFileSync } from "node:child_process";
+import { childFailureError } from "./childError.js";
 
 export interface RespTarget {
   host: string;
@@ -161,7 +162,10 @@ export function respCommandSync(target: RespTarget, args: string[], label = "Red
     // Non-zero exit = socket error / timeout / closed connection: a transport
     // FAILURE, not a key miss. Surface it so the Session boundary logs + degrades
     // (or re-throws under strict mode).
-    throw new Error(`${label} command failed: ${(err as Error).message}`);
+    //
+    // Report the CHILD's stderr, not execFileSync's message -- that message
+    // embeds the whole generated script and buries the actual reason.
+    throw childFailureError(label, err);
   }
   if (result === "__NULL__") return "";       // genuine key miss
   if (result.startsWith("__ERR__")) {