@@ -0,0 +1,17 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): the `resolveSearchFieldResolution` docblock says a declared search column whose type can never hold a string is admitted to the set but contributes no clause
+
+Clause-②: no
+Metadata-protocol: none
+
+The declared-branch text on `resolveSearchFieldResolution` (`@objectstack/spec`, shipped in its `.d.ts`) still said a `json` column declared in `searchableFields` is "a scan that CAN match". The `$search` expansion in `@objectstack/objectql` gives such a column no clause: its declared type can never hold a string, which is the text-operator door's `door-refusal` verdict (`textOperatorDoorVerdict`). The docblock now says so:
+
+- a declared `json` column (or any numeric, boolean, date or time, or structured-JSON column, or a `formula` whose `returnType` names one) is still admitted to the set, but contributes no clause;
+- a set made only of such columns answers no rows, never an error;
+- a declared single-valued `lookup` column still matches by substring over the stored foreign key;
+- only an entry that names no column at all is dropped, as before.
+
+Comment-only: no behaviour, schema or accepted value moves.
@@ -309,13 +309,17 @@ describe('a virtual field declared in searchableFields — not admitted, since n
 
   it('CONTROL — the declared branch still bypasses the auto-default exclusions', () => {
     // The dividing line is STORAGE, not search quality. `lookup` and `json` are
-    // auto-EXCLUDED types, and declaring them is still the author's choice: the
-    // engine runs a `$contains` over the stored foreign key / the stored JSON
-    // text. Narrow and rarely useful, but a scan that CAN match — so it must not
-    // be swept up by the virtual filter. This control is what keeps #6674 from
-    // silently becoming "the declared branch is type-filtered after all", which
-    // would reject metadata the runtime accepts (ADR-0072 D1, and the #4830
-    // changeset's explicit carve-out).
+    // auto-EXCLUDED types, and declaring them is still the author's choice, so
+    // both are ADMITTED here. What each then contributes is the expansion's call
+    // (`expandSearchToFilter`, `@objectstack/objectql`): `lookup` becomes an
+    // `$icontains` over the stored foreign key, a narrow scan that can match;
+    // [#29394] `json` can never hold a string (the text-operator door's
+    // `door-refusal` verdict), so it contributes NO clause, and a set made only
+    // of such columns answers no rows. Neither is swept up by the virtual
+    // filter, which drops only an entry with no column at all. This control is
+    // what keeps #6674 from silently becoming "the declared branch is
+    // type-filtered after all", which would reject metadata the runtime accepts
+    // (ADR-0072 D1, and the #4830 changeset's explicit carve-out).
     expect(
       resolveSearchFieldResolution({
         fields,
 
@@ -283,11 +283,23 @@ function autoDefaultFields(fields: Record<string, SearchFieldMeta>, displayField
  *
  * Filter 2 is deliberately NOT a type allow-list on the declared branch. The
  * declaration remains the author's explicit choice and still bypasses the
- * auto-default's exclusions: a `json` or `lookup` column declared here is
- * executed by the engine as a `$contains` over the stored JSON text / stored
- * foreign key — narrow, rarely useful, but a scan that CAN match. Only "there
- * is no column at all" is refused, which is why the vocabulary is a storage
- * fact rather than a search-quality one.
+ * auto-default's exclusions, so a `lookup` or `json` column declared here is
+ * ADMITTED to the set. What an admitted column then contributes to a search is
+ * the expansion's call (`expandSearchToFilter`, `@objectstack/objectql`), not
+ * this function's:
+ *
+ * - a single-valued `lookup` column becomes an `$icontains` over the stored
+ *   foreign key — narrow, rarely useful, but a scan that can match;
+ * - [#29394] a column whose DECLARED type can never hold a string — the
+ *   text-operator door's `door-refusal` verdict (`textOperatorDoorVerdict`,
+ *   `./filter-text-operator-declared-type`: numeric, boolean, calendar-date,
+ *   instant, clock-time and structured-JSON types such as `json`, plus a
+ *   `formula` whose readable `returnType` names one) — contributes NO clause.
+ *   A set made only of such columns answers no rows: never an error, never
+ *   every row.
+ *
+ * Only "there is no column at all" is refused, which is why the vocabulary is
+ * a storage fact rather than a search-quality one.
  *
  * Why the drop is not the whole fix. Dropping alone would only make the
  * declaration silently NARROWER — the failure mode #4254 exists to close on