@@ -0,0 +1,10 @@
+---
+'@objectstack/objectql': patch
+---
+
+fix(objectql): temporal-comparand and text-operator filter refusals state what to write inside the 500-character client cap
+
+Clause-②: no
+Metadata-protocol: none
+
+`POST /api/v1/data/OBJECT/query` refuses a comparand a temporal field cannot read (`{ "created_date": { "$gte": "last_30_days" } }`, a year outside the field's range, an impossible day, a non-ISO spelling, a relative-date placeholder resolved outside the years) and a text operator aimed at a field that never holds a string (`{ "amount": { "$contains": "5" } }`) with `400 INVALID_FILTER`, in `where`, `aggregations[i].filter` and `having`. A client reads at most 500 characters of that message, and these refusals printed the prescription last, after the consequence, so it was often cut off. Each refusal now reads: what was written and why it is not a value of its kind, then what to write instead, then "NOT applied" and what the value would have done. The `datetime` prescription now names the relative-date placeholder first (`"{30_days_ago}"`), and the year-range prescriptions are shorter. The cap, the truncation, the code and the status are unchanged, and so is the set of filters refused.
@@ -285,20 +285,25 @@ describe('[#20263] having — a comparand its column cannot read is refused befo
         "`having` on 'first_opened' (min(opened_at), a datetime column) compares against \"last_30_days\" at "
         + 'having.first_opened.$lt, which is not a datetime value this platform can interpret.'],
     ];
-    const after = (message: string, marker: string): string => {
-      expect(message).toContain(marker);
-      return message.slice(message.indexOf(marker) + marker.length);
+    // [#27173] The remedy sits between the verdict and "NOT applied", so it
+    // lands inside the 500 characters a client reads.
+    const between = (message: string, start: string, end: string): string => {
+      expect(message).toContain(start);
+      const from = message.indexOf(start) + start.length;
+      expect(message.indexOf(end, from)).toBeGreaterThan(from);
+      return message.slice(from, message.indexOf(end, from));
     };
+    const VERDICT_END = 'this platform can interpret. ';
     for (const [having, where, firstSentence] of CASES) {
       // INVALID_FILTER / 400 on both paths, empty or populated, no read.
       const message = await expectHavingRefusal(() => having);
       expect(message.startsWith(`aggregate('${OBJECT}'): ${firstSentence} `)).toBe(true);
-      const remedy = after(message, 'The `having` was NOT applied. ');
+      const remedy = between(message, VERDICT_END, ' The `having` was NOT applied.');
       expect(remedy).toContain('"{30_days_ago}"');
       const twin = await whereTwinOf(where);
       expect(twin.err?.code).toBe('INVALID_FILTER');
       expect(twin.err?.status).toBe(400);
-      expect(remedy).toBe(after(twin.err!.message, 'The filter was NOT applied. '));
+      expect(remedy).toBe(between(twin.err!.message, VERDICT_END, ' The filter was NOT applied.'));
     }
   });
 });
 
