@object-ui/core 17.5.0 → 17.7.0

package/dist/utils/dashboard-filters.js

@@ -6,12 +6,39 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { liftLegacyGlobalFilterDefault } from '@object-ui/types';
-import { DATE_RANGE_PRESETS } from '@objectstack/spec/ui';
+import { DATE_RANGE_PRESETS, DashboardSchema as SpecDashboardSchema } from '@objectstack/spec/ui';
 import { resolveDateMacros } from './date-macros.js';
 /** Reserved filter name for the dashboard's built-in date range. */
 export const DATE_RANGE_FILTER_NAME = 'dateRange';
 /** Default target field for the built-in date range filter. */
 const DATE_RANGE_DEFAULT_FIELD = 'created_at';
+/**
+ * The preset an authored `dateRange` resolves to when it omits `defaultRange`
+ * (objectui#10339) — READ FROM THE SPEC, never restated here.
+ *
+ * `@objectstack/spec` declares `DashboardSchema.dateRange.defaultRange` with a
+ * `.default(...)`, so the platform's parse of `dateRange: { field: 'created_at' }`
+ * carries that preset, and a renderer that treated the omission as "no filter"
+ * showed an UNFILTERED dashboard for a document the protocol says is filtered
+ * (#7759 ruling 5617465269, rule 1: the read site implements every arm the spec
+ * declares). The value is derived by parsing an EMPTY `dateRange` element
+ * through the spec's own schema: the only keys that come back are the ones the
+ * spec supplies by default, so this reads the spec's answer rather than a
+ * hand-copied string that could drift from it. `allowCustomRange` is the
+ * sibling default and needs no such read — it is consumed as `!== false`,
+ * which already is its spec default.
+ *
+ * Computed on first use and cached: `DashboardSchema` is a lazy schema, and
+ * forcing its construction at module load would cost every importer of
+ * `@object-ui/core` for a value only a dashboard with a bare `dateRange` needs.
+ */
+let specDateRangeDefault;
+function specDefaultDateRangePreset() {
+    if (specDateRangeDefault === undefined) {
+        specDateRangeDefault = SpecDashboardSchema.shape.dateRange.parse({})?.defaultRange;
+    }
+    return specDateRangeDefault;
+}
 /**
  * Date-range presets → date-macro token bounds. Tokens stay symbolic in the
  * generated condition; every widget renderer resolves them at query time via
@@ -72,7 +99,7 @@ function presetBounds(preset) {
  * protect.
  *
  * What stays local is the BOUNDS table above, which is the other half of
- * #4614's design ("the two vocabularies live one import apart and neither
+ * objectstack-ai/objectstack#4614's design ("the two vocabularies live one import apart and neither
  * restates the other's grammar"): the spec owns which presets exist, this
  * module owns what each one resolves to in date-macro tokens.
  */
@@ -111,13 +138,13 @@ function warnDateFilter(message) {
         console.warn(`[dashboard-filters] ${message}`);
 }
 /**
- * Dev-mode gate, matching `actions/actionKeys.ts` — a deprecation warning that
- * floods a production console is a warning that gets muted.
+ * Dev-mode gate, matching `actions/actionKeys.ts` — a warning that floods a
+ * production console is a warning that gets muted.
  */
 const isDev = () => globalThis.process?.env?.NODE_ENV !==
     'production';
 /**
- * Warn-once memo for the bare-string `options` shorthand (objectui#4356).
+ * Warn-once memo for the DROPPED bare-string `options` members (objectui#4356).
  *
  * Keyed by filter NAME **and** the offending values, deliberately — the same
  * reasoning `warnOnUnknownActionKeys` records for its own memo. Keying on the
@@ -132,7 +159,13 @@ const isDev = () => globalThis.process?.env?.NODE_ENV !==
  * flood the dedupe exists to prevent.
  */
 const warnedShorthandOptions = new Set();
-/** Reset the shorthand-options warn-once memo. Exported for tests. */
+/**
+ * Reset the dropped-shorthand warn-once memo. Exported for tests.
+ *
+ * Kept through the objectui#4356 retirement: the memo it clears outlived the
+ * deprecation warning, because the warning that replaced it (a member was
+ * DROPPED, not lifted) dedupes on the same key for the same render-path reason.
+ */
 export function resetDashboardFilterWarnings() {
     warnedShorthandOptions.clear();
 }
