@object-ui/core 17.6.0 → 18.0.0

package/dist/utils/chart-series.d.ts

@@ -9,7 +9,51 @@ export interface ChartResultField {
     name: string;
     label?: string;
     format?: string;
+    /**
+     * The aggregate the measure column carries — the spec's
+     * `AnalyticsResult.fields[].aggregate`, which the dataset answer states on
+     * every measure column whose measure declares one, labelled or not
+     * (objectstack#21995). Absent on dimension columns and derived measures.
+     *
+     * Typed `string`, not the closed vocabulary, for the reason
+     * {@link BuiltinAggregateCarrier} gives: a JSON response is handed here
+     * as-is, so the value is judged at the read ({@link isIntegerAggregate}).
+     * {@link buildChartSeries} copies it onto each series it derives from the
+     * column, so a value axis can tell a count from a sum (objectui#11681).
+     */
+    aggregate?: string;
+}
+/**
+ * The OPTIONAL wire discriminator naming which server-side BUILT-IN default
+ * measure a result column is (objectui#7258; producer half objectstack#14492).
+ * The analytics service sets it ONLY on the measures it minted itself with a
+ * hard-coded English default label (`count` → `'Count'`, …); an author-declared
+ * measure never carries it, so its `label` stays the author's verbatim text
+ * (objectui#4106). {@link resolveMeasureLabel} is the one reader.
+ *
+ * Declared BESIDE {@link ChartResultField} rather than on it, deliberately:
+ * `dataset-result-field-spec-parity` pins every key of `ChartResultField` as a
+ * key of the spec's `AnalyticsResult.fields[]`, and the `@objectstack/spec`
+ * this package is built against does not carry `builtinAggregate` yet. The
+ * intersection {@link ChartMeasureField} is what the helpers accept, so a
+ * spec-typed field flows in unchanged today and carries the key the moment
+ * the spec does — structurally, with no cast at the call sites.
+ *
+ * Typed as `string` rather than the closed {@link BuiltinAggregate} union on
+ * purpose: a JSON response is handed here as-is, so the value is validated at
+ * the lookup ({@link isBuiltinAggregate}) instead of trusted at the type.
+ *
+ * TODO(objectstack#14492): once the spec dependency is bumped past the release
+ * that adds `AnalyticsResult.fields[].builtinAggregate`, fold this key into
+ * `ChartResultField` as `DatasetResultField['builtinAggregate']` (pinning the
+ * two closed vocabularies to each other in the parity suite) and retire the
+ * carrier.
+ */
+export interface BuiltinAggregateCarrier {
+    builtinAggregate?: string;
 }
+/** A result field as the series helpers read it: the renderer shape plus the optional discriminator. */
+export type ChartMeasureField = ChartResultField & BuiltinAggregateCarrier;
 /**
  * One renderer-internal series binding produced by {@link buildChartSeries}:
  * WHICH result-set column to draw and what to call it.
@@ -25,12 +69,74 @@ export interface ChartResultField {
 export interface ChartSeriesBinding {
     dataKey: string;
     label: string;
+    /**
+     * The aggregate of the measure this series plots, copied from its result
+     * column's `aggregate` (objectui#11681). Renderer-internal: the chart's value
+     * axis draws whole-number ticks when every series on it plots an
+     * {@link isIntegerAggregate} measure. Absent when the column states none.
+     */
+    aggregate?: string;
 }
 export interface ChartSeriesResult {
     data: Array<Record<string, unknown>>;
     xAxisKey: string | undefined;
     series: ChartSeriesBinding[];
 }