@@ -0,0 +1,144 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#27173] Two `INVALID_FILTER` producers — the temporal-comparand door and
+ * the text-operator declared-type door — state what to write instead INSIDE
+ * the 500 characters a client reads.
+ *
+ * The cap stays: `mapDataError` (`@objectstack/types`) cuts a 4xx message at
+ * `CLIENT_MESSAGE_MAX` with `…`, and that is the general bound on what reaches
+ * a client. So the producer orders each refusal verdict, prescription, then
+ * consequence, and this file reads every arm the way a client does — through
+ * `mapDataError` — and requires the whole prescription in what survives the
+ * cut, ahead of "NOT applied". Run against the two producers as they stood on
+ * `origin/main` `4d3a077f`, all 31 cases here go red: every arm printed its
+ * prescription last, after "NOT applied" and the consequence.
+ *
+ * The fixtures are long on purpose — a 12-character object and field, a path
+ * through an aggregation's filter and a nested `$and` / `$or` — so the pin
+ * holds with margin, not only on a one-letter field.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { resolveFilterTokens } from '@objectstack/core';
+import { mapDataError } from '@objectstack/types';
+import {
+  assertTemporalComparandsInterpretable,
+  assertHavingTemporalComparandsInterpretable,
+  assertResolvedTemporalTokensInRange,
+  assertHavingResolvedTemporalTokensInRange,
+} from './temporal-comparand-door.js';
+import { assertTextOperatorTargetsAreStringCapable } from './text-operator-declared-type-door.js';
+
+const OBJECT = 'support_case';
+const FIELD = 'created_date';
+const ROOTS = ['where', 'aggregations[0].filter'] as const;
+
+/** The refusal a client reads: status, code, and the bounded `error` text. */
+function clientReads(fn: () => void): { status: number; code: unknown; text: string; full: string } {
+  let thrown: unknown;
+  try { fn(); } catch (e) { thrown = e; }
+  expect(thrown, 'the door refused').toBeInstanceOf(Error);
+  const { status, body } = mapDataError(thrown);
+  return { status, code: body.code, text: String(body.error), full: (thrown as Error).message };
+}
+
+/**
+ * The prescription is whole in what the client reads, and precedes the
+ * "NOT applied" sentence — the consequence after it is what a cut may take.
+ */
+function expectPrescriptionInside(fn: () => void, prescription: readonly string[]): void {
+  const read = clientReads(fn);
+  expect(read.status).toBe(400);
+  expect(read.code).toBe('INVALID_FILTER');
+  const notApplied = read.full.indexOf(' was NOT applied');
+  expect(notApplied, read.full).toBeGreaterThan(0);
+  for (const words of prescription) {
+    expect(read.text, `client text misses ${JSON.stringify(words)}`).toContain(words);
+    expect(read.full.indexOf(words), `${JSON.stringify(words)} sits after "NOT applied"`).toBeLessThan(notApplied);
+  }
+}
+
+/** The opening and the closing words of each remedy sentence, per class. */
+const DATETIME_REMEDY = ['Write a relative-date placeholder such as "{30_days_ago}"', 'or epoch milliseconds.'];
+const DATE_REMEDY = ['Write a "YYYY-MM-DD" calendar day that exists', '"{current_month_start}".'];
+const TIME_REMEDY = ['Write an "HH:MM" / "HH:MM:SS" wall clock', 'ADR-0053 D-C1).'];
+const DATETIME_YEARS_REMEDY = ['Write an ISO-8601 instant, epoch milliseconds or a Date', 'in the years 1000 to 9999.'];
+const DATE_YEARS_REMEDY = ['Write a "YYYY-MM-DD" day, epoch milliseconds or a Date', 'in the years 0001 to 9999.'];
+const TOKEN_REMEDY = ['Use a relative-date placeholder whose offset lands inside those years.'];
+
+type Kind = 'date' | 'datetime' | 'time';
+const WHERE_CASES: ReadonlyArray<readonly [string, Kind, unknown, readonly string[]]> = [
+  ['a preset name (junk) on a datetime', 'datetime', 'last_30_days', DATETIME_REMEDY],
+  ['a 60-character junk string on a datetime', 'datetime', 'x'.repeat(80), DATETIME_REMEDY],
+  ['junk on a date', 'date', 'last_30_days', DATE_REMEDY],
+  ['junk on a time', 'time', 'noon', TIME_REMEDY],
+  ['year 10000 on a datetime', 'datetime', '+010000-01-01T00:00:00.000Z', DATETIME_YEARS_REMEDY],
+  ['year 999 on a datetime (before the floor)', 'datetime', '0999-01-01T00:00:00.000Z', DATETIME_YEARS_REMEDY],
+  ['year 10000 on a date', 'date', 253402300800000, DATE_YEARS_REMEDY],
+  ['an impossible day on a date', 'date', '2026-02-30', DATE_REMEDY],
+  ['an impossible day on a datetime', 'datetime', '2026-02-30T00:00:00Z', DATETIME_REMEDY],
+  ['a slashed day on a datetime (not ISO)', 'datetime', '07/15/2026', DATETIME_REMEDY],
+  ['an instant outside the four-digit years on a time', 'time', '+010000-01-01T00:00:00.000Z', TIME_REMEDY],
+];
+
+describe('[#27173] the temporal-comparand door: the prescription lands inside the client cap', () => {
+  for (const [name, kind, value, prescription] of WHERE_CASES) {
+    it(`where / aggregations[i].filter — ${name}`, () => {
+      const schema = { fields: { [FIELD]: { type: kind } } };
+      for (const root of ROOTS) {
+        expectPrescriptionInside(() => assertTemporalComparandsInterpretable(
+          OBJECT, 'aggregate', schema, { $and: [{ x: 1 }, { $or: [{ [FIELD]: { $in: [value] } }] }] }, root,
+        ), prescription);
+      }
+    });
+    it(`having — ${name}`, () => {
+      const classes = new Map([[FIELD, kind]]);
+      const query = { aggregations: [{ alias: FIELD, function: 'max', field: 'opened_on_src' }] };
+      expectPrescriptionInside(() => assertHavingTemporalComparandsInterpretable(
+        OBJECT, { [FIELD]: { $gt: value } }, classes as never, query,
+      ), prescription);
+    });
+  }
+
+  const TOKENS: ReadonlyArray<readonly [Kind, string, readonly string[]]> = [
+    ['datetime', '{8000_years_from_now}', [...TOKEN_REMEDY, ...DATETIME_YEARS_REMEDY]],
+    ['datetime', '{1977_years_ago}', [...TOKEN_REMEDY, ...DATETIME_YEARS_REMEDY]],
+    ['date', '{8000_years_from_now}', [...TOKEN_REMEDY, ...DATE_YEARS_REMEDY]],
+    ['time', '{8000_years_from_now}', TIME_REMEDY],
+  ];
+  for (const [kind, token, prescription] of TOKENS) {
+    it(`a ${token} placeholder resolved outside a ${kind} column's years — where, aggregations[i].filter, having`, () => {
+      const schema = { fields: { [FIELD]: { type: kind } } };
+      const written = { [FIELD]: { $gt: token } };
+      const resolved = resolveFilterTokens(written, {});
+      for (const root of ROOTS) {
+        expectPrescriptionInside(() => assertResolvedTemporalTokensInRange(
+          OBJECT, 'aggregate', schema, written, resolved, root,
+        ), prescription);
+      }
+      const classes = new Map([[FIELD, kind]]);
+      const query = { groupBy: [{ field: 'opened_on_src', alias: FIELD, dateGranularity: 'day' }] };
+      expectPrescriptionInside(() => assertHavingResolvedTemporalTokensInRange(
+        OBJECT, written, resolved, classes as never, query,
+      ), prescription);
+    });
+  }
+});
+
+describe('[#27173] the text-operator declared-type door: the prescription lands inside the client cap', () => {
+  for (const type of ['number', 'currency', 'boolean', 'datetime', 'json']) {
+    it(`${type} under $notContains — where and aggregations[i].filter`, () => {
+      const field = 'contract_value';
+      const schema = { fields: { [field]: { type } } };
+      for (const root of ROOTS) {
+        expectPrescriptionInside(() => assertTextOperatorTargetsAreStringCapable(
+          OBJECT, 'aggregate', schema, { $and: [{ x: 1 }, { $or: [{ [field]: { $notContains: '5' } }] }] }, root,
+        ), [
+          `Compare '${field}' with an operator its declared type can answer`,
+          'or aim the text operator at a text-valued field.',
+        ]);
+      }
+    });
+  }
+});
@@ -216,6 +216,16 @@
  * expanded-year form (`+010026-10-01`, `-000001-10-01`), so the range reads
  * the year it names on every host.
  *