@@ -252,45 +285,40 @@ function normalizeDateDefault(type, defaultValue) {
 }
 /**
  * Normalize a filter's static `options` declaration to `{ value, label }`
- * pairs. The @objectstack/spec `GlobalFilterSchema.options` form is
- * `{ value, label }` objects; the bare-string shorthand (`options: ['EMEA', …]`)
- * is still lifted, but is DEPRECATED and now says so out loud. Rendering an
- * un-normalized option crashes React — this is the single place both shapes
- * converge.
+ * pairs — the @objectstack/spec `GlobalFilterSchema.options` form, and the
+ * only form this function emits. Rendering an un-normalized option crashes
+ * React, so every member that reaches a renderer passes through here.
  *
- * ## The shorthand's deprecation (objectui#4356, objectstack#7917)
+ * ## The bare-string shorthand is RETIRED (objectui#4356, objectstack#7917)
  *
  * Maintainer ruling of 2026-08-12 on objectstack#7917, verbatim 「7917 ②」:
- * option ② — **the spec stays strict; the runtime bare-string lift retires
- * behind a deprecation window sized by a stored-dashboard survey.** So a
- * document spelling `options: ['EMEA']` renders here and is refused the moment
- * it reaches the platform's validation — the "one strict contract beats N
- * dialects" divergence AGENTS.md #0.1 names, with the renderer's tolerance
- * acting as a second de-facto contract.
- *
- * This is the WARN half of that window (Phase 1). The lift itself is unchanged
- * and remains mechanically lossless (`'EMEA'` → `{ value: 'EMEA', label:
- * 'EMEA' }`), because stored dashboards carry the shorthand and dropping it
- * silently would turn a rendering filter into an empty one. Removal (Phase 2)
- * is scheduled on objectstack#7917, earliest one minor release after this ships
- * and not before the live-tenant channel has actually been queried.
- *
- * The warning is not decoration: a silent lift can never be retired, because
- * nothing would ever show that the last shorthand document is gone (ADR-0078 —
- * nothing silently inert). It is the same reasoning `liftLegacyFilterDeclaration`
- * records above, for the sibling alias.
- *
- * Phase 0 shipped in the same PR: objectui's own docs, its `plugin-dashboard`
- * README and its schema-catalog corpus stopped TEACHING the shorthand, so the
- * stored population is no longer growing while this warning asks authors to
- * migrate. Warning authors while the docs still taught the form would have been
- * a contradiction users report as a bug.
+ * option ② — **the spec stays strict; the runtime bare-string lift retires.**
+ * The window closed on the maintainer's 2026-09-02 ruling, verbatim
+ * 「objectstack#7917 不考虑现有数据」: Phase 2 proceeds on release cadence
+ * alone, with no live-tenant survey and no migration entry.
+ *
+ * So `options: ['EMEA']` — which the Phase 1 build (PR #4601) lifted to
+ * `{ value: 'EMEA', label: 'EMEA' }` under a deprecation warning — now yields
+ * NO option. A member that is not an object is skipped, exactly as a nullish
+ * member or an object with no `value` already was: a shorthand-only filter
+ * resolves with no `options`, and a mixed array keeps only its object members.
+ * The runtime reads the document the way the spec does, which is the end
+ * state option ② named — one strict contract, no renderer dialect beside it
+ * (AGENTS.md #0.1). ⛔ No lift, alias, fallback or migration returns here.
+ *
+ * The skip is not silent. `warnDroppedShorthandOptions` names the filter, the
+ * dropped members and the rewrite, once per filter per session — ADR-0078 §4:
+ * where the runtime skips an instance it emits a dev-mode diagnostic rather
+ * than swallowing it, and a STORED dashboard is the one document no author-time
+ * gate ever re-reads, so an empty select with nothing in the console would read
+ * as "no data". What that warning must NOT do is promise a lift: the Phase 1
+ * text said "still lifted here", and that sentence retired with the arm.
  *
  * ## What is normalized, and what is deliberately NOT (objectui#4032 / #4163)
  *
- * The PAIR SHAPE is normalized (`value` stringified, a bare string lifted to a
- * pair). The LABEL's authoring vocabulary is carried through untouched, because
- * `label` is `I18nLabel` — a string OR an inline per-locale map.
+ * The PAIR SHAPE is normalized (`value` stringified). The LABEL's authoring
+ * vocabulary is carried through untouched, because `label` is `I18nLabel` — a
+ * string OR an inline per-locale map.
  *
  * This line used to read:
  *
@@ -312,8 +340,8 @@ function normalizeFilterOptions(options, filterName) {
     if (!Array.isArray(options) || options.length === 0)
         return undefined;
     const normalized = [];
-    /** Every bare-string member, in authored order — one warning names them all. */
-    const shorthand = [];
+    /** Every non-object member, in authored order — one warning names them all. */
+    const dropped = [];
     for (const o of options) {
         if (o === null || o === undefined)
             continue;
@@ -329,39 +357,48 @@ function normalizeFilterOptions(options, filterName) {
             });
         }
         else {
-            shorthand.push(String(o));
-            normalized.push({ value: String(o), label: String(o) });
+            // The retired shorthand arm (objectui#4356): nothing is pushed for this
+            // member. It is recorded for the warning and yields no option.
+            dropped.push(o);
         }
     }
