@@ -0,0 +1,9 @@
+---
+'@objectstack/core': patch
+---
+
+`jsonColumnOperatorRefusalText` takes an optional fourth argument: the class of JSON column the refused operator met, `JsonColumnFieldClass` (now exported). `'multi-value-or-json'` is the default, and its words are unchanged. `'single-value-media'` words the refusal for a single-value file-class field that a SQL deployment still stores as a JSON column.
+
+Clause-②: no
+
+A single-value file-class field (`file`, `image`, `avatar`, `video`, `audio`) is stored as a JSON column only on a deployment inside the ADR-0104 dual-encoding window, whose media columns have not moved. There it holds one JSON string, so `$contains` with the field's exact id answers no rows. That class's refusal no longer prescribes `$contains`. It says that the field answers these operators again once the deployment finishes the media-column move (the column step of `objectstack migrate files-to-references --apply`), and it still names `$null` / `$empty` for "no value". The message stays under the REST envelope's 500-character bound. Which operators are refused, and on which fields, does not change.
@@ -0,0 +1,9 @@
+---
+'@objectstack/driver-sql': patch
+---
+
+On a deployment whose media columns have not moved, the JSON-column filter refusal on a single-value file-class field (`file`, `image`, `avatar`, `video`, `audio`) now names the repair that works there: the media-column move, not `$contains`.
+
+Clause-②: no
+
+The filter is still refused with `INVALID_FILTER` / 400, for the same operators as before (`$eq`, `$in`, `$startsWith`, `$icontains`, the orderings and the rest of that set, and the bare `{ field: value }` spelling). Before, the refusal told the caller to use `$contains`, the membership repair for a multi-valued field. On a single-value file-class field `$contains` with the field's exact id answers no rows. The refusal now says that the field answers these operators again once the deployment finishes the media-column move (the column step of `objectstack migrate files-to-references --apply`), and it still names `$null` / `$empty`, which answer there. A multi-valued field keeps the `$contains` words, byte for byte. Once the media columns have moved, these filters are not refused, as before.
@@ -0,0 +1,11 @@
+---
+'@objectstack/driver-turso': minor
+---
+
+Both transports now word the JSON-column filter refusal on a single-value file-class field (`file`, `image`, `avatar`, `video`, `audio`) the way `@objectstack/driver-sql` does: the media-column move, not `$contains`, which answers no rows on that field.
+
+Clause-②: no
+
+The local transport inherits the new words from `SqlDriver`. The remote transport refuses in its own filter compiler, and now reads the same class from the driver, so one filter gets one message on both transports. The refused operators and fields do not change. Remote mode never moves its media columns, so a single-value file-class field is a JSON column there on every deployment; the remote transport refuses to plan the column step of `objectstack migrate files-to-references` (`NOT_IMPLEMENTED` / 501), as before, so on that transport the prescribed move is not yet available.
+
+`RemoteTransport.setJsonColumnResolver` now takes a resolver that answers the column's class (`JsonColumnFieldClass`, from `@objectstack/core`), or `undefined` for a column that is not JSON, in place of `true` / `false`. `TursoDriver` supplies it. A host that calls the method itself returns `'multi-value-or-json'` where it returned `true`, and `undefined` where it returned `false`. That replaces the setter's published parameter type, so a host resolver that returns a boolean no longer compiles: a host that injects its own resolver updates its signature, which is why this release is `minor`.
@@ -28,12 +28,22 @@
  *
  * A deliberate change of wording updates the hashes in the PR that makes it —
  * and then reaches every face alike, which is the point of the move.
+ *
+ * [#21236] The second class of JSON column, a single-value file-class field
+ * inside the ADR-0104 window, has its own reason and repair (the media-column
+ * move), pinned the same three ways at the foot of this file. The first
+ * class's words are the control: its hashes above did not move, and the
+ * default class is the first class, byte for byte.
  */
 
 import { describe, it, expect } from 'vitest';
 import { createHash } from 'node:crypto';
 import { truncateClientMessage } from '@objectstack/types';
-import { JSON_COLUMN_INCOMPATIBLE_OPERATORS, jsonColumnOperatorRefusalText } from './json-column-operator-refusal.js';
+import {
+  JSON_COLUMN_INCOMPATIBLE_OPERATORS,
+  jsonColumnOperatorRefusalText,
+  type JsonColumnFieldClass,
+} from './json-column-operator-refusal.js';
 
 const sha256 = (text: string): string => createHash('sha256').update(text, 'utf8').digest('hex');
 
@@ -151,3 +161,75 @@ describe('[#21067] jsonColumnOperatorRefusalText — whole on the wire, and true
     expect(truncateClientMessage(diagnostic)).toBe(diagnostic);
   });
 });