+/**
+ * The closed vocabulary of server-side built-in default measures a result field
+ * can declare itself as (objectui#7258 / objectstack#14492) — the spec's own
+ * measure-aggregate enum spelling (`count_distinct`, not `countDistinct`), so
+ * there is exactly ONE spelling on the wire and this list never grows on its
+ * own: a value outside it is not "a new aggregate", it is an unrecognised one,
+ * and {@link resolveMeasureLabel} treats it as absent.
+ */
+export declare const BUILTIN_AGGREGATES: readonly ["count", "sum", "avg", "min", "max", "count_distinct"];
+/** One member of {@link BUILTIN_AGGREGATES}. */
+export type BuiltinAggregate = (typeof BUILTIN_AGGREGATES)[number];
+/**
+ * The aggregates whose every value is a whole number: a count of rows, or of
+ * distinct values (objectui#11681, triage ruling Q3 A on that card). `sum` /
+ * `min` / `max` over an integer field would qualify too, but the answer does
+ * not state the source field's scale, so they are not judged integer here.
+ */
+export declare const INTEGER_AGGREGATES: readonly ["count", "count_distinct"];
+/**
+ * Whether a measure column's `aggregate` makes every value a whole number — a
+ * value axis that plots only such measures takes integer ticks
+ * (objectui#11681). Judged over an untrusted wire value; anything else,
+ * absence included, answers `false`, so the axis keeps its default.
+ */
+export declare function isIntegerAggregate(value: unknown): boolean;
+/** Runtime membership test for {@link BUILTIN_AGGREGATES}, over an untrusted wire value. */
+export declare function isBuiltinAggregate(value: unknown): value is BuiltinAggregate;
+/**
+ * The LOCALIZED display label per built-in aggregate, as the layer that holds
+ * the i18n provider resolved them (`@object-ui/i18n`'s
+ * `builtinAggregateLabels(tt)`). Partial on purpose: an aggregate the caller
+ * did not resolve falls back to the wire `label`, exactly as if the field had
+ * carried no discriminator.
+ */
+export type BuiltinAggregateLabels = Partial<Record<BuiltinAggregate, string>>;
+/**
+ * The display label of ONE result field, for a legend / axis / tooltip.
+ *
+ * Resolution order (objectui#7258, maintainer ruling B of 2026-09-02):
+ *  1. the field declares itself a built-in default measure
+ *     (`builtinAggregate` ∈ {@link BUILTIN_AGGREGATES}) AND the caller resolved
+ *     a locale label for it → that label. This is the only path that can
+ *     replace a wire `label`, and it is keyed by a STRUCTURAL discriminator —
+ *     never by matching the label's text or the field's name, both of which
+ *     the ruling rejected (a real author measure literally named `count`, or
+ *     labelled `Count`, must keep its own label);
+ *  2. otherwise the wire `label` verbatim — the objectui#4106 contract for an
+ *     author-declared measure (`'Tasks'` reaches the legend untouched);
+ *  3. otherwise the field's `name`.
+ *
+ * So a discriminator the caller has no label for (a provider-less host, or a
+ * value outside the closed vocabulary) costs nothing: the field renders exactly
+ * what it rendered before the discriminator existed.
+ */
+export declare function resolveMeasureLabel(field: ChartMeasureField, labels?: BuiltinAggregateLabels): string;
 /**
  * The bucket a NULL/undefined category VALUE renders under, when the caller
  * supplies no localized label of its own (objectui#4466).
@@ -110,6 +216,16 @@ export interface ChartSeriesOptions {
      * it, so a mismatch costs the null bucket its drill-through.
      */
     nullCategoryLabel?: string;