-    if (shorthand.length > 0)
-        warnShorthandOptions(filterName, shorthand);
+    if (dropped.length > 0)
+        warnDroppedShorthandOptions(filterName, dropped);
     return normalized.length > 0 ? normalized : undefined;
 }
 /**
- * Say the deprecated shorthand out loud — once per offending filter per
- * session, naming the filter and printing the canonical replacement.
+ * Say the dropped members out loud — once per offending filter per session,
+ * naming the filter, the members that yielded no option, and the rewrite.
  *
- * Collected per FILTER rather than per option: a filter declaring
+ * Collected per FILTER rather than per member: a filter declaring
  * `['EMEA', 'APAC', 'AMER']` is one authoring mistake in one place, so it earns
  * one warning carrying all three values, not three warnings the author has to
  * reassemble. A MIXED array (`[{ value: 'won', … }, 'lost']`) names only the
- * bare members, which are the ones that need rewriting — partial migrations
- * happen and a warning that re-reports the already-canonical members is noise.
+ * dropped members — the object members rendered, and re-reporting them is noise.
+ *
+ * Dev-mode only and memoised, exactly as the Phase 1 deprecation warning was:
+ * `resolveDashboardFilterDefs` runs on every dashboard render, and a warning
+ * that floods a console is a warning that gets muted. What changed is the
+ * sentence — this one reports a member that was DROPPED and promises no lift.
  */