+
+describe('[#21236] jsonColumnOperatorRefusalText — a single-value file-class field inside the ADR-0104 window', () => {
+  const MEDIA: JsonColumnFieldClass = 'single-value-media';
+  /** Every spelling that gets this refusal: each member of the set, and the bare one. */
+  const SPELLINGS: ReadonlyArray<readonly [op: string, bare: boolean]> = [
+    ...[...JSON_COLUMN_INCOMPATIBLE_OPERATORS].map((op) => [op, false] as const),
+    ['=', true],
+  ];
+  /** The move, as the migration entry `filter-text-operator-declared-type-refused` words it. */
+  const MOVE =
+    'Such a field is not a membership question: it answers these operators again once this deployment ' +
+    'finishes the media-column move (the column step of `objectstack migrate files-to-references --apply`).';
+
+  it('the words, by hash: one message for every operator, and a diagnostic per spelling', () => {
+    const MESSAGE = { sha: 'd76a61be45a1f2200179f7282e4cbe50685ad32f65124f55fc79eb7a2876fd22', length: 485 };
+    for (const [op, bare, diagnostic] of [
+      ['$startsWith', false, { sha: '9ee94859d50fc05f124ee2c1620c20d140c9572d2eb680bab3a45205a0b66de6', length: 418 }],
+      ['$eq', false, { sha: '8e976c33c09a3c91ba135179caf47497ad1fbe7d1b8bc8c29ae5363512af83d8', length: 402 }],
+      ['=', true, { sha: '40f4606c544acab304594079b6a8c9ded6fabfb7b2a9e037932e96aa0ca5e988', length: 414 }],
+    ] as const) {
+      const text = jsonColumnOperatorRefusalText('attachment', op, bare, MEDIA);
+      expect({ sha: sha256(text.message), length: text.message.length }, op).toEqual(MESSAGE);
+      expect({ sha: sha256(text.diagnostic), length: text.diagnostic.length }, op).toEqual(diagnostic);
+    }
+  });
+
+  it('prescribes the media-column move and the presence spellings, and never $contains', () => {
+    for (const [op, bare] of SPELLINGS) {
+      const { message, diagnostic } = jsonColumnOperatorRefusalText('attachment', op, bare, MEDIA);
+      for (const text of [message, diagnostic]) {
+        expect(text, op).toContain('at a single-value file-class field still stored as JSON.');
+        expect(text, op).toContain(MOVE);
+        expect(text, op).toContain('For no value, use "$null" or "$empty".');
+        expect(text, op).not.toContain('$contains');
+        expect(text, op).not.toContain('which it cannot test for one member');
+      }
+      expect(message.startsWith('A constraint in this filter WAS NOT APPLIED: ')).toBe(true);
+      expect(message.endsWith(
+        'The field and the operator are withheld from the message; the full diagnostic is in the server log.',
+      )).toBe(true);
+      expect(message, op).not.toContain('attachment');
+      expect(diagnostic, op).toContain(`it aims "${op}", a scalar comparison or text operator, at`);
+    }
+  });
+
+  it('the message passes the REST envelope\'s bound unchanged, for every refused spelling', () => {
+    for (const [op, bare] of SPELLINGS) {
+      const { message } = jsonColumnOperatorRefusalText('attachment', op, bare, MEDIA);
+      expect(truncateClientMessage(message), op).toBe(message);
+    }
+  });
+
+  it('the diagnostic is whole on the wire for a 91-character field name, the bound the module docblock states', () => {
+    const name = 'f'.repeat(91);
+    for (const [op, bare] of SPELLINGS) {
+      const { diagnostic } = jsonColumnOperatorRefusalText(name, op, bare, MEDIA);
+      expect(truncateClientMessage(diagnostic), op).toBe(diagnostic);
+    }
+    const past = jsonColumnOperatorRefusalText(`${name}f`, '$startsWith', false, MEDIA).diagnostic;
+    expect(truncateClientMessage(past)).not.toBe(past);
+  });
+
+  it('the control: the default class IS the multi-value class, and its words are not the media class\'s', () => {
+    for (const [op, bare] of SPELLINGS) {
+      const byDefault = jsonColumnOperatorRefusalText('members', op, bare);
+      const named = jsonColumnOperatorRefusalText('members', op, bare, 'multi-value-or-json');
+      expect(named, op).toEqual(byDefault);
+      expect(byDefault.message, op).toContain('{ "FIELD": { "$contains": "a" } }');
+      expect(jsonColumnOperatorRefusalText('members', op, bare, MEDIA).message, op).not.toBe(byDefault.message);
+    }
+  });
+});
@@ -50,6 +50,28 @@
  * and then the any-of example last, so a longer name pushes those out first;
  * the any-of example survives up to 36 characters.
  *
