fix(service-analytics): the unknown dialect arm folds $icontains with a portable construct, not translate()

`normalizeSqlDialect` routes EVERYTHING it cannot name onto `unknown` — an
unset hook, `'oracle'`, `'libsql'`, a `SqlDriver` given a class client. #15780
left that arm folding with `translate()` on the reading that it "was never
broken", which held only for the dialects the arm was pictured as (mssql,
oracle). SQLite reaches it through four embedder compositions, and SQLite has
no `translate()`, so all three of this package's compilers emitted a statement
the engine refuses — a documented operator answering 500 because one OPTIONAL
field was left out.

The arm now folds with one nested `REPLACE` per ASCII letter: the same chain
the MySQL arm already used, minus its `CAST(… AS BINARY)`, so there is one
builder and the two cannot fold different alphabets. It parses on every SQL
dialect and is ASCII-only BY CONSTRUCTION, so it serves both families
`unknown` conflates — PostgreSQL/Oracle-like keep `translate()`'s exact result
set, SQLite-like get an answer at all.

- `postgres` is untouched and byte-identical; so is the case-EXACT family on
  every arm (`fold` false makes the fold function the identity on both).
- ⛔ Not `LOWER()`, which `driver-sql`'s own `unknown` arm uses: it follows the
  collation and would trade this parse failure for silently wrong rows on
  PostgreSQL, the Unicode fold #4706 Q1 = A rules out.
- The pins that moved are re-aimed at the property, not regenerated, and the
  pre-fix bytes are kept as a control that the engine still refuses them.
- `SqliteWasmDriver`'s `isSqlite` override — 0 direct test hits, the sole
  reason no in-repo SQLite driver lands on this arm — gets a direct pin, with a
  control showing the base class answers `unknown` for that very config.

Refs #16028

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

Author: claude

packages/drivers/driver-sqlite-wasm/src/sqlite-wasm-dialect-identity.test.ts

@@ -0,0 +1,87 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#16028] The `isSqlite` override, pinned DIRECTLY — the one thing that makes
+ * this transport answer `"sqlite"` when something outside the driver asks which
+ * SQL it speaks.
+ *
+ * ## Why this file exists
+ *
+ * `SqlDriver.dialectName` is public for exactly one consumer:
+ * `service-analytics` compiles its own statements (an analytics `where`, an
+ * ADR-0021 D-C read scope, the `/analytics/sql` echo) and needs the same
+ * per-dialect construct choices the driver makes. Answering `'sqlite'` is what
+ * routes `$icontains` onto `lower(col) GLOB lower(?)`; answering `'unknown'`
+ * routes it onto the residue arm instead.
+ *
+ * The base class derives that answer by STRING-MATCHING `config.client` against
+ * {@link SqlDriver}'s emission sets — and this transport passes a knex Client
+ * CLASS, which is no string at all. So the correct answer here is produced by
+ * one three-line override and by nothing else.
+ *
+ * ⚠️ #16028 measured that override at **0 direct test hits**: the only cover was
+ * an indirect row-set pin (#15684), which would keep passing if the override
+ * moved, because the ROWS come out the same either way — the driver runs its own
+ * SQL through its own SQLite. What changes silently is the answer handed to a
+ * package that compiles SQL for a DIFFERENT engine. That is the gap this file
+ * closes, and it is the reason the control below is not decoration: it shows the
+ * base class answering `'unknown'` for this exact config, so the pin above is a
+ * measurement of the override rather than of the class hierarchy.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { SqlDriver } from '@objectstack/driver-sql';
+
+import { SqliteWasmDriver } from '../src/index.js';
+
+/** Nothing here connects — but every knex instance built is still torn down. */
+const opened: Array<{ disconnect(): Promise<void> }> = [];
+const dirs: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(opened.splice(0).map((d) => d.disconnect().catch(() => {})));
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+const track = <T extends { disconnect(): Promise<void> }>(d: T): T => {
+  opened.push(d);
+  return d;
+};
+
+describe('[#16028] SqliteWasmDriver names its dialect', () => {
+  it('answers "sqlite" — the answer service-analytics compiles against', () => {
+    // Read WITHOUT connecting, deliberately: `service-analytics` asks this
+    // while BUILDING a statement, so an answer that needed a live pool would
+    // arrive after the SQL it decides.
+    expect(track(new SqliteWasmDriver({ filename: ':memory:' })).dialectName).toBe('sqlite');
+  });
+
+  it('…on a file-backed database too, and with persistence on', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'wasm-dialect-'));
+    dirs.push(dir);
+    const file = join(dir, 'test.db');
+    expect(track(new SqliteWasmDriver({ filename: file })).dialectName).toBe('sqlite');
+    expect(track(new SqliteWasmDriver({ filename: file, persist: 'on-write' })).dialectName).toBe('sqlite');
+  });
+
+  it('the client is a CLASS, so no string table could have answered it', () => {
+    // The override's premise, asserted rather than assumed: if this ever became
+    // a string knex spelling, the base class would answer on its own and the
+    // override would be dead code rather than the load-bearing line it is.
+    const client = (SqliteWasmDriver.toKnexConfig({ filename: ':memory:' }) as { client: unknown }).client;
+    expect(typeof client).toBe('function');
+    expect(typeof client).not.toBe('string');
+  });
+
+  it('CONTROL: the base class answers "unknown" for this very config', () => {
+    // Delete `isSqlite` from the subclass and this is what `service-analytics`
+    // would be told — #16028's residue arm, which for `$icontains` emitted a
+    // statement SQLite cannot parse at all until that card. This is what makes
+    // the pin above a measurement of the OVERRIDE rather than of the hierarchy.
+    const base = track(new SqlDriver(SqliteWasmDriver.toKnexConfig({ filename: ':memory:', pool: { min: 0, max: 1 } })));
+    expect(base.dialectName).toBe('unknown');
+  });
+});