-function warnShorthandOptions(filterName, shorthand) {
+function warnDroppedShorthandOptions(filterName, dropped) {
     if (!isDev())
         return;
-    const memo = `${filterName}:${shorthand.join(',')}`;
+    // A string is quoted so `"42"` and `42` stay distinguishable; anything else is
+    // spelled as itself — `String()` rather than `JSON.stringify()`, because a
+    // programmatic caller can hand this a value JSON cannot carry.
+    const spelled = dropped.map((v) => (typeof v === 'string' ? JSON.stringify(v) : String(v)));
+    const memo = `${filterName}:${spelled.join(',')}`;
     if (warnedShorthandOptions.has(memo))
         return;
     warnedShorthandOptions.add(memo);
-    const canonical = shorthand.map((v) => `{ value: ${JSON.stringify(v)}, label: ${JSON.stringify(v)} }`).join(', ');
-    warnDateFilter(`filter "${filterName}": \`options\` carries the bare-string shorthand ` +
-        `(${shorthand.map((v) => JSON.stringify(v)).join(', ')}), which @objectstack/spec's ` +
-        `\`GlobalFilterSchema\` REFUSES at publish — a dashboard authored this way renders here ` +
-        `and is rejected the moment it reaches the platform (objectui#4356). Rewrite the stored ` +
-        `dashboard to the canonical pair form: [${canonical}]. Still lifted here for already-` +
-        `persisted dashboards; the lift is removed on the objectstack#7917 schedule.`);
+    const canonical = dropped
+        .map((v) => `{ value: ${JSON.stringify(String(v))}, label: ${JSON.stringify(String(v))} }`)
+        .join(', ');
+    warnDateFilter(`filter "${filterName}": \`options\` members ${spelled.join(', ')} are not \`{ value, label }\` ` +
+        `objects and were DROPPED — the bare-string shorthand is no longer lifted (objectui#4356), so the ` +
+        `filter renders without them. Rewrite the stored dashboard to @objectstack/spec's pair form: ` +
+        `[${canonical}].`);
 }
 /**
  * Normalize a dashboard schema's filter declarations into a flat list of
@@ -372,7 +409,11 @@ function warnShorthandOptions(filterName, shorthand) {
 export function resolveDashboardFilterDefs(schema) {
     const byName = new Map();
     if (schema.dateRange) {
-        const preset = schema.dateRange.defaultRange;
+        // An omitted `defaultRange` takes the spec's declared default (#10339); an
+        // explicit value — `'custom'` included — is used exactly as authored.
+        const preset = schema.dateRange.defaultRange === undefined
+            ? specDefaultDateRangePreset()
+            : schema.dateRange.defaultRange;
         byName.set(DATE_RANGE_FILTER_NAME, {
             name: DATE_RANGE_FILTER_NAME,
             field: schema.dateRange.field || DATE_RANGE_DEFAULT_FIELD,
@@ -398,9 +439,14 @@ export function resolveDashboardFilterDefs(schema) {
         byName.set(name, {
             name,
             field: f.field,
+            // Spread rather than assigned (`061f5e829`): every filter authored
+            // before this key existed keeps the exact key set it resolved to, so
+            // `'object' in def` stays the discriminator the render side branches on
+            // and no consumer sees a new own-property carrying `undefined`.
+            ...(typeof f.object === 'string' && f.object ? { object: f.object } : {}),
             label: f.label,
             type,
-            // `name` is the identifying context the deprecation warning needs, and
+            // `name` is the identifying context the dropped-member warning needs, and
             // the local above already resolved it — nothing new is threaded through a
             // public signature for it. `normalizeFilterOptions` is module-private, so
             // widening ITS parameter list is not a contract move.

package/dist/utils/dataset-format.d.ts

@@ -17,6 +17,7 @@
  */
 import type { AnalyticsResult } from '@objectstack/spec/contracts';
 import type { PercentScale } from '@objectstack/spec/data';
+import { type BuiltinAggregateLabels } from './chart-series.js';
 /**
  * Column metadata the analytics server returns alongside the rows — the spec's
  * `AnalyticsResult.fields[]` element BY REFERENCE, never a local restatement of
@@ -59,28 +60,35 @@ export type DatasetResultField = AnalyticsResult['fields'][number];
  */
 export type { PercentScale } from '@objectstack/spec/data';
 /**
- * Scale a stored `percent`-field value to its DISPLAY magnitude.
- *
- * Percent fields store a FRACTION (0–1) by convention — a stored `0.75` means
- * 75% (see the percent edit widget `PercentField`, which divides input by 100).
- * A value already in whole-percent form (magnitude ≥ 1, e.g. a `progress` /
- * `completion` field storing `57`) is passed through unchanged. This is the
- * SINGLE source of truth for percent display scaling, shared by the list-view
- * percent cell renderer (`formatPercent` in `@object-ui/fields`) and the dataset
- * measure formatter ({@link formatMeasure}) so a percent renders identically as
- * a row value and as an aggregated metric — the two surfaces can never drift.
- *
- * ⚠️ That last sentence was briefly FALSE, and objectui#4576 is what made it
- * true again. Sharing the SCALING was never enough on its own: between #4553
- * and #4576 the cell renderer got the locale's percent CONVENTION from `Intl`
- * while {@link formatMeasure} appended a literal '%', so a German session read
- * `1.234,5 %` in a list cell and `1.234,5%` in a dashboard measure — the same
- * number, scaled identically, rendered under two conventions. Both ends now go
- * through the locale's own percent affix. If a third surface ever needs percent
- * display, it takes BOTH halves from here — the scaling AND the convention —
- * or this promise breaks again in the same place.
+ * Scale a stored percentage to its DISPLAY magnitude (percentage points), at
+ * the storage the caller STATES.
+ *
+ * `percentScale` is the spec's `PercentScale`: `fraction` is a 0–1 ratio
+ * (`0.75` ⇒ 75, `1` ⇒ 100), `whole` is already in percentage points (`75` ⇒
+ * 75, `1` ⇒ 1). A caller holding a field definition reads it with the spec's
+ * `percentScaleOf` (`@objectstack/spec/data`): a `percent` field stores a
+ * fraction unless it declares a `max` above 1. A caller with no field (a
+ * computed ratio, a server measure column) states the storage it knows: a
+ * `derived: { op: 'ratio' }` measure is a fraction by definition, and the
+ * server annotates a measure column with its `percentScale`.
+ *
+ * ⛔ No storage is inferred from the VALUE any more (objectui#11475). This
+ * function used to be `value > -1 && value < 1 ? value * 100 : value`, a guess
+ * from the magnitude that read neither the field nor its `max`. A fraction-
+ * stored `1` (100%) therefore read `1%` in the list cell while the read-only
+ * form, which reads the declaration, read `100%`; a whole-stored `0.5` read
+ * `50%`. objectui#3136 was the same guess on a dashboard measure. The
+ * parameter is REQUIRED, so every caller says which storage it holds, and a
+ * value outside the union throws rather than falling to a branch silently.
+ *
+ * ⭐ The contract a third percent surface still owes is BOTH halves: this
+ * scaling, at the stored scale, AND the locale's percent convention
+ * (`style: 'percentPoints'`, see {@link formatMeasure} and `formatPercent` in
+ * `@object-ui/fields`). Between objectui#4553 and objectui#4576 the two ends
+ * shared the scaling and not the convention, so a German session read
+ * `1.234,5 %` in a list cell and `1.234,5%` in a dashboard measure.
  */
-export declare function percentDisplayValue(value: number): number;
+export declare function percentDisplayValue(value: number, percentScale: PercentScale): number;
 /**
  * Format a MEASURE value. Currency comes from the field's declared `currency`
  * (locale-correct symbol via `Intl`), NOT from a "$" baked into the format
@@ -118,8 +126,54 @@ export declare function percentDisplayValue(value: number): number;
  * is pure, so it moved DOWN into this package (`./number-display.ts`) and
  * `@object-ui/i18n` re-exports it. The duplicate implementation this file used
  * to carry is gone, and with it the drift that duplicate produced — see the
- * percent note in the body, and {@link percentDisplayValue}'s promise, which
- * is true again.
+ * percent note in the body, and the both-halves contract
+ * {@link percentDisplayValue}'s doc comment states.
+ *
+ * ── Date-valued measures (objectui#7178) ──
+ * `min` / `max` over a date or datetime field is a legitimate measure, and it
+ * used to render its stored value verbatim: the guard above returned
+ * `String(v)` for anything non-numeric BEFORE `format` was read, so a KPI tile
+ * showed `2026-07-04T07:00:00.000Z` in `text-2xl` and wrapped it over two
+ * lines. A date-shaped value now routes through {@link formatMeasureDate} to
+ * the display path list cells use; nothing about the numeric path moved.
+ *
+ * ⚠️ What `format` can and cannot say for those values, measured rather than
+ * assumed, and stated PER ARM — a date-shaped measure takes one of two arms in
+ * {@link formatMeasureDate}, and this paragraph used to describe only one of
+ * them while reading as though it described both. That cost a card: an
+ * objectui triage pass read the undifferentiated claim, concluded the defect
+ * was already fixed, and downgraded objectui#8352, which a driven browser run
+ * then refuted. The two arms agree TODAY, but only because #8352 made them; a
+ * universal sentence here is what hid the disagreement before, so it is not
+ * coming back even now that it would be true.
+ *
+ * The shared date path takes a named STYLE, not a date pattern. On BOTH arms
+ * the honoured vocabulary is `'short'` and `'relative'`:
+ *
+ *   - `Field.date` (`2026-09-08`) — honoured by threading `format` into
+ *     `formatDate`'s style parameter. The same words `DateCellRenderer`
+ *     honours from `field.format` for the same field.
+ *   - `Field.datetime` (`2026-09-01T00:00:00.000Z`) — honoured by SELECTING a
+ *     formatter, because `formatDateTime` has no style parameter to thread
+ *     into (objectui#8352). Before that card this arm honoured NOTHING: it
+ *     dropped `format` entirely, so `'relative'` rendered the absolute face.
+ *
+ * Every other string falls to that arm's default face — a PATTERN like
+ * `format: 'YYYY-MM-DD'` is accepted by the schema, reaches this function, and
+ * renders the locale default, and so does `'compact'`, which is
+ * `formatDateTime`'s own vocabulary but not this path's. The pattern part is
+ * not new behaviour introduced here: `plugin-dashboard`'s `recordFields`
+ * already routes a date-shaped `format` into the same style slot and gets the
+ * same locale default. Closing it would mean teaching the shared path a
+ * pattern grammar, which is a change to the path itself and to every list cell
+ * that reads it — not a measure concern, and not either card.
+ *
+ * ⚠️ `'relative'` renders the ABSOLUTE face for a value more than ±7 days from
+ * today, on both arms, by `formatRelativeDate`'s own design. That is correct
+ * output, not a regression — but it also means an out-of-window value is
+ * useless for testing this path, because it renders identically whether
+ * `format` is honoured or dropped. Both readings that missed #8352 were taken
+ * on 40–60-day-old data.
  */
 export declare function formatMeasure(v: unknown, format?: string, currency?: string, percentScale?: PercentScale, locale?: string): string;
 /**
@@ -140,13 +194,31 @@ export declare function formatDimensionValue(v: unknown, locale?: string): strin
  *
  * `fieldLabel` is injected (rather than imported) so this stays React/i18n-free;
  * callers pass `useSafeFieldLabel().fieldLabel`.
+ *
+ * ## `builtinAggregateLabels` (objectui#7534, sibling of #7258)
+ *
+ * A result field the analytics service minted as a BUILT-IN default measure
+ * carries `builtinAggregate` (objectstack#14492) and a hard-coded English
+ * `label` ('Count'). {@link resolveMeasureLabel} is the ONE resolver for that —
+ * #7258 wired it into `buildChartSeries()`, so a chart legend already read
+ * `计数` on a zh console while the table underneath it, the KPI caption, the
+ * pivot header and the dataset preview all still said `Count`, because they
+ * resolve their titles through here instead.
+ *
+ * Passing the caller's resolved labels closes that gap without a second
+ * resolution order: the discriminator is consulted FIRST (exactly as on the
+ * chart seam), the existing `fieldLabel` convention still applies on top, and
+ * the raw name is still the floor. Omitting the argument reproduces the
+ * previous output byte for byte — an author-declared measure carries no
+ * discriminator and keeps its wire `label` verbatim (objectui#4106), and a
+ * provider-less host resolves no labels and so changes nothing.
  */
-export declare function buildDatasetFieldHelpers(fields: DatasetResultField[] | undefined, object: string | undefined, fieldLabel?: (objectName: string, fieldName: string, fallback: string) => string): {
+export declare function buildDatasetFieldHelpers(fields: DatasetResultField[] | undefined, object: string | undefined, fieldLabel?: (objectName: string, fieldName: string, fallback: string) => string, builtinAggregateLabels?: BuiltinAggregateLabels): {
     measureField: (name: string) => DatasetResultField | undefined;
     headerLabel: (name: string) => string;
 };
 /**
- * A half-open date-range drill scope for one time-bucketed dimension (#1752):
+ * A half-open date-range drill scope for one time-bucketed dimension (objectstack-ai/objectstack#1752):
  * the object FIELD to filter and its inclusive `gte` / exclusive `lt` bounds
  * (the server's `drillRanges` sidecar entry).
  */
@@ -161,18 +233,127 @@ export interface DatasetDrillRange {
  * Each drillable dimension maps to its underlying object field, filtered by the
  * dimension's RAW grouped value (from the server's parallel `drillRawRows`, NOT
  * the visible row which carries the display LABEL — a select/lookup label would
- * mis-filter). An empty/undefined raw value normalizes to `null` (an explicit
- * "is empty" filter). The render-time `runtimeFilter` is ANDed in so the drilled
- * list stays within the same slice the aggregate was computed over.
+ * mis-filter). The render-time `runtimeFilter` is ANDed in so the drilled list
+ * stays within the same slice the aggregate was computed over.
+ *
+ * ## What the EMPTY bucket means, and why it is spelled `{ $null: true }`
  *
- * A time-bucketed date dimension (#1752) drills by RANGE, not equality — a
+ * A drill must return exactly the rows the clicked bucket COUNTED. The empty
+ * bucket is the one the aggregate grouped rows with NO VALUE for that dimension
+ * into, so the drill means "this dimension has no value" — NOT "this dimension
+ * holds the literal value null". Those are different row sets, and the
+ * difference is measurable rather than theoretical: against `ValueDataSource`'s
+ * matcher over rows `{owner:'alice'}` / `{owner:null}` / `{}` (no `owner` key),
+ * `['owner','is_null',true]` selects the explicit-null row AND the missing-key
+ * row, while an equality test against `null` selects only the explicit-null one
+ * and drops the row that has no `owner` at all. The bucket counted both, so
+ * is-null is the one that agrees with the number the user clicked.
+ *
+ * ⇒ every empty authoring — `''`, `null` and `undefined` alike — becomes ONE
+ * spelling, `{ [field]: { $null: true } }`, which `convertFiltersToAST` lowers
+ * to `[field, 'is_null', true]`. The three are not told apart because the
+ * server already merged them into the single bucket the user clicked; there is
+ * no second bucket here for a second spelling to address.
+ *
+ * ⚠️ This value used to be a bare `null`, and that is the defect objectui#9085
+ * records: `convertFiltersToAST`'s OLDEST pinned behaviour is to SKIP a key
+ * whose value is `null` / `undefined` (pinned as "should skip null and
+ * undefined values"), so the constraint was dropped on the way to the wire and
+ * the empty-bucket drill answered with a SUPERSET — every row, silently. The
+ * repair is here at the PRODUCER and ⛔ not at that converter: the skip is
+ * relied on by other producers, and changing it would move every caller's
+ * meaning at once (objectui#9020 ruled it stays). `$null` is not a new
+ * vocabulary either — it is a declared spec operator this dialect already
+ * lowers, and the one spelling that says the same thing on BOTH of
+ * `ValueDataSource`'s routes, where a bare `null` said "only an explicit null"
+ * on the plain-object route and "no constraint at all" on the AST route.
+ *
+ * ⚠️ Known BOUNDARY, unchanged by this and deliberately not widened: the drill
+ * "escape hatch" (the host's `openRecordList`, which serializes a drill filter
+ * into `filter[...]` URL params) has NO spelling for is-null — its operator
+ * vocabulary is equality plus four range bounds — so it drops this condition
+ * exactly as it already dropped the bare `null`, byte-for-byte the same query
+ * string. That surface is a superset today and stays one; closing it needs a
+ * URL-dialect operator on both the write and the read side, which is its own
+ * card.
+ *
+ * A time-bucketed date dimension (objectstack-ai/objectstack#1752) drills by RANGE, not equality — a
  * humanized bucket ("2026-Q2") can't be exact-matched, so the server sends a
  * half-open `[gte, lt)` per date dim in `rawRanges` instead of a raw value.
  * Each becomes an ObjectQL range operator object (`{ $gte, $lt }`) so the drill
  * scopes the list to the clicked time bucket instead of every bucket (which the
  * old date-dim skip degraded to — a superset).
  *
+ * ## The widget filter is CONJOINED, not spread (objectui#9137)
+ *
+ * ⛔ `runtimeFilter` is composed through {@link composeDrillFilter}, never by
+ * spreading it into the object literal below. Spreading is correct only for the
+ * OBJECT arm; this parameter's declared producer sends the ARRAY arm. The
+ * dashboard's `DashboardWidgetSchema.filter` docblock states it outright —
+ * "objectui passes an ObjectQL FilterNode array here, not the spec's
+ * `FilterCondition` envelope" — and `DatasetWidget`'s guard admits it
+ * (`typeof [] === 'object'` and `Object.keys(['x']).length === 1` are both
+ * true), so the array arm reached this line unfiltered. Spreading an ARRAY
+ * yields INDEX keys: `[['region','=','emea']]` became
+ * `{ '0': ['region','=','emea'] }`, which is not a condition anyone can honour.
+ *
+ * ⚠️ MEASURED, and it is NOT the silent superset the sibling sites had. An
+ * index key is not dropped on the way to the wire — every sink in circulation
+ * refuses it LOUDLY, because a bare array is not a legal equality comparand
+ * (objectui#8530 / objectui#8514): `convertFiltersToAST` THROWS
+ * `FilterOperatorError`, `driver-sql` answers `400 INVALID_FILTER`, and
+ * `ValueDataSource`'s matcher selects NOTHING. Against rows scoped
+ * `region = 'emea'`, drilling the `stage = 'won'` bucket returned `(none)`
+ * where the widget alone returned three rows and the conjunction returns the
+ * right two. So the widget's conditions were not merely lost — the drill was
+ * dead in the array arm. The failure is fail-CLOSED here, and this is the third
+ * site of the class objectui#8944 (chart) and objectui#9024 (pivot) removed.
+ *
+ * Three properties of THIS site, each confirmed rather than assumed — it is not
+ * a copy-paste of the other two:
+ *
+ * 1. The return stays a NON-optional `Record<string, unknown>`, because callers
+ *    do not expect `undefined`. `composeDrillFilter` answers `undefined` when
+ *    both sources are empty, so that one case is spelled `?? {}` — the same
+ *    empty object this function already returned for a bucket with no dims.
+ * 2. Range operators SURVIVE. A time-bucketed dim contributes
+ *    `{ $gte, $lt }`, and the composition re-spells it as two `$and` children
+ *    on the same field (`[{d:{$gte}},{d:{$lt}}]`) rather than losing a bound;
+ *    the selected rows are identical, and `serializeDrillFilterParams` walks
+ *    `$and` (objectui#8944) so both bounds still reach `filter[d][gte|lt]`.
+ * 3. `runtimeFilter` is declared `unknown`, which is what the two consumers
+ *    actually hand it — `any` from the dashboard, `Record<string, unknown>`
+ *    from `DatasetReportRenderer`. Widening the PARAMETER is what admits both
+ *    without a cast; ⛔ neither consumer's own type is changed by this.
+ *
+ * ⚠️ Conjunction changes one behaviour deliberately: a field named by BOTH the
+ * widget filter and the clicked bucket used to be overwritten by the bucket,
+ * and now both conditions apply. That is the point — a drill may narrow the
+ * widget's scope and may never widen it — and it is the posture the chart and
+ * pivot sites already ship.
+ *
+ * ## ⭐ Only the COMPOSING leg moves; the identity leg is left byte-identical
+ *
+ * The sink is asked only when there IS a second source. That is this site's
+ * one departure from `ObjectChart` / `ObjectPivotTable`, which call it
+ * unconditionally, and it is deliberate rather than a shortcut: the spread
+ * this replaces only ever ran when `runtimeFilter` was present, so the
+ * no-widget-filter path carries no defect to repair.
+ *
+ * ⚠️ Routing it anyway was MEASURED and rejected. `composeDrillFilter`'s own
+ * note — "a lone surviving source lowers back to exactly the flat object the
+ * spread produced" — holds only for a source of ONE condition; with two it
+ * lowers to `$and`, because `convertFiltersToAST` emits one node per condition
+ * and `parseFilterAST` cannot fold two nodes back onto one key. A `{ $gte,
+ * $lt }` range is two conditions on its own, so even a single date bucket
+ * re-spells. Sending the identity leg through the sink therefore re-shaped
+ * every multi-condition dataset drill — including the controls objectui#9085,
+ * objectui#4056, objectstack#5473 and objectstack-ai/objectstack#1752 pin on paths this card does not
+ * touch — for ZERO change in the rows selected or the `filter[...]` params
+ * emitted. ⛔ Do not "simplify" this to an unconditional call without redoing
+ * that measurement.
+ *
  * Shared by the dashboard `DatasetWidget` and the report renderer so a drill
  * filters identically (and correctly, including lookups) on both surfaces.
  */
-export declare function buildDatasetDrillFilter(rawRow: Record<string, unknown> | undefined, drillDims: string[], dimensionFields: Record<string, string>, runtimeFilter?: Record<string, unknown>, rawRanges?: Record<string, DatasetDrillRange>): Record<string, unknown>;
+export declare function buildDatasetDrillFilter(rawRow: Record<string, unknown> | undefined, drillDims: string[], dimensionFields: Record<string, string>, runtimeFilter?: unknown, rawRanges?: Record<string, DatasetDrillRange>): Record<string, unknown>;