+ * ## Two classes of JSON column, two repairs
+ *
+ * [#21236] The membership repair is right for a field that IS a list or a
+ * structured value, which is every JSON column the engine and `driver-memory`
+ * meet. The SQL family meets one more: on a deployment still inside the
+ * ADR-0104 dual-encoding window (its media columns not yet moved),
+ * `driver-sql` stores a SINGLE-VALUE file-class field (`file`, `image`,
+ * `avatar`, `video`, `audio`) as a JSON column too, holding one JSON string.
+ * There is no member to find there: measured on SQLite through `SqlDriver`,
+ * `$contains` with the field's exact id answered no rows, while the same
+ * `$startsWith` answered rows once the columns had moved. So that class gets
+ * its own reason and its own repair, the media-column move, in the words the
+ * migration entry `filter-text-operator-declared-type-refused` gives it
+ * (`@objectstack/spec`). The face knows the class and passes it
+ * ({@link JsonColumnFieldClass}); this module never reads a declaration. The
+ * operator set, the presence spellings and the "withheld" sentence are the
+ * same for both classes. Only the SQL family meets the second class, so its
+ * reason may name the storage the window leaves behind, where the first
+ * class's must not. Its message is held under the same bound by the same pin;
+ * its diagnostic names the field once, and is whole on the wire for a field
+ * name of up to 91 characters.
+ *
  * ## The other half of the JSON column's contract
  *
  * `$contains` is the membership spelling on such a column (`FILTER_OPERATORS`'
@@ -126,6 +148,28 @@ export const JSON_COLUMN_INCOMPATIBLE_OPERATORS: ReadonlySet<string> = new Set([
   '$startsWith', '$endsWith', '$icontains', '$like', '$ilike',
 ]);
 
+/**
+ * [#21236] Which class of JSON column a refused operator met. The class decides
+ * the reason the refusal gives and the repair it prescribes.
+ *
+ * - `'multi-value-or-json'`: a multi-value field (`multiple: true`, or an
+ *   inherently multi-value option type) or a structured-JSON type. Such a
+ *   column is JSON on every deployment, and its repair is membership:
+ *   `$contains`, or an `$or` of `$contains` for any-of.
+ * - `'single-value-media'`: a single-value file-class field that a SQL
+ *   deployment inside the ADR-0104 dual-encoding window still stores as a JSON
+ *   column. The column holds one JSON string, so this is not a membership
+ *   question. Its repair is the media-column move, after which the column
+ *   holds the bare id and these operators answer again.
+ *
+ * The face decides the class from its own registries; the builder only words
+ * it. `driver-sql`, and `driver-turso`'s two faces that ask its registries, are
+ * the only faces that meet the second class. The engine's per-aggregation
+ * `filter` and `driver-memory` never store a single-value file-class field as
+ * JSON, so they meet only the first, which is the default.
+ */
+export type JsonColumnFieldClass = 'multi-value-or-json' | 'single-value-media';
+
 /** The two texts of one JSON-column refusal — see {@link jsonColumnOperatorRefusalText}. */
 export interface JsonColumnOperatorRefusalText {
   /**
@@ -150,12 +194,18 @@ export interface JsonColumnOperatorRefusalText {
  * prints them — see the module docblock. Shared by both texts, so the message
  * and the diagnostic cannot come to give two reasons; the diagnostic passes
  * `op` and so names the operator, the bare spelling's as `=`.
+ *
+ * [#21236] The field's half of the reason is its class's. A single-value
+ * file-class field is not a field "it cannot test for one member": it has no
+ * members, so its reason says what the window left behind instead.
  */
-function refusalReason(op?: string): string {
+function refusalReason(fieldClass: JsonColumnFieldClass, op?: string): string {
   const operator = op === undefined
     ? 'a scalar comparison or text operator'
     : `"${op}", a scalar comparison or text operator,`;
-  return `it aims ${operator} at a multi-value or JSON field, which it cannot test for one member.`;
+  return fieldClass === 'single-value-media'
+    ? `it aims ${operator} at a single-value file-class field still stored as JSON.`
+    : `it aims ${operator} at a multi-value or JSON field, which it cannot test for one member.`;
 }
 
 /**
@@ -179,6 +229,30 @@ function containsRemedy(name: string): string {
   );
 }
 
+/**
+ * [#21236] The prescription for a single-value file-class field whose column is
+ * still JSON: the media-column move, which makes the column hold the bare id.
+ * It agrees with the migration entry `filter-text-operator-declared-type-refused`
+ * (`@objectstack/spec`), which says that such a field "is not a membership
+ * question: it answers text operators again once its deployment finishes the
+ * media-column move". The equality and ordering operators answer again too,
+ * hence "these operators". `$contains` is not named: on that column it answers
+ * no rows.
+ *
+ * The presence clause stays. `$null` and `$empty` are outside the refused set,
+ * and they answer on that column: `$empty` takes the spec's null-only row for
+ * a file-class type, so both are `IS NULL`.
+ */
+const MEDIA_COLUMN_MOVE_REMEDY =
+  'Such a field is not a membership question: it answers these operators again once this ' +
+  'deployment finishes the media-column move (the column step of ' +
+  `\`objectstack migrate files-to-references --apply\`). ${PRESENCE_REMEDY}`;
+
+/** [#21236] The prescription for `fieldClass`, spelled with `name` in the field position where it has one. */
+function refusalRemedy(fieldClass: JsonColumnFieldClass, name: string): string {
+  return fieldClass === 'single-value-media' ? MEDIA_COLUMN_MOVE_REMEDY : containsRemedy(name);
+}
+
 /**
  * [#7398] The words of the refusal: a scalar-comparison operator met a field
  * stored as JSON TEXT, so the comparison can never mean what the caller wrote.
@@ -225,20 +299,29 @@ function containsRemedy(name: string): string {
  * withheld; it is now 486, with the presence spellings a `null` comparand
  * needs (see `PRESENCE_REMEDY`). The mechanism above stays here, where the
  * next author reads it.
+ *
+ * [#21236] `fieldClass` is the class of JSON column the operator met
+ * ({@link JsonColumnFieldClass}). The default, `'multi-value-or-json'`, gives
+ * the words above unchanged. `'single-value-media'` gives the media-column
+ * move as the repair: on a single-value file-class field inside the ADR-0104
+ * window, `$contains` answered no rows. A face that can hold such a field as
+ * JSON passes the class it read from its own registries.
  */
 export function jsonColumnOperatorRefusalText(
   field: string,
   op: string,
   bare: boolean,
+  fieldClass: JsonColumnFieldClass = 'multi-value-or-json',
 ): JsonColumnOperatorRefusalText {
   const subject = bare
     ? `The bare equality spelling { "${field}": value }`
     : `Operator "${op}" on field "${field}"`;
   return {
     message:
-      `A constraint in this filter WAS NOT APPLIED: ${refusalReason()} ${containsRemedy('FIELD')} ` +
+      `A constraint in this filter WAS NOT APPLIED: ${refusalReason(fieldClass)} ` +
+      `${refusalRemedy(fieldClass, 'FIELD')} ` +
       `The field and the operator are withheld from the message; the full diagnostic is in the ` +
       `server log.`,
-    diagnostic: `${subject} WAS NOT APPLIED: ${refusalReason(op)} ${containsRemedy(field)}`,
+    diagnostic: `${subject} WAS NOT APPLIED: ${refusalReason(fieldClass, op)} ${refusalRemedy(fieldClass, field)}`,
   };
 }