packages/services/service-analytics/src/__tests__/icontains-dialect-sql.test.ts

@@ -30,14 +30,27 @@
  *   - **postgres → byte-identical text.** `translate()` is correct there today,
  *     so the correct diff is no diff: the emitted SQL and params are asserted
  *     verbatim against the pre-#15780 bytes, for all three compilers.
- *   - **`unknown` (no hook wired) → byte-identical text, ALSO `translate()`.**
- *     The residue keeps the shape it has always had. It is not an endorsement:
- *     it is what still runs on the dialects nothing here models (mssql, oracle,
- *     which do have `translate()`), and falling back to `LOWER()` for it would
- *     silently restore the Unicode fold #4706 Q1 = A took away. Note this
- *     DIVERGES from `driver-sql`'s `unknown` arm, which folds with `LOWER()` —
- *     each side keeps its own pre-existing residue, and neither claims the
- *     other's.
+ *   - **[#16028] `unknown` (no hook wired) → the portable `REPLACE` chain,
+ *     EXECUTED.** #15780 left this arm on `translate()` and called it
+ *     unbroken, which held only for the dialects the arm was PICTURED as
+ *     (mssql, oracle, which have `translate()`). `unknown` is not a dialect:
+ *     `normalizeSqlDialect` routes EVERYTHING it cannot name here, SQLite
+ *     included, so the residue arm carried the whole defect forward for the
+ *     four embedder compositions #16028 lists — among them a public
+ *     `AnalyticsService` constructed with its OPTIONAL `sqlDialect` left out.
+ *     The arm now folds with one nested `REPLACE` per ASCII letter, which every
+ *     SQL dialect parses, and the rows it answers on this engine are asserted
+ *     below from the same shared table the `sqlite` arm answers.
+ *
+ *     ⛔ NOT `LOWER()`, which is what `driver-sql`'s `unknown` arm folds with:
+ *     `LOWER()` follows the collation, so adopting it would trade this parse
+ *     failure for SILENTLY wrong rows on PostgreSQL — the Unicode fold #4706
+ *     Q1 = A rules out. ⚠️ And measuring `LOWER()` HERE proves nothing about
+ *     that, because SQLite's `lower()` is ASCII-only and answers the shared
+ *     table correctly: the trap is a green SQLite reading standing in for a
+ *     PostgreSQL one, so the `REPLACE` chain is pinned as ASCII-only BY
+ *     CONSTRUCTION (over every ASCII code point, below) rather than by a fold
+ *     that happens to behave on the one engine in this container.
  *   - **mysql → NOT MEASURED.** The nested-`REPLACE`-over-`CAST(… AS BINARY)`
  *     arm is asserted as TEXT only. No MySQL server is provisionable in this
  *     container — the same declared skip `driver-sql`'s #6518 suite and this
@@ -119,40 +132,118 @@ const ctxFor = (dialect?: string): DatasetScopedStrategyContext =>
 const TRANSLATE_FOLD =
   "translate(name, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz')";
 
+/**
+ * [#16028] The `unknown` arm's fold, rebuilt HERE from the ruled domain rather
+ * than imported from the implementation — a second construction of the expected
+ * text, so a change to the emitter's loop does not quietly re-bless itself.
+ *
+ * The endpoints are pinned verbatim beside every use (`REPLACE(name, 'A', 'a')`
+ * innermost, `'Z', 'z')` outermost), which is also what discriminates this arm
+ * from MySQL's: that one's innermost operand is `CAST(name AS BINARY)`.
+ */
+const ASCII_UP = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+const ASCII_LO = 'abcdefghijklmnopqrstuvwxyz';
+const replaceFold = (expr: string): string => {
+  let out = expr;
+  for (let i = 0; i < ASCII_UP.length; i++) out = `REPLACE(${out}, '${ASCII_UP[i]}', '${ASCII_LO[i]}')`;
+  return out;
+};
+
 describe('[#15780] the compiled TEXT, per dialect — all three compilers', () => {
   const nativeSql = async (where: unknown, dialect?: string) =>
     new NativeSQLStrategy().generateSql(query(where), ctxFor(dialect));
   const echoSql = async (where: unknown, dialect?: string) =>
     new ObjectQLStrategy().generateSql(query(where), ctxFor(dialect));
 
-  it('postgres and a host that wired NO hook keep the pre-#15780 bytes exactly', async () => {
-    // The non-regression half, for the two dialects that were already correct.
-    // Asserted verbatim, not by shape: `translate()` is right on Postgres, and
-    // the `unknown` residue must keep the only fold that still runs there.
-    for (const dialect of [undefined, 'postgres'] as const) {
+  it('postgres keeps the pre-#15780 bytes exactly — the arm that was always right', async () => {
+    // The non-regression half. Asserted verbatim, not by shape: `translate()`
+    // is correct on Postgres, so the correct diff there is no diff — through
+    // #15780 and through #16028 alike.
+    const out = await nativeSql({ name: { $icontains: 'acme' } }, 'postgres');
+    expect(out.sql).toContain(
+      `WHERE ${TRANSLATE_FOLD} LIKE translate($1, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz') ESCAPE $2`,
+    );
+    expect(out.params).toEqual(['%acme%', '\\']);
+
+    const echo = await echoSql({ name: { $icontains: 'acme' } }, 'postgres');
+    expect(echo.sql).toContain(
+      `${TRANSLATE_FOLD} LIKE translate($1, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz') ESCAPE $2`,
+    );
+    expect(echo.params).toEqual(['%acme%', '\\']);
+
+    expect(
+      compileScopedFilterToSql({ name: { $icontains: 'acme' } } as FilterCondition, 't', { dialect: 'postgres' }),
+    ).toEqual({
+      sql:
+        `translate("t"."name", 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz') LIKE ` +
+        `translate(?, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz') ESCAPE ?`,
+      params: ['%acme%', '\\'],
+    });
+  });
+
+  it('[#16028] a host that wired NO hook folds with the PORTABLE chain, on all three compilers', async () => {
+    // The moved cells, stated as the pin rather than left to a regenerate: the
+    // `unknown` arm's emitted text CHANGED, from `translate()` — which SQLite
+    // and MySQL/MariaDB cannot parse — to a nested `REPLACE` per ASCII letter,
+    // which every SQL dialect can. The rows this text answers are executed
+    // further down; here it is the bytes and the bindings.
+    for (const dialect of [undefined, 'oracle', 'libsql'] as const) {
+      // All three normalize to `unknown`: an unset hook, and two spellings
+      // `normalizeSqlDialect` does not model. One arm, reached three ways.
       const out = await nativeSql({ name: { $icontains: 'acme' } }, dialect);
       expect(out.sql, String(dialect)).toContain(
-        `WHERE ${TRANSLATE_FOLD} LIKE translate($1, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz') ESCAPE $2`,
+        `WHERE ${replaceFold('name')} LIKE ${replaceFold('$1')} ESCAPE $2`,
       );
+      expect(out.sql, String(dialect)).not.toMatch(/translate\(/);
+      // The chain's endpoints, verbatim — and the innermost operand is the bare
+      // column, which is what tells this arm apart from MySQL's `CAST(… AS
+      // BINARY)` one.
+      expect(out.sql, String(dialect)).toContain("REPLACE(name, 'A', 'a')");
+      expect(out.sql, String(dialect)).toContain("'Z', 'z')");
+      expect(out.sql, String(dialect)).not.toMatch(/CAST\(/);
       expect(out.params, String(dialect)).toEqual(['%acme%', '\\']);
 
       const echo = await echoSql({ name: { $icontains: 'acme' } }, dialect);
       expect(echo.sql, `echo ${String(dialect)}`).toContain(
-        `${TRANSLATE_FOLD} LIKE translate($1, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz') ESCAPE $2`,
+        `${replaceFold('name')} LIKE ${replaceFold('$1')} ESCAPE $2`,
       );
+      expect(echo.sql, `echo ${String(dialect)}`).not.toMatch(/translate\(/);
       expect(echo.params, `echo ${String(dialect)}`).toEqual(['%acme%', '\\']);
     }
 
+    // The read scope — the compiler where an unevaluable statement is an
+    // ADR-0021 policy that cannot be applied at all.
     const noHook = compileScopedFilterToSql({ name: { $icontains: 'acme' } } as FilterCondition, 't');
     expect(noHook).toEqual({
-      sql:
-        `translate("t"."name", 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz') LIKE ` +
-        `translate(?, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz') ESCAPE ?`,
+      sql: `${replaceFold('"t"."name"')} LIKE ${replaceFold('?')} ESCAPE ?`,
       params: ['%acme%', '\\'],
     });
+    expect(noHook.sql).not.toMatch(/translate\(/);
     expect(
-      compileScopedFilterToSql({ name: { $icontains: 'acme' } } as FilterCondition, 't', { dialect: 'postgres' }),
+      compileScopedFilterToSql({ name: { $icontains: 'acme' } } as FilterCondition, 't', { dialect: 'nonesuch' }),
     ).toEqual(noHook);
+
+    // ⛔ And the arm did NOT become Postgres's: the two are now different text,
+    // which is the whole point of splitting them.
+    const pg = await nativeSql({ name: { $icontains: 'acme' } }, 'postgres');
+    const unknown = await nativeSql({ name: { $icontains: 'acme' } }, undefined);
+    expect(unknown.sql).not.toBe(pg.sql);
+    expect(unknown.params).toEqual(pg.params);
+  });
+
+  it('[#16028] the case-EXACT four are byte-identical on `unknown` — only the FOLD moved', async () => {
+    // The blast-radius pin. `fold` is the only thing #16028 changed on this
+    // arm, so every case-exact operator must still emit the plain `LIKE` it
+    // emitted before — no `REPLACE` anywhere near them.
+    for (const op of ['$contains', '$notContains', '$startsWith', '$endsWith'] as const) {
+      const out = await nativeSql({ name: { [op]: 'acme' } }, undefined);
+      expect(out.sql, op).not.toMatch(/REPLACE\(|translate\(|lower\(/);
+      expect(out.sql, op).toMatch(/name (NOT )?LIKE \$1 ESCAPE \$2/);
+    }
+    expect(compileScopedFilterToSql({ name: { $contains: 'acme' } } as FilterCondition, 't')).toEqual({
+      sql: '"t"."name" LIKE ? ESCAPE ?',
+      params: ['%acme%', '\\'],
+    });
   });
 
   it('sqlite compiles lower() over GLOB — one bound value, no ESCAPE clause', async () => {
@@ -274,16 +365,81 @@ describe('[#15780] the three compilers, EXECUTED on a real SQLite engine', () =>
     ]);
   });
 
-  it('the defect, still reachable through a host that answers no dialect — so these pins discriminate', async () => {
-    // Before-red, stated as the engine's own refusal rather than argued: the
-    // `unknown` residue still emits `translate()`, and this engine cannot parse
-    // it. This is the control that keeps every green assertion above honest.
+  it('[#16028] the PRE-fix bytes are still refused by this engine — the control the greens rest on', () => {
+    // Before-red, kept as a control rather than deleted with the defect. This
+    // is the statement the `unknown` arm emitted until #16028, rebuilt here and
+    // handed to the engine: it does not parse. Every green below is therefore a
+    // measurement of the CHANGE, not of an engine that would have accepted
+    // anything.
+    const preFix =
+      `SELECT "id" FROM "rows" WHERE ${TRANSLATE_FOLD} LIKE ` +
+      `translate(?, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz') ESCAPE ?`;
+    expect(() => run(preFix, ['%acme%', '\\'])).toThrow(/no such function: translate/);
+  });
+
+  it('[#16028] a host that answers NO dialect now compiles a statement this engine RUNS', async () => {
+    // The card's headline, executed: with no `sqlDialect` hook wired — the
+    // shape a directly-constructed public `AnalyticsService` has when its
+    // OPTIONAL field is omitted — the compiled `where` used to be refused by
+    // the engine. It now parses, and it answers the shared table's rows.
     const { sql, params } = await new NativeSQLStrategy().generateSql(
       query({ name: { $icontains: 'acme' } }),
       unawareCtx,
     );
-    expect(sql).toContain('translate(');
-    expect(() => run(sql, params)).toThrow(/no such function: translate/);
+    expect(sql).not.toMatch(/translate\(/);
+    expect(run(sql, params)).toEqual(['1', '2']);
+  });
+
+  it('[#16028] the `unknown` arm answers the shared $icontains table — all three compilers', async () => {
+    // The same rows the `sqlite` arm is required to answer, required of the
+    // residue arm. Executed on sql.js 1.14.1, the engine `driver-sqlite-wasm`
+    // runs — which is what an `unknown` dialect that is really SQLite IS.
+    for (const c of NAME_ICONTAINS) {
+      expect(await executedIds(c.filter, unawareCtx), c.name).toEqual([...c.expected]);
+
+      const scoped = {
+        ...unawareCtx,
+        getReadScope: (object: string) => (object === 'rows' ? (c.filter as FilterCondition) : null),
+      } as DatasetScopedStrategyContext;
+      const viaScope = await new NativeSQLStrategy().generateSql(query(undefined), scoped);
+      expect(viaScope.sql, `read scope: ${c.name}`).not.toMatch(/translate\(/);
+      expect(run(viaScope.sql, viaScope.params), `read scope: ${c.name}`).toEqual([...c.expected]);
+
+      const echo = await new ObjectQLStrategy().generateSql(query(c.filter), unawareCtx);
+      expect(echo.sql, `echo: ${c.name}`).not.toMatch(/translate\(/);
+      expect(run(echo.sql, echo.params), `echo: ${c.name}`).toEqual([...c.expected]);
+    }
+  });
+
+  it('[#16028] the portable chain folds ASCII and NOTHING else — every code point, executed', () => {
+    // The property the arm rests on, measured instead of argued, because the
+    // one thing that must never happen here is a fold that reaches past `A`-`Z`
+    // (#4706 Q1 = A). Two halves:
+    //
+    //   1. the chain equals the simultaneous `A`-`Z` map — i.e. applying the 26
+    //      REPLACEs IN SEQUENCE cannot cascade, because every step writes a
+    //      lower-case letter and every later step matches an upper-case one;
+    //   2. it touches nothing else — no accented letter, and none of the LIKE
+    //      metacharacters the escaping depends on staying literal.
+    const asciiLower = (v: string) =>
+      v.replace(/[A-Z]/g, (ch) => ASCII_LO[ASCII_UP.indexOf(ch)]);
+    const probes = [
+      ...Array.from({ length: 128 }, (_, i) => String.fromCharCode(i)).filter((ch) => ch !== '\0'),
+      'CAFÉ', 'café', 'ÀÉÎÕÜ', 'ÄÖÜ', 'ǍǏǑ', 'ΑΒΓ', 'АБВ', 'İIı',
+      'ACME Corp', '100% match', 'a_b', 'A\\B', 'ZzAa',
+    ];
+    for (const probe of probes) {
+      const literal = probe.replace(/'/g, "''");
+      const got = db.exec(`SELECT ${replaceFold(`'${literal}'`)}`)[0].values[0][0];
+      expect(got, JSON.stringify(probe)).toBe(asciiLower(probe));
+    }
+    // ⚠️ And the control that says why `LOWER()` may not be adopted here even
+    // though it passes on THIS engine: SQLite's `lower()` is ASCII-only, so it
+    // agrees with the chain on every probe above. It is PostgreSQL's, which is
+    // collation-aware, that would fold `É` — and no PostgreSQL server is
+    // provisionable in this container. So this cell is why the arm is chosen by
+    // CONSTRUCTION and not by what happens to pass locally.
+    expect(db.exec(`SELECT lower('CAFÉ')`)[0].values[0][0]).toBe('cafÉ');
   });
 
   it('NativeSQLStrategy answers the shared table\'s $icontains rows', async () => {