+    /**
+     * Locale labels for the server's BUILT-IN default measures, keyed by the
+     * wire discriminator a result field carries as `builtinAggregate`
+     * (objectui#7258). Same division of labour as `nullCategoryLabel`: this
+     * package is React-free and i18n-free, so the renderer that holds the
+     * provider resolves the strings (`builtinAggregateLabels(tt)` in
+     * `@object-ui/i18n`) and passes them in. Absent ⇒ every measure keeps its
+     * wire `label`, which for a built-in default is the server's English.
+     */
+    builtinAggregateLabels?: BuiltinAggregateLabels;
 }
 /** Per-CLICK knobs for {@link findChartSeriesRow}, on top of the shared ones. */
 export interface ChartDrillLookupOptions extends ChartSeriesOptions {
@@ -174,7 +290,7 @@ export interface ChartSegmentClickEvent {
     /** The measure value at the click point. */
     value?: number;
 }
-export declare function buildChartSeries(rows: Array<Record<string, unknown>> | null | undefined, dimensions: string[] | null | undefined, values: string[] | null | undefined, fields?: ChartResultField[] | null, options?: ChartSeriesOptions): ChartSeriesResult;
+export declare function buildChartSeries(rows: Array<Record<string, unknown>> | null | undefined, dimensions: string[] | null | undefined, values: string[] | null | undefined, fields?: ChartMeasureField[] | null, options?: ChartSeriesOptions): ChartSeriesResult;
 /**
  * Resolve select/enum dimension VALUES to display LABELS in chart rows.
  *
@@ -362,10 +478,54 @@ export declare function buildDimensionLabelMap(options: unknown, translate?: Opt
  * The object a relationship field points at, or `undefined` when the field is
  * not a relationship (or names no target).
  *
- * The target lives under `reference` on framework-served field defs; older /
- * spec shapes spell it `reference_to` / `referenceTo` / `reference_to_object`,
- * and any of them may carry a bare name, a one-element array, or `{ object }`.
- * Same canonicalization as the dataset designer's `resolveReferenceTo`.
+ * The target lives under `reference` — the ONLY spelling read here, and the same
+ * canonicalization as the dataset designer's `resolveReferenceTo`, which is
+ * narrowed to match in the same pass (objectui#6528). As of objectui#6648 the
+ * CARRIER matches too: a bare string and nothing else. The two helpers are one
+ * doctrine in two files and must never drift — a divergence recreates the
+ * defect one file over.
+ *
+ * The three legacy spellings this dropped (`reference_to` / `referenceTo` /
+ * `reference_to_object`) were censused against every producer, with `reference`
+ * itself as the positive control (445 of 565 lookup / master_detail defs in the
+ * framework tree; ACCEPTED by `ObjectSchema.safeParse` on spec 17.2.0, which
+ * REFUSES all three others BY NAME). No producer emits any of them onto an
+ * object metadata document: `reference_to` was then live only on ObjectUI's own
+ * view/field schema (a different contract, translated INTO from `reference`;
+ * objectui#11070 round 4 moved that contract to `reference` as well),
+ * `referenceTo`'s two producers were retired by objectui#6041, and
+ * `reference_to_object` occurs nowhere in either tree outside this chain and the
+ * test that called it.
+ *
+ * ⚠ Unlike `resolveReferenceTo`, this helper reads the `GET /meta/object/:name`
+ * document DIRECTLY — no `readFields` door strips retired keys on this path. So
+ * the narrowing is load-bearing rather than cosmetic: a stored pre-objectui#6041
+ * row spelling the target `referenceTo` now resolves to `undefined` here, the
+ * walk yields no entry, and the caller keeps the raw value (best-effort by
+ * construction — see {@link resolveDimensionFieldMeta}). That is the intended
+ * outcome: per AGENTS.md #0.1 such a row is a PRODUCER-side defect, and a
+ * lenient consumer here is exactly where it would have stayed hidden. Note
+ * `reference` was already HEAD of the old chain, so any doc carrying both is
+ * unaffected.
+ *
+ * The array and `{ object }` CARRIERS this used to accept were censused on the
+ * same standard and removed with the same reasoning (objectui#6648).
+ * `FieldSchema.reference` is a plain `z.string()`; `ObjectSchema.safeParse`
+ * (spec 17.2.0) ACCEPTS `reference: 'crm_account'` and REFUSES both
+ * `['crm_account']` and `{ object: 'crm_account' }` as `invalid_type`. A
+ * structure-walking, key-position-aware census of both trees found 587
+ * bare-string carriers at the field-def key position and ZERO array or
+ * `{ object }` carriers from any producer — the only ones in either tree were
+ * the green pins asserting this very tolerance. See `resolveReferenceTo` for
+ * the full census, including why a multi-target lookup is NOT what the array
+ * branch was serving: it returned `raw[0]` and discarded the rest, and
+ * polymorphic lookup remains an undeclared, open spec gap.
+ *
+ * This path matters MORE than the designer's for the same reason the spelling
+ * narrowing did: it reads the metadata document directly, with no `readFields`
+ * door in between, so a non-string carrier now degrades visibly (the walk
+ * yields no entry and the caller keeps the raw value) instead of being absorbed
+ * here.
  *
  * The **type gate is deliberate**: only a declared relationship is walked, so a
  * path segment naming a plain field can never be turned into an object name and

package/dist/utils/chart-series.js

@@ -44,6 +44,63 @@
  * know" refuses — one doctrine, and now BOTH branches state it.
  */
 import { pivotBucketId, pivotDimensionValue } from './dataset-pivot.js';
+/**
+ * The closed vocabulary of server-side built-in default measures a result field
+ * can declare itself as (objectui#7258 / objectstack#14492) — the spec's own
+ * measure-aggregate enum spelling (`count_distinct`, not `countDistinct`), so
+ * there is exactly ONE spelling on the wire and this list never grows on its
+ * own: a value outside it is not "a new aggregate", it is an unrecognised one,
+ * and {@link resolveMeasureLabel} treats it as absent.
+ */
+export const BUILTIN_AGGREGATES = ['count', 'sum', 'avg', 'min', 'max', 'count_distinct'];
+/**
+ * The aggregates whose every value is a whole number: a count of rows, or of
+ * distinct values (objectui#11681, triage ruling Q3 A on that card). `sum` /
+ * `min` / `max` over an integer field would qualify too, but the answer does
+ * not state the source field's scale, so they are not judged integer here.
+ */
+export const INTEGER_AGGREGATES = ['count', 'count_distinct'];
+/**
+ * Whether a measure column's `aggregate` makes every value a whole number — a
+ * value axis that plots only such measures takes integer ticks
+ * (objectui#11681). Judged over an untrusted wire value; anything else,
+ * absence included, answers `false`, so the axis keeps its default.
+ */
+export function isIntegerAggregate(value) {
+    return typeof value === 'string' && INTEGER_AGGREGATES.includes(value);
+}
+/** Runtime membership test for {@link BUILTIN_AGGREGATES}, over an untrusted wire value. */
+export function isBuiltinAggregate(value) {
+    return typeof value === 'string' && BUILTIN_AGGREGATES.includes(value);
+}
+/**
+ * The display label of ONE result field, for a legend / axis / tooltip.
+ *
+ * Resolution order (objectui#7258, maintainer ruling B of 2026-09-02):
+ *  1. the field declares itself a built-in default measure
+ *     (`builtinAggregate` ∈ {@link BUILTIN_AGGREGATES}) AND the caller resolved
+ *     a locale label for it → that label. This is the only path that can
+ *     replace a wire `label`, and it is keyed by a STRUCTURAL discriminator —
+ *     never by matching the label's text or the field's name, both of which
+ *     the ruling rejected (a real author measure literally named `count`, or
+ *     labelled `Count`, must keep its own label);
+ *  2. otherwise the wire `label` verbatim — the objectui#4106 contract for an
+ *     author-declared measure (`'Tasks'` reaches the legend untouched);
+ *  3. otherwise the field's `name`.
+ *
+ * So a discriminator the caller has no label for (a provider-less host, or a
+ * value outside the closed vocabulary) costs nothing: the field renders exactly
+ * what it rendered before the discriminator existed.
+ */
+export function resolveMeasureLabel(field, labels) {
+    const aggregate = field.builtinAggregate;
+    if (isBuiltinAggregate(aggregate)) {
+        const localized = labels?.[aggregate];
+        if (typeof localized === 'string' && localized !== '')
+            return localized;
+    }
+    return field.label ?? field.name;
+}
 /**
  * The bucket a NULL/undefined category VALUE renders under, when the caller
  * supplies no localized label of its own (objectui#4466).
@@ -296,7 +353,19 @@ export function buildChartSeries(rows, dimensions, values, fields, options) {
     const dims = (dimensions ?? []).filter(Boolean);
     const vals = (values ?? []).filter(Boolean);
     const safeRows = Array.isArray(rows) ? rows : [];
-    const labelOf = (name) => (fields ?? []).find((f) => f.name === name)?.label ?? name;
+    // A measure's series label: the locale label when the field declares itself
+    // a built-in default measure and the caller resolved one, else the wire
+    // `label` verbatim (objectui#4106), else the name — see `resolveMeasureLabel`.
+    const labelOf = (name) => {
+        const field = (fields ?? []).find((f) => f.name === name);
+        return field ? resolveMeasureLabel(field, options?.builtinAggregateLabels) : name;
+    };
+    // The measure column's own `aggregate`, spread onto each series that plots
+    // it (objectui#11681) — present only when the column states a string one.
+    const aggregateOf = (name) => {
+        const aggregate = (fields ?? []).find((f) => f.name === name)?.aggregate;
+        return typeof aggregate === 'string' ? { aggregate } : {};
+    };
     // Multi-dimension, single-measure → pivot the second dimension into series.
     if (dims.length >= 2 && vals.length === 1) {
         const xKey = dims[0];
@@ -402,7 +471,8 @@ export function buildChartSeries(rows, dimensions, values, fields, options) {
             // server-resolved to display labels by queryDataset), except the null
             // group, which says so with the bucket label the renderer supplied. The
             // key is a separate question from the text — see `pivotSeriesBuckets`.
-            series: groups.map(({ dataKey, label }) => ({ dataKey, label })),
+            // Every group plots the one measure, so each carries its aggregate.
+            series: groups.map(({ dataKey, label }) => ({ dataKey, label, ...aggregateOf(measure) })),
         };
     }
     // Default: first dimension on the x-axis, one series per measure.
@@ -425,7 +495,7 @@ export function buildChartSeries(rows, dimensions, values, fields, options) {
             ? bucketNullCategories(safeRows, xKey, options?.nullCategoryLabel ?? NULL_CATEGORY_LABEL)
             : safeRows,
         xAxisKey: xKey,
-        series: vals.map((v) => ({ dataKey: v, label: labelOf(v) })),
+        series: vals.map((v) => ({ dataKey: v, label: labelOf(v), ...aggregateOf(v) })),
     };
 }
 /**
@@ -765,10 +835,54 @@ function fieldDefsOf(schema) {
  * The object a relationship field points at, or `undefined` when the field is
  * not a relationship (or names no target).
  *
- * The target lives under `reference` on framework-served field defs; older /
- * spec shapes spell it `reference_to` / `referenceTo` / `reference_to_object`,
- * and any of them may carry a bare name, a one-element array, or `{ object }`.
- * Same canonicalization as the dataset designer's `resolveReferenceTo`.
+ * The target lives under `reference` — the ONLY spelling read here, and the same
+ * canonicalization as the dataset designer's `resolveReferenceTo`, which is
+ * narrowed to match in the same pass (objectui#6528). As of objectui#6648 the
+ * CARRIER matches too: a bare string and nothing else. The two helpers are one
+ * doctrine in two files and must never drift — a divergence recreates the
+ * defect one file over.
+ *
+ * The three legacy spellings this dropped (`reference_to` / `referenceTo` /
+ * `reference_to_object`) were censused against every producer, with `reference`
+ * itself as the positive control (445 of 565 lookup / master_detail defs in the
+ * framework tree; ACCEPTED by `ObjectSchema.safeParse` on spec 17.2.0, which
+ * REFUSES all three others BY NAME). No producer emits any of them onto an
+ * object metadata document: `reference_to` was then live only on ObjectUI's own
+ * view/field schema (a different contract, translated INTO from `reference`;
+ * objectui#11070 round 4 moved that contract to `reference` as well),
+ * `referenceTo`'s two producers were retired by objectui#6041, and
+ * `reference_to_object` occurs nowhere in either tree outside this chain and the
+ * test that called it.
+ *
+ * ⚠ Unlike `resolveReferenceTo`, this helper reads the `GET /meta/object/:name`
+ * document DIRECTLY — no `readFields` door strips retired keys on this path. So
+ * the narrowing is load-bearing rather than cosmetic: a stored pre-objectui#6041
+ * row spelling the target `referenceTo` now resolves to `undefined` here, the
+ * walk yields no entry, and the caller keeps the raw value (best-effort by
+ * construction — see {@link resolveDimensionFieldMeta}). That is the intended
+ * outcome: per AGENTS.md #0.1 such a row is a PRODUCER-side defect, and a
+ * lenient consumer here is exactly where it would have stayed hidden. Note
+ * `reference` was already HEAD of the old chain, so any doc carrying both is
+ * unaffected.
+ *
+ * The array and `{ object }` CARRIERS this used to accept were censused on the
+ * same standard and removed with the same reasoning (objectui#6648).
+ * `FieldSchema.reference` is a plain `z.string()`; `ObjectSchema.safeParse`
+ * (spec 17.2.0) ACCEPTS `reference: 'crm_account'` and REFUSES both
+ * `['crm_account']` and `{ object: 'crm_account' }` as `invalid_type`. A
+ * structure-walking, key-position-aware census of both trees found 587
+ * bare-string carriers at the field-def key position and ZERO array or
+ * `{ object }` carriers from any producer — the only ones in either tree were
+ * the green pins asserting this very tolerance. See `resolveReferenceTo` for
+ * the full census, including why a multi-target lookup is NOT what the array
+ * branch was serving: it returned `raw[0]` and discarded the rest, and
+ * polymorphic lookup remains an undeclared, open spec gap.
+ *
+ * This path matters MORE than the designer's for the same reason the spelling
+ * narrowing did: it reads the metadata document directly, with no `readFields`
+ * door in between, so a non-string carrier now degrades visibly (the walk
+ * yields no entry and the caller keeps the raw value) instead of being absorbed
+ * here.
  *
  * The **type gate is deliberate**: only a declared relationship is walked, so a
  * path segment naming a plain field can never be turned into an object name and
@@ -781,17 +895,8 @@ export function resolveRelationshipTarget(fieldDef) {
     const type = typeof def.type === 'string' ? def.type.toLowerCase() : '';
     if (!RELATIONSHIP_FIELD_TYPES.has(type))
         return undefined;
-    const raw = def.reference ?? def.reference_to ?? def.referenceTo ?? def.reference_to_object;
-    if (typeof raw === 'string' && raw)
-        return raw;
-    if (Array.isArray(raw) && typeof raw[0] === 'string' && raw[0])
-        return raw[0];
-    if (raw && typeof raw === 'object') {
-        const obj = raw.object;
-        if (typeof obj === 'string' && obj)
-            return obj;
-    }
-    return undefined;
+    const raw = def.reference;
+    return typeof raw === 'string' && raw ? raw : undefined;
 }
 /**
  * Resolve each dataset dimension's underlying `field` to that field's select

package/dist/utils/column-sortability.d.ts

@@ -0,0 +1,157 @@
+/**
+ * ObjectUI — served per-column sortability projection (consumer side)
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * The consumer half of objectstack#10235 (maintainer ruling A, 2026-08-23):
+ * the platform serves an explicit per-column sortability signal, and a grid
+ * reads THAT to decide whether a header offers a sort click — it never
+ * re-derives "virtual ⇒ unsortable" from the field's `type`.
+ *
+ * ## What the platform serves
+ *
+ * `GET /api/v1/meta/object/:name` answers `GetMetaItemResponseSchema`, whose
+ * ENVELOPE (never the document under `item` — `FieldSchema` is a
+ * `strictObject`, so the key must stay un-authorable) carries an optional
+ * `sortability` key when the served type is `object`, on every serving branch
+ * including the cached one:
+ *
+ * ```jsonc
+ * { "type": "object", "name": "crm_opportunity", "item": { … },
+ *   "sortability": { "fields": {
+ *     "amount":           { "sortable": true },
+ *     "expected_revenue": { "sortable": false, "reason": "virtual-type" },
+ *     "remote_anchor":    { "sortable": true,  "caveat": "unprovisioned-anchor" }
+ *   } } }
+ * ```
+ *
+ * Shape verified against the MERGED upstream change, not against a description
+ * of it: `@objectstack/spec`'s `ObjectSortabilitySchema` /
+ * `FieldSortabilitySchema` and `GetMetaItemResponseSchema.sortability`.
+ *
+ * ## The contract, and the asymmetry that makes it easy to get backwards
+ *
+ * Offer a sort affordance on a column **iff the projection has an entry for
+ * the column's field name AND that entry says `sortable: true`**.
+ *
+ * ABSENCE OF AN ENTRY MEANS "no platform sort behind this name" — never
+ * "assume sortable". The projection's domain is exactly the served field map
+ * plus the always-provisioned `id`, so an unknown name, a dotted path
+ * (`account.name`) and an unprovisioned audit column all arrive as absence,
+ * and all three are refused by the runtime doors. A `!== false` test — the
+ * spelling every other optional flag in this repo uses — answers `true` for
+ * absence and so gets exactly that family backwards. {@link isPlatformSortableField}
+ * is the only spelling of this test; do not inline a comparison at a call site.
+ *
+ * ## Present-vs-absent PROJECTION is a different question
+ *
+ * `readObjectSortability` returns `undefined` when the served metadata carried
+ * no `sortability` key at all — a backend older than the upstream change, an
+ * inline/mock data source, a fixture. That is NOT "every column is unsortable":
+ * it is "no signal was served", and the caller decides what it did before the
+ * signal existed. The two are deliberately different types (`undefined` vs an
+ * empty `fields` map) so a caller cannot conflate them by accident.
+ *
+ * ## `caveat: 'unprovisioned-anchor'` is NOT a refusal
+ *
+ * Platform-injected anchors on ADR-0015 `external` objects come back
+ * `sortable: true, caveat: 'unprovisioned-anchor'`: the runtime ACCEPTS the
+ * sort, but silently drops it (`asc` === `desc` under a `200`) when the remote
+ * table carries no such column — a degradation the platform cannot prove
+ * either way at serve time. This module treats the caveat as advisory and the
+ * `sortable` verdict as the enforcement fact, so a caveated column keeps its
+ * click. Refusing what the platform does not refuse would recreate
+ * declared-≠-enforced drift in mirror image; whether to badge or withhold on
+ * the caveat is an open affordance question, not something to settle here.
+ */
+/**
+ * The served shape is the SPEC's, re-exported rather than restated.
+ *
+ * `FIELD_UNSORTABLE_VIRTUAL_TYPE` / `FIELD_SORTABLE_UNPROVISIONED_ANCHOR` are
+ * the two string literals the projection can carry, and `FieldSortability` /
+ * `ObjectSortability` are the wire types themselves (`z.input` of the
+ * schemas the REST layer answers with). Re-exporting is the point of a
+ * contract-first consumer: a local declaration under a spec export's name is
+ * read by the next agent as the spec's own definition, and then drifts from
+ * it — which is what `check:spec-symbols` guards, and what it caught here.
+ */
+export { FIELD_UNSORTABLE_VIRTUAL_TYPE, FIELD_SORTABLE_UNPROVISIONED_ANCHOR, } from '@objectstack/spec/api';
+export type { FieldSortability, ObjectSortability } from '@objectstack/spec/api';
+import type { ObjectSortability } from '@objectstack/spec/api';
+/**
+ * Where the projection rides on the client-side object schema.
+ *
+ * A GLOBAL-REGISTRY SYMBOL, deliberately — the same carrier shape
+ * `INFLIGHT_GET_REGISTRY_KEY` uses in `@object-ui/types`. Three properties
+ * this signal needs and a string key would not give it:
+ *
+ *  - `JSON.stringify` drops symbol-keyed properties, so a schema object that
+ *    is ever round-tripped back at a metadata WRITE endpoint cannot carry the
+ *    projection into a document the server parses `strict` and rejects by
+ *    name. The upstream change kept the key off `item` for exactly that
+ *    reason; stamping a string key here would undo it one repo away.
+ *  - `Object.keys` / spread / `for…in` do not see it, so every existing reader
+ *    that enumerates the schema (column generators, diffing, form builders)
+ *    is unchanged by its presence.
+ *  - `Symbol.for` is the cross-realm registry, so two copies of this module
+ *    (a workspace build and a published one in the same graph) agree on the
+ *    key rather than silently reading past each other.
+ */
+export declare const OBJECT_SORTABILITY_KEY: unique symbol;
+/**
+ * Normalize a served `sortability` envelope value into the projection, or
+ * `undefined` when the envelope carried nothing usable.
+ *
+ * Tolerant on purpose (the same contract the upstream resolver carries): the
+ * adapter hands this whatever came back over the wire, unparsed.
+ */
+export declare function normalizeObjectSortability(served: unknown): ObjectSortability | undefined;
+/**
+ * Stamp the served projection onto the client-side object schema, under
+ * {@link OBJECT_SORTABILITY_KEY}.
+ *
+ * Non-enumerable and non-writable-by-accident: the property is defined rather
+ * than assigned so it never shows up in a spread of the schema and cannot be
+ * clobbered by one. Returns the same object it was handed (the adapter caches
+ * that instance), and is a no-op when there is nothing usable to attach — so
+ * an older backend leaves the schema exactly as it found it rather than
+ * stamping an empty projection that would read as "nothing is sortable".
+ */
+export declare function attachObjectSortability<T>(schema: T, served: unknown): T;
+/**
+ * Read the served projection off a client-side object schema.
+ *
+ * `undefined` means NO SIGNAL WAS SERVED — not "nothing is sortable". See the
+ * module docblock: callers must branch on this before applying the contract.
+ */
+export declare function readObjectSortability(schema: unknown): ObjectSortability | undefined;
+/**
+ * THE contract test: does the platform offer a sort over this field name?
+ *
+ * `true` iff the projection has an entry for `fieldName` and that entry says
+ * `sortable: true`. Every other case — no entry, `sortable: false`, a
+ * malformed entry — answers `false`, because absence means "no platform sort
+ * behind this name".
+ *
+ * `sortability` is REQUIRED and non-optional on purpose: a caller holding
+ * `undefined` (no signal served) has a different question to answer and must
+ * not reach this function with it. See {@link readObjectSortability}.
+ */
+export declare function isPlatformSortableField(sortability: ObjectSortability, fieldName: string | undefined): boolean;
+/**
+ * Drop from a sort list every entry the platform will not order by.
+ *
+ * The RESTORE leg of the same contract: withholding the header click stops a
+ * fresh unsortable sort from being created, but a sort persisted BEFORE the
+ * signal existed is already in stored view state, and replaying it would keep
+ * a refused `$orderby` alive and re-persist it on the next unrelated edit.
+ * Filtering the list at the seam the grid both renders from and emits through
+ * means an already-stored entry is inert and is dropped the first time
+ * anything writes the sort back.
+ */
+export declare function filterPlatformSortableSort<T extends {
+    field?: string;
+}>(sort: readonly T[] | undefined, sortability: ObjectSortability): T[];