@@ -0,0 +1,16 @@
+---
+'@objectstack/lint': patch
+---
+
+docs(lint): the `validateSearchableFields` module docblock says a declared search column whose type can never hold a string is admitted but contributes no clause
+
+Clause-②: no
+Metadata-protocol: none
+
+The module docblock of `validate-searchable-fields.ts` (`@objectstack/lint`, shipped in its `.d.ts`) still said a `json` or `lookup` column on an object's own `searchableFields` is "a scan that CAN match" via `$contains`. The `$search` expansion in `@objectstack/objectql` reads it differently, and the docblock now says so:
+
+- a declared `json` column (or any column whose declared type can never hold a string, the text-operator door's `door-refusal` verdict, `textOperatorDoorVerdict`) is 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 becomes an `$icontains` over the stored foreign key; a `multiple: true` one, a `$contains` membership match.
+
+Comment-only: no rule behaviour, finding or test moves.
@@ -216,9 +216,12 @@ describe('validateSearchableFields — what it deliberately does not flag', () =
   });
 
   it('does not flag a field that exists but is an odd search target', () => {
-    // An explicit `searchableFields` is authoritative — the engine scans
+    // An explicit `searchableFields` is authoritative — the runtime admits
     // exactly what it names — so declaring a json column is a choice, not
-    // drift. This rule answers existence only.
+    // drift. It is admitted but contributes no clause to the `$search`
+    // expansion (its declared type can never hold a string). This rule
+    // answers existence only: flagging it would reject metadata the runtime
+    // accepts (ADR-0072 D1).
     const findings = validateSearchableFields({
       objects: [
         {
@@ -536,9 +539,11 @@ describe('validateSearchableFields — list views that narrow the set', () => {
 
   it('passes a view entry of odd type once the object declares it searchable', () => {
     // The runtime's declared branch filters by EXISTENCE, never by type: a
-    // json/lookup column declared on the OBJECT is honored by the engine and
-    // admitted by the gate, so the view echoing it must stay green — flagging
-    // it would reject metadata the runtime accepts.
+    // json/lookup column declared on the OBJECT is admitted to the resolved
+    // set and by the gate (a json column contributes no clause to the
+    // `$search` expansion; a single lookup becomes an `$icontains` over the
+    // stored foreign key), so the view echoing it must stay green — flagging
+    // it would reject metadata the runtime accepts (ADR-0072 D1).
     const findings = validateSearchableFields({
       objects: [
         {
@@ -962,11 +967,13 @@ describe('[#6674] validateSearchableFields — a virtual formula entry', () => {
 
   it('CONTROL — a json or lookup entry on the OBJECT\'s own set stays clean', () => {
     // The carve-out #4830 wrote down, deliberately preserved: the runtime's
-    // declared branch executes those (a `$contains` over the stored JSON text /
-    // the stored foreign key). Narrow and rarely useful, but a scan that CAN
-    // match — flagging it would reject metadata the runtime accepts (ADR-0072
-    // D1). If this control ever goes red, #6674 has quietly become "the declared
-    // branch is type-filtered", which it is not.
+    // declared branch admits those. A json column contributes no clause to the
+    // `$search` expansion (its declared type can never hold a string); a single
+    // lookup becomes an `$icontains` over the stored foreign key, narrow and
+    // rarely useful but a scan that CAN match. Either way, flagging it would
+    // reject metadata the runtime accepts (ADR-0072 D1). If this control ever
+    // goes red, #6674 has quietly become "the declared branch is
+    // type-filtered", which it is not.
     expect(
       validateSearchableFields({
         objects: [
 
@@ -94,12 +94,19 @@
  *
  * The OBJECT's own `searchableFields` stays existence-only OTHERWISE, and the
  * dividing line is STORAGE, not search quality: the runtime's declared branch
- * filters by existence and scannability, never by type taste, so a json or
- * lookup column declared THERE is a choice the engine executes (a `$contains`
- * over the stored JSON text / the stored foreign key) — narrow, rarely useful,
- * but a scan that CAN match, so it is neither a 400 nor a finding. Flagging
- * those would reject metadata the runtime accepts — the false finding that
- * makes authors stop trusting the linter (ADR-0072 D1). A virtual entry is the
+ * filters by existence and scannability, never by type taste, so a lookup or
+ * json column declared THERE is admitted to the resolved set: neither a 400
+ * nor a finding. What it then contributes is the `$search` expansion's call
+ * (`expandSearchToFilter`, `@objectstack/objectql`). A single-valued lookup
+ * becomes an `$icontains` over the stored foreign key (a `multiple: true` one,
+ * a `$contains` membership match) — narrow, rarely useful, but a scan that
+ * CAN match. A column whose declared type can never hold a string — the
+ * text-operator door's `door-refusal` verdict (`textOperatorDoorVerdict`,
+ * `@objectstack/spec/data`), json among them — is admitted but contributes NO
+ * clause, and a set made only of such columns answers no rows, never an
+ * error. Flagging either would reject metadata the runtime accepts — the
+ * false finding that makes authors stop trusting the linter (ADR-0072 D1).
+ * A virtual entry is the
  * opposite case: no column exists on any driver, so admitting it is the
  * fail-open #4254 closed one axis over, surviving on the known-but-virtual
  * axis.