+ * ## [#27173] Prescription first, inside the client cap
+ *
+ * A client reads at most 500 characters of a refusal (`CLIENT_MESSAGE_MAX`,
+ * `@objectstack/types`, cut with `…`), and the cap stays. So every refusal
+ * here is ordered: what was written and why it is not a value of its kind,
+ * then what to write instead, then "NOT applied" and what the value would
+ * have done past this door. The consequence is the part a cut may take; the
+ * prescription is not. `filter-refusal-prescription-cap.test.ts`
+ * pins it per arm, the same rule #27098 set for the retired operators.
+ *
  * @see `@objectstack/core`'s `temporal-comparand.ts` — the value-half predicate,
  *   shared with the analytics raw-SQL decline so one rule cannot exist twice.
  * @see https://github.com/objectstack-ai/objectstack/issues/8690
@@ -484,12 +494,15 @@ function preview(value: unknown): string {
  * preset name (`last_30_days`) that the console would have lowered to
  * `{30_days_ago}`, so the fix a caller needs is almost always "wrap it as the
  * token the resolver knows", not "compute an instant yourself".
+ *
+ * [#27173] Each one is short, and printed right after the verdict, so it lands
+ * inside the 500 characters a client reads — see "Prescription first" above.
  */
 const REMEDY: Record<TemporalComparandKind, string> = {
   datetime:
-    'Write an ISO-8601 instant ("2026-07-15T00:00:00.000Z") on a calendar day that exists, '
-    + 'a bare "YYYY-MM-DD" (read as midnight UTC), epoch milliseconds as a number, or a '
-    + 'relative-date placeholder the resolver knows, e.g. "{30_days_ago}" / "{current_month_start}".',
+    'Write a relative-date placeholder such as "{30_days_ago}", an ISO-8601 instant '
+    + '("2026-07-15T00:00:00.000Z") on a day that exists, a bare "YYYY-MM-DD" (midnight UTC) or '
+    + 'epoch milliseconds.',
   date:
     'Write a "YYYY-MM-DD" calendar day that exists, or a relative-date placeholder the resolver '
     + 'knows, e.g. "{30_days_ago}" / "{current_month_start}".',
@@ -530,8 +543,8 @@ const YEAR_CLASS: Record<'date' | 'datetime', YearClass> = {
   date: {
     year: 'whose calendar day falls outside the years 0001 to 9999',
     ...misorders('does not sort as a day'),
-    remedy: 'Write a "YYYY-MM-DD" calendar day in the years 0001 to 9999, or an epoch-millisecond '
-      + 'number or Date whose UTC calendar day falls in those years.',
+    remedy: 'Write a "YYYY-MM-DD" day, epoch milliseconds or a Date whose UTC day falls in the years '
+      + '0001 to 9999.',
   },
   datetime: {
     year: DATETIME_YEARS,
@@ -703,13 +716,13 @@ export function assertTemporalComparandsInterpretable(
   // does: its text orders as no day or instant does, so it answers the WRONG
   // rows (or, on PostgreSQL, a database error) — or [#20280], for a `datetime`
   // in 0001..0999, it names a year MySQL's `DATETIME` does not document.
+  // [#27173] Each arm: the verdict, the prescription, then the consequence.
   const yearClass = yearClassOf(hit);
   if (yearClass) {
     throw invalidFilterError(
       `${operation}('${object}'): filter on '${hit.field}' compares a declared ${hit.kind} field `
-      + `against ${preview(hit.value)} at ${hit.path}, ${yearClass.year}, the years a ${hit.kind} `
-      + `value may name, so it is not a ${hit.kind} value this platform can interpret. `
-      + `${yearClass.where} The filter was NOT applied. ${yearClass.remedy}`,
+      + `against ${preview(hit.value)} at ${hit.path}, ${yearClass.year}, so it is not a ${hit.kind} `
+      + `value. ${yearClass.remedy} The filter was NOT applied. ${yearClass.where}`,
     );
   }
   // [#20549] A comparand the rule reads as another value than it names.
@@ -718,16 +731,15 @@ export function assertTemporalComparandsInterpretable(
     throw invalidFilterError(
       `${operation}('${object}'): filter on '${hit.field}' compares a declared ${hit.kind} field `
       + `against ${preview(hit.value)} at ${hit.path}, ${misread.why}, so it is not a ${hit.kind} `
-      + `value this platform can interpret. ${misread.where} The filter was NOT applied. `
-      + REMEDY[hit.kind],
+      + `value. ${REMEDY[hit.kind]} The filter was NOT applied. ${misread.where}`,
     );
   }
   throw invalidFilterError(
     `${operation}('${object}'): filter on '${hit.field}' compares a declared ${hit.kind} `
     + `field against ${preview(hit.value)} at ${hit.path}, which is not a ${hit.kind} value `
-    + 'this platform can interpret. It would reach the driver as written, compare false for '
-    + 'EVERY row, and return 200 with an empty result — indistinguishable from "there is no '
-    + `data". The filter was NOT applied. ${REMEDY[hit.kind]}`,
+    + `this platform can interpret. ${REMEDY[hit.kind]} The filter was NOT applied. As written `
+    + 'it would reach the driver, compare false for EVERY row, and return 200 with an empty '
+    + 'result — indistinguishable from "there is no data".',
   );
 }
 
@@ -784,29 +796,29 @@ export function assertHavingTemporalComparandsInterpretable(
   if (!hit) return;
   const column = havingColumnPhrase(hit, query);
   // The year class, in its own words, as on `where` (#20240, #20264, #20280).
+  // [#27173] The verdict, the prescription, then the consequence, as on `where`.
   const yearClass = yearClassOf(hit);
   if (yearClass) {
     throw invalidFilterError(
       `aggregate('${object}'): ${column} compares against ${preview(hit.value)} at ${hit.path}, `
-      + `${yearClass.year}, the years a ${hit.kind} value may name, so it is not a ${hit.kind} `
-      + `value this platform can interpret. ${yearClass.having} The \`having\` was NOT applied. `
-      + yearClass.remedy,
+      + `${yearClass.year}, so it is not a ${hit.kind} value. ${yearClass.remedy} The \`having\` was `
+      + `NOT applied. ${yearClass.having}`,
     );
   }
   // [#20549] The misread classes, in their own words, as on `where`.
   const misread = misreadClassOf(hit);
   if (misread) {
     throw invalidFilterError(
       `aggregate('${object}'): ${column} compares against ${preview(hit.value)} at ${hit.path}, `
-      + `${misread.why}, so it is not a ${hit.kind} value this platform can interpret. `
-      + `${misread.having} The \`having\` was NOT applied. ${REMEDY[hit.kind]}`,
+      + `${misread.why}, so it is not a ${hit.kind} value. ${REMEDY[hit.kind]} The \`having\` was `
+      + `NOT applied. ${misread.having}`,
     );
   }
   throw invalidFilterError(
     `aggregate('${object}'): ${column} compares against ${preview(hit.value)} at ${hit.path}, `
-    + `which is not a ${hit.kind} value this platform can interpret. Compared with each group as `
-    + 'written, it would keep no group or every group, a 200 indistinguishable from a real answer. '
-    + `The \`having\` was NOT applied. ${REMEDY[hit.kind]}`,
+    + `which is not a ${hit.kind} value this platform can interpret. ${REMEDY[hit.kind]} The `
+    + '`having` was NOT applied. Compared with each group as written, it would keep no group or '
+    + 'every group, a 200 indistinguishable from a real answer.',
   );
 }
 
@@ -847,7 +859,7 @@ function judgeResolvedToken(
 
 /** [#20844] The placeholder, where it sits, and what it resolved to — for the message. */
 function resolvedTokenPhrase(hit: ResolvedTokenOutsideYears): string {
-  return `${preview(hit.token)} at ${hit.path}, a relative-date placeholder that resolved to `
+  return `${preview(hit.token)} at ${hit.path}, a relative-date placeholder resolved to `
     + `${preview(hit.value)} (the year ${resolvedYearOf(hit.value)})`;
 }
 
@@ -866,7 +878,7 @@ function resolvedTokenWords(hit: ResolvedTokenOutsideYears): { cls: string; wher
   }
   const yearClass = yearClassOutside(hit.kind, hit.value);
   return {
-    cls: `${yearClass.year}, the years a ${hit.kind} value may name`,
+    cls: yearClass.year,
     where: yearClass.where,
     having: yearClass.having,
     remedy: `${RESOLVED_TOKEN_REMEDY} ${yearClass.remedy}`,
@@ -899,8 +911,8 @@ export function assertResolvedTemporalTokensInRange(
   const words = resolvedTokenWords(hit);
   throw invalidFilterError(
     `${operation}('${object}'): filter on '${hit.field}' compares a declared ${hit.kind} field against `
-    + `${resolvedTokenPhrase(hit)}, ${words.cls}, so it is not a ${hit.kind} value this platform can `
-    + `interpret. ${words.where} The filter was NOT applied. ${words.remedy}`,
+    + `${resolvedTokenPhrase(hit)}, ${words.cls}. ${words.remedy} The filter was NOT applied. `
+    + words.where,
   );
 }
 
@@ -921,7 +933,6 @@ export function assertHavingResolvedTemporalTokensInRange(
   const words = resolvedTokenWords(hit);
   throw invalidFilterError(
     `aggregate('${object}'): ${havingColumnPhrase(hit, query)} compares against ${resolvedTokenPhrase(hit)}, `
-    + `${words.cls}, so it is not a ${hit.kind} value this platform can interpret. ${words.having} `
-    + `The \`having\` was NOT applied. ${words.remedy}`,
+    + `${words.cls}. ${words.remedy} The \`having\` was NOT applied. ${words.having}`,
   );
 }