@object-ui/core 17.1.0 → 17.2.0

package/dist/utils/dashboard-filters.js

@@ -5,6 +5,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+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. */
@@ -31,6 +32,72 @@ const PRESET_RANGES = {
 };
 /** Preset keys the filter bar offers, in display order. */
 export const DATE_RANGE_PRESETS = Object.keys(PRESET_RANGES);
+/**
+ * ISO calendar date, optionally carrying a time part — `2026-01-15`,
+ * `2026-01-15T08:30:00Z`. Deliberately narrower than `Date.parse`, which
+ * also accepts locale prose (`March 5, 2026`) and bare years (`2026`);
+ * neither is a value the backend compares a date column against usefully.
+ */
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}(?:[T ][\d:.]+(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+/**
+ * True when a bare string value can legitimately reach a query as a date
+ * (#3151). Two spellings qualify:
+ *
+ *  - a **date-macro token** (`{today}`, `${current_month_start}`,
+ *    `{7_days_ago}`) — it stays symbolic in the generated condition and is
+ *    resolved at query time by `resolveDateMacros`, exactly like the bounds
+ *    `PRESET_RANGES` emits. The check asks that resolver itself instead of
+ *    restating its grammar here: one token vocabulary, no second dialect to
+ *    drift — and a token it does not know is precisely the typo this guard
+ *    exists to catch;
+ *  - an **ISO date**, which means equality on that day (documented behaviour).
+ */
+function isUsableDateString(value) {
+    if (resolveDateMacros(value) !== value)
+        return true;
+    return ISO_DATE_RE.test(value) && !Number.isNaN(Date.parse(value));
+}
+/** `today, yesterday, …` — quoted in every rejection so the fix is in reach. */
+function presetList() {
+    return DATE_RANGE_PRESETS.join(', ');
+}
+function warnDateFilter(message) {
+    if (typeof console !== 'undefined')
+        console.warn(`[dashboard-filters] ${message}`);
+}
+/**
+ * Normalize a date filter's DECLARED default into the `DateRangeValue` shape
+ * every date consumer in this module reads (framework#4475).
+ *
+ * The built-in `dateRange` declaration has always been normalized this way —
+ * `schema.dateRange.defaultRange` is a preset NAME and
+ * `resolveDashboardFilterDefs` lifts it to `{ preset }`. A `globalFilters`
+ * entry of `type: 'date'` was passed through raw instead, and that asymmetry
+ * is the whole bug: `@objectstack/spec`'s `GlobalFilterSchema.defaultValue` is
+ * `string | number | boolean`, so a bare preset name is the ONLY spelling an
+ * author can write, yet nothing ever mapped it. Both symptoms of Setup's
+ * System Overview reading 0 across every KPI tile follow from that:
+ *
+ *  - `buildFilterCondition` fell through to its "a bare string date means
+ *    equality on that day" branch and emitted `created_at = 'last_7_days'`,
+ *    which matches no row — a query the backend answers `200 OK` with a 0;
+ *  - `DateRangeFilter` reads `value.preset` / `.from` / `.to`, all `undefined`
+ *    on a bare string, so the control displayed "All time" while sending that
+ *    equality — the tiles looked deliberately unfiltered and merely empty.
+ *
+ * Only a name this module actually knows is lifted. A genuine ISO date string
+ * still means equality on that day (the documented behaviour), and a number /
+ * boolean / unrecognised string is left exactly as declared — an unrecognised
+ * string then never reaches a query at all: `buildFilterCondition` skips it
+ * with a warning rather than comparing a column against it (#3151).
+ */
+function normalizeDateDefault(type, defaultValue) {
+    if (type !== 'date' && type !== 'dateRange')
+        return defaultValue;
+    if (typeof defaultValue !== 'string')
+        return defaultValue;
+    return defaultValue in PRESET_RANGES ? { preset: defaultValue } : defaultValue;
+}
 /**
  * Normalize a filter's static `options` declaration to `{ value, label }`
  * pairs. The @objectstack/spec `GlobalFilterSchema.options` form is
@@ -88,14 +155,18 @@ export function resolveDashboardFilterDefs(schema) {
         if (byName.has(name) && typeof console !== 'undefined') {
             console.warn(`[dashboard-filters] duplicate filter name "${name}" — the later definition wins`);
         }
+        const type = f.type ?? 'text';
         byName.set(name, {
             name,
             field: f.field,
             label: f.label,
-            type: f.type ?? 'text',
+            type,
             options: normalizeFilterOptions(f.options),
             optionsFrom: f.optionsFrom,
-            defaultValue: f.defaultValue,
+            // framework#4475 — same preset-name lifting the built-in `dateRange`
+            // above already does; see normalizeDateDefault for why a bare string is
+            // the only thing an author can declare here.
+            defaultValue: normalizeDateDefault(type, f.defaultValue),
             targetWidgets: f.targetWidgets,
         });
     }
@@ -134,6 +205,15 @@ function isEmptyValue(def, value) {
  * Build the operator shape (the value side of a `FilterCondition` entry) for
  * one filter's current value. Returns `undefined` when the value imposes no
  * constraint. The caller keys the result by the bound field name.
+ *
+ * A `date`/`dateRange` value is held to three spellings (#3151): a known
+ * preset name → range bounds; a date-macro token or ISO date → equality on
+ * that day; **anything else → skipped with a console warning**, never
+ * silently downgraded to an equality nothing can match. That last branch is
+ * the same strictness `buildWidgetScopedFilter` applies to a default binding
+ * on an unknown field name, for the same reason: a query the backend answers
+ * `200 OK` with zero rows is indistinguishable from "this range has no data",
+ * so the typo has to be said out loud somewhere.
  */
 export function buildFilterCondition(def, value) {
     if (isEmptyValue(def, value))
@@ -141,9 +221,18 @@ export function buildFilterCondition(def, value) {
     if (def.type === 'dateRange' || def.type === 'date') {
         const v = value;
         if (typeof v === 'object') {
-            const range = v.preset ? PRESET_RANGES[v.preset] : undefined;
+            const preset = typeof v.preset === 'string' && v.preset ? v.preset : undefined;
+            const range = preset ? PRESET_RANGES[preset] : undefined;
             const from = range?.from ?? v.from;
             const to = range?.to ?? v.to;
+            if (preset && !range) {
+                // Was already dropped here — but silently, which reads as "no data".
+                warnDateFilter(from || to
+                    ? `filter "${def.name}": ignoring unknown date range preset "${preset}" — ` +
+                        `using the explicit from/to bounds instead; known presets: ${presetList()}`
+                    : `skipping filter "${def.name}": unknown date range preset "${preset}" — ` +
+                        `expected one of: ${presetList()}`);
+            }
             if (!from && !to)
                 return undefined;
             return {
@@ -151,7 +240,13 @@ export function buildFilterCondition(def, value) {
                 ...(to ? { $lte: to } : {}),
             };
         }
-        // A bare string date means equality on that day.
+        if (typeof v === 'string' && !isUsableDateString(v)) {
+            warnDateFilter(`skipping filter "${def.name}": value "${v}" is neither a known date range preset ` +
+                `nor an ISO date — expected one of: ${presetList()}, an ISO date (YYYY-MM-DD), ` +
+                `or a date macro such as {today}`);
+            return undefined;
+        }
+        // A bare string date (or date macro) means equality on that day.
         return value;
     }
     if (def.type === 'select' || def.type === 'lookup') {

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

@@ -27,7 +27,19 @@ export interface DatasetResultField {
     label?: string;
     format?: string;
     currency?: string;
+    percentScale?: PercentScale;
 }
+/**
+ * How a percentage column's stored number relates to its displayed percentage —
+ * the server's answer to a question a `%` format string cannot express:
+ * `fraction` is a 0–1 ratio (`1` ⇒ "100%"), `whole` is already percentage
+ * points (`1` ⇒ "1%"). Resolved from metadata server-side (a `ratio` measure is
+ * a fraction by definition; a measure over a `percent` field inherits that
+ * field's scale) and carried on the result column, so display never has to
+ * infer it from the value's magnitude — the inference that printed a ratio of
+ * exactly 1 as "1.0%" (#3136).
+ */
+export type PercentScale = 'fraction' | 'whole';
 /**
  * Scale a stored `percent`-field value to its DISPLAY magnitude.
  *
@@ -49,7 +61,7 @@ export declare function percentDisplayValue(value: number): number;
  * controls grouping / decimals / percent; it can't be baked into the row value
  * server-side (the same number feeds charts), so it is applied here.
  */
-export declare function formatMeasure(v: unknown, format?: string, currency?: string): string;
+export declare function formatMeasure(v: unknown, format?: string, currency?: string, percentScale?: PercentScale): string;
 /**
  * Format a non-measure (dimension / label) value — the server already resolves
  * dimension display labels, so this only tidies numbers and nulls.

package/dist/utils/dataset-format.js

@@ -28,7 +28,7 @@ export function percentDisplayValue(value) {
  * controls grouping / decimals / percent; it can't be baked into the row value
  * server-side (the same number feeds charts), so it is applied here.
  */
-export function formatMeasure(v, format, currency) {
+export function formatMeasure(v, format, currency, percentScale) {
     if (v == null)
         return '—';
     if (typeof v !== 'number')
@@ -59,7 +59,15 @@ export function formatMeasure(v, format, currency) {
     // (0.75 ⇒ 75%). Scale to display magnitude the SAME way the list-view cell
     // renderer does — otherwise an avg of 0.608 renders as "0.6%" instead of
     // "60.8%", disagreeing with the per-row "75%" the list already shows.
-    const display = isPercent ? percentDisplayValue(v) : v;
+    //
+    // A DECLARED `percentScale` from the server wins outright: the value-magnitude
+    // heuristic below cannot tell a 0–1 ratio of exactly 1 from 1 percentage point
+    // (both are the number 1) and resolves it as "1%", so an SLA rate of full
+    // compliance rendered as "1.0%" instead of "100.0%" (#3136). The heuristic
+    // stays as the fallback for columns that arrive without the annotation.
+    const display = isPercent
+        ? (percentScale ? (percentScale === 'fraction' ? v * 100 : v) : percentDisplayValue(v))
+        : v;
     const body = display.toLocaleString(undefined, { minimumFractionDigits: decimals ?? 0, maximumFractionDigits: decimals ?? 0 });
     return `${legacyDollar}${body}${isPercent ? '%' : ''}`;
 }

package/dist/utils/filter-tokens.d.ts

@@ -5,6 +5,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import { CONTEXT_TOKENS } from '@objectstack/spec/data';
 /**
  * Session-scoped filter placeholders — the sibling vocabulary to
  * `{date-macros}`.
@@ -42,13 +43,19 @@
  * ## Contract source
  *
  * The canonical vocabulary is published as part of the platform contract at
- * `@objectstack/spec` → `CONTEXT_TOKENS` / `classifyFilterToken`. It is
- * mirrored here — exactly as `date-macros.ts` mirrors `DATE_MACRO_TOKENS` —
- * because the installed `@objectstack/spec` predates that export. Keep the two
- * in sync; the duplication is temporary until the next coordinated release.
+ * `@objectstack/spec/data` → `CONTEXT_TOKENS`. This module used to carry a
+ * hand-written copy of that tuple under the spec's own name, with a comment
+ * saying the duplication was "temporary until the next coordinated release"
+ * — the installed spec (17.0.0-rc.0) has exported it for some time, so the
+ * copy was simply a fork wearing the spec's name (objectstack#4115).
+ *
+ * It is now a **re-export**, which is the only form that cannot drift: the
+ * copy was byte-identical, so every value comparison and every behavioural
+ * test passed while it sat here. Reference identity is the one check that
+ * distinguishes a re-export from a fork (objectui#3003).
  */
-/** The complete set of session-scoped filter tokens. */
-export declare const CONTEXT_TOKENS: readonly ["current_user_id", "current_org_id"];
+/** The complete set of session-scoped filter tokens (spec-owned, re-exported). */
+export { CONTEXT_TOKENS };
 export type ContextTokenName = (typeof CONTEXT_TOKENS)[number];
 /** Session values a filter placeholder can resolve against. */
 export interface FilterTokenScope {

package/dist/utils/filter-tokens.js

@@ -5,6 +5,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import { CONTEXT_TOKENS } from '@objectstack/spec/data';
 import { resolveDateMacros } from './date-macros.js';
 /**
  * Session-scoped filter placeholders — the sibling vocabulary to
@@ -43,13 +44,19 @@ import { resolveDateMacros } from './date-macros.js';
  * ## Contract source
  *
  * The canonical vocabulary is published as part of the platform contract at
- * `@objectstack/spec` → `CONTEXT_TOKENS` / `classifyFilterToken`. It is
- * mirrored here — exactly as `date-macros.ts` mirrors `DATE_MACRO_TOKENS` —
- * because the installed `@objectstack/spec` predates that export. Keep the two
- * in sync; the duplication is temporary until the next coordinated release.
+ * `@objectstack/spec/data` → `CONTEXT_TOKENS`. This module used to carry a
+ * hand-written copy of that tuple under the spec's own name, with a comment
+ * saying the duplication was "temporary until the next coordinated release"
+ * — the installed spec (17.0.0-rc.0) has exported it for some time, so the
+ * copy was simply a fork wearing the spec's name (objectstack#4115).
+ *
+ * It is now a **re-export**, which is the only form that cannot drift: the
+ * copy was byte-identical, so every value comparison and every behavioural
+ * test passed while it sat here. Reference identity is the one check that
+ * distinguishes a re-export from a fork (objectui#3003).
  */
-/** The complete set of session-scoped filter tokens. */
-export const CONTEXT_TOKENS = ['current_user_id', 'current_org_id'];
+/** The complete set of session-scoped filter tokens (spec-owned, re-exported). */
+export { CONTEXT_TOKENS };
 /**
  * Near-miss spellings → the token the author meant.
  *

package/dist/utils/freeze-schema.d.ts

@@ -9,7 +9,7 @@
  * System View immutability layer.
  *
  * A "System View" is any UI schema authored in source code (imported `.ts`/`.json`,
- * `as const` literals, or returned from a `defineView()` call). Such schemas are
+ * `as const` literals, or returned from a `defineSystemView()` call). Such schemas are
  * part of the product contract and MUST NOT be mutated at runtime. Mutation
  * would cause behavior drift, break TypeScript inference, and bypass code review.
  *
@@ -37,7 +37,7 @@ export type DeepReadonly<T> = T extends (...args: any[]) => any ? T : T extends
     readonly [K in keyof T]: DeepReadonly<T[K]>;
 } : T;
 /**
- * A schema that has been frozen by `defineView()`. The marker symbol is
+ * A schema that has been frozen by `defineSystemView()`. The marker symbol is
  * non-enumerable and therefore invisible to consumers, but its presence
  * lets us discriminate at runtime.
  */
@@ -52,11 +52,19 @@ export declare function deepFreeze<T>(value: T, seen?: WeakSet<object>): DeepRea
 /**
  * Mark and freeze a code-loaded schema as a System View.
  *
+ * Named `defineView` until objectstack#4115, which is a name `@objectstack/spec`
+ * owns for something else entirely: the spec's `defineView(config)` is the
+ * VIEW-DOCUMENT factory — it parses a `ViewSchema` (`{ list, form, listViews,
+ * formViews }`) and returns a validated `View`. This one takes an arbitrary
+ * object, stamps the System-View marker and deep-freezes it; it validates
+ * nothing. An app-shell comment already conflated the two, which is precisely
+ * the planted-premise failure the guard exists to stop.
+ *
  * @example
  * ```ts
- * import { defineView } from '@object-ui/core';
+ * import { defineSystemView } from '@object-ui/core';
  *
- * export const userListView = defineView({
+ * export const userListView = defineSystemView({
  *   type: 'list',
  *   data: { object: 'User' },
  *   columns: [{ name: 'email' }],
@@ -69,9 +77,9 @@ export declare function deepFreeze<T>(value: T, seen?: WeakSet<object>): DeepRea
  * To produce a mutable derivative (Tenant or User View), call
  * `cloneAsOverride(userListView)`.
  */
-export declare function defineView<T extends object>(schema: T): SystemView<T>;
+export declare function defineSystemView<T extends object>(schema: T): SystemView<T>;
 /**
- * Runtime check: was this object produced by `defineView()` (or loaded from a
+ * Runtime check: was this object produced by `defineSystemView()` (or loaded from a
  * source that forwards the marker)?
  */
 export declare function isSystemView(value: unknown): boolean;

package/dist/utils/freeze-schema.js

@@ -9,7 +9,7 @@
  * System View immutability layer.
  *
  * A "System View" is any UI schema authored in source code (imported `.ts`/`.json`,
- * `as const` literals, or returned from a `defineView()` call). Such schemas are
+ * `as const` literals, or returned from a `defineSystemView()` call). Such schemas are
  * part of the product contract and MUST NOT be mutated at runtime. Mutation
  * would cause behavior drift, break TypeScript inference, and bypass code review.
  *
@@ -86,11 +86,19 @@ export function deepFreeze(value, seen = new WeakSet()) {
 /**
  * Mark and freeze a code-loaded schema as a System View.
  *
+ * Named `defineView` until objectstack#4115, which is a name `@objectstack/spec`
+ * owns for something else entirely: the spec's `defineView(config)` is the
+ * VIEW-DOCUMENT factory — it parses a `ViewSchema` (`{ list, form, listViews,
+ * formViews }`) and returns a validated `View`. This one takes an arbitrary
+ * object, stamps the System-View marker and deep-freezes it; it validates
+ * nothing. An app-shell comment already conflated the two, which is precisely
+ * the planted-premise failure the guard exists to stop.
+ *
  * @example
  * ```ts
- * import { defineView } from '@object-ui/core';
+ * import { defineSystemView } from '@object-ui/core';
  *
- * export const userListView = defineView({
+ * export const userListView = defineSystemView({
  *   type: 'list',
  *   data: { object: 'User' },
  *   columns: [{ name: 'email' }],
@@ -103,9 +111,9 @@ export function deepFreeze(value, seen = new WeakSet()) {
  * To produce a mutable derivative (Tenant or User View), call
  * `cloneAsOverride(userListView)`.
  */
-export function defineView(schema) {
+export function defineSystemView(schema) {
     if (schema == null || typeof schema !== 'object') {
-        throw new TypeError('[ObjectUI] defineView() expects a non-null object schema.');
+        throw new TypeError('[ObjectUI] defineSystemView() expects a non-null object schema.');
     }
     // Stamp the marker on the root only — nested nodes share origin via lineage.
     // Non-enumerable keeps it out of JSON, spreads, and Object.keys.
@@ -120,7 +128,7 @@ export function defineView(schema) {
     return deepFreeze(schema);
 }
 /**
- * Runtime check: was this object produced by `defineView()` (or loaded from a
+ * Runtime check: was this object produced by `defineSystemView()` (or loaded from a
  * source that forwards the marker)?
  */
 export function isSystemView(value) {

package/dist/utils/managedBy.d.ts

@@ -1,51 +1,54 @@
 /**
- * managedBy — the single source of truth for interpreting an object's
- * lifecycle bucket (`ObjectSchema.managedBy`) into CRUD affordances.
+ * managedBy — the UI end of the platform's `managedBy` → CRUD affordance
+ * contract (ADR-0103).
  *
- * UI-side mirror of the framework's `resolveCrudAffordances()`
- * (`@objectstack/spec/data/object.zod.ts`, ADR-0103). Lives in `@object-ui/core`
- * — React-free and reachable by every UI package (app-shell, plugin-detail,
- * plugin-form, plugin-grid) — so the bucket logic is defined ONCE instead of
- * hand-mirrored in each. Components ask "should I show New / Import / Edit /
- * Delete / Export?" and get an answer that tracks the object's lifecycle without
- * special-casing `sys_*` names.
+ * ## What is spec-owned here, and what is not (objectstack#4115)
  *
- * The bucket UNION type lives in `@object-ui/types` (`ManagedByBucket`) so the
- * schema field can reference it; this module re-exports it for convenience.
- * Only the affordance BOOLEANS live here — all translated copy (badge variants,
- * empty-state messages) stays in `@object-ui/app-shell`.
+ * The bucket logic is **the spec's**, and this module now says so in code
+ * rather than in a comment. `CrudAffordances` / `RowCrudPredicates` are
+ * re-exported from `@objectstack/spec/data`, and the bucket resolution itself
+ * delegates to the spec's `resolveCrudAffordances()`.
+ *
+ * This module used to describe itself as a "UI-side mirror" of that function
+ * and carry its own `DEFAULTS` table — a line-for-line copy of the spec's
+ * `CRUD_AFFORDANCE_DEFAULTS`, plus a copy of its override parser. A faithful
+ * copy passes every value comparison and every behavioural test, so nothing
+ * would have caught the release in which the spec re-buckets an object class;
+ * reference identity is the only check that distinguishes a re-export from a
+ * fork (objectui#3003).
+ *
+ * What is genuinely objectui's and keeps a local name:
+ * {@link resolveEffectiveCrudAffordances} — the spec's object-level matrix
+ * INTERSECTED with the server-resolved effective API operation set (#3391), so
+ * the UI never offers a button the server would 405. The spec's function has
+ * no such notion; naming ours after it was the misdescription this burn-down
+ * removes.
+ *
+ * Lives in `@object-ui/core` — React-free and reachable by every UI package
+ * (app-shell, plugin-detail, plugin-form, plugin-grid) — so the intersection is
+ * defined ONCE instead of hand-mirrored in each. The bucket UNION type lives in
+ * `@object-ui/types` (`ManagedByBucket`) and is re-exported here for
+ * convenience. All translated copy (badge variants, empty-state messages) stays
+ * in `@object-ui/app-shell`.
  */
+import { type CrudAffordances, type RowCrudPredicates } from '@objectstack/spec/data';
 export type { ManagedByBucket } from '@object-ui/types';
-export interface CrudAffordances {
-    /** Generic "New" button for single-record creation. */
-    create: boolean;
-    /** CSV bulk-import wizard. */
-    import: boolean;
-    /** Inline + form editing of existing rows. */
-    edit: boolean;
-    /** Row-level + bulk delete. */
-    delete: boolean;
-    /** CSV / clipboard export. */
-    exportCsv: boolean;
-    /**
-     * Per-record CEL predicates for the built-in row Edit/Delete actions,
-     * present only when `userActions.edit` / `delete` used the object form
-     * (objectui#2614). Carried through as authored for row renderers to evaluate;
-     * they never affect the object-level booleans above.
-     */
-    editPredicates?: RowCrudPredicates;
-    deletePredicates?: RowCrudPredicates;
-}
-/** Per-record predicates from the #2614 object form of a userActions flag. */
-export interface RowCrudPredicates {
-    visibleWhen?: unknown;
-    disabledWhen?: unknown;
-}
+/**
+ * The resolved CRUD affordance matrix and its per-record predicate envelope
+ * are **spec-owned** (`@objectstack/spec/data`, ADR-0103) and re-exported here,
+ * not re-declared.
+ *
+ * Note this also TIGHTENS the predicate types: the local copies typed
+ * `visibleWhen` / `disabledWhen` as `unknown`, while the spec types them as
+ * `Expression | ExpressionInput` — the authored CEL shorthand or its envelope.
+ * The local `unknown` was imprecision, not a deliberate dialect.
+ */
+export type { CrudAffordances, RowCrudPredicates };
 /** `edit`/`delete` accept a bare boolean or the #2614 object form. */
 export type UserActionOverride = boolean | {
     enabled?: boolean;
-    visibleWhen?: unknown;
-    disabledWhen?: unknown;
+    visibleWhen?: RowCrudPredicates['visibleWhen'];
+    disabledWhen?: RowCrudPredicates['disabledWhen'];
 };
 export interface UserActionsOverride {
     create?: boolean;
@@ -63,11 +66,14 @@ export interface SchemaLike {
  * the given bucket default, surfacing any per-record predicates alongside.
  *
  * THE single parser for the `userActions.{edit,delete}` override shape — every
- * UI package (grid row affordances, related-list row predicates, this module's
- * own `resolveCrudAffordances`) routes through here instead of re-implementing
- * the boolean/object-form parse locally. `base` is the bucket default an
- * omitted `enabled` falls back to (callers that only gate on an explicit
- * opt-out pass `true`; predicate extraction is independent of `base`).
+ * UI package (grid row affordances, related-list row predicates) routes through
+ * here instead of re-implementing the boolean/object-form parse locally. The
+ * spec keeps its equivalent (`normalizeRowCrudOverride`) module-private, so
+ * this stays a local declaration — under a name the spec does not own.
+ *
+ * `base` is the bucket default an omitted `enabled` falls back to (callers that
+ * only gate on an explicit opt-out pass `true`; predicate extraction is
+ * independent of `base`).
  */
 export declare function normalizeUserAction(v: UserActionOverride | undefined | null, base: boolean): {
     enabled: boolean;
@@ -82,7 +88,15 @@ export declare function normalizeUserAction(v: UserActionOverride | undefined |
  */
 export declare function userActionPredicates(v: UserActionOverride | undefined | null): RowCrudPredicates | undefined;
 /**
- * Resolve the effective CRUD affordances for an object schema.
+ * Resolve the CRUD affordances a UI surface should expose for an object —
+ * the spec's object-level matrix, INTERSECTED with what the server will
+ * actually accept.
+ *
+ * The bucket/`userActions` half is **not computed here**: it is delegated to
+ * `resolveCrudAffordances()` from `@objectstack/spec/data` (ADR-0103), so the
+ * bucket table has exactly one definition on the platform. Only the
+ * intersection below is objectui's, which is why this function no longer
+ * carries the spec's name (objectstack#4115).
  *
  * @param obj The object schema (managedBy bucket + userActions overrides).
  * @param effectiveApiOperations OPTIONAL server-resolved effective API operation
@@ -93,13 +107,27 @@ export declare function userActionPredicates(v: UserActionOverride | undefined |
  *   (old backend / no effective set) leaves the affordances untouched —
  *   backward-compatible. An empty array means "expose nothing" → all bits off.
  */
-export declare function resolveCrudAffordances(obj: SchemaLike | null | undefined, effectiveApiOperations?: readonly string[] | null): CrudAffordances;
+export declare function resolveEffectiveCrudAffordances(obj: SchemaLike | null | undefined, effectiveApiOperations?: readonly string[] | null): CrudAffordances;
 /** True only when a `userActions` flag (bare boolean or #2614 object form) opts the write in. */
 export declare function isWriteOptedIn(v: UserActionOverride | undefined | null): boolean;
 /**
- * ADR-0103 — a `system`-bucket object that opened ANY write via `userActions`
- * is admin/user-writable DATA, not an engine-owned monitoring surface. Used to
- * pick the writable-system badge/empty-state copy.
+ * True for a platform-defined schema whose DATA is admin/user-writable — the
+ * `system-data` bucket. Used to pick the writable-system badge/empty-state copy
+ * instead of the engine-owned "read-only monitoring surface" copy.
+ *
+ * **Simplified in protocol 17 (objectstack#3355).** Under ADR-0103's v16 split
+ * this had to RECOVER the distinction from `userActions`: `system` doubled as
+ * both the engine-owned default and the writable set, so "did it open any
+ * write?" was the only way to tell a Notification Preferences grid from an
+ * automation-run log. v17 retired that overload — the writable half is now the
+ * `system-data` bucket (writable by DEFAULT) and the engine-owned half is
+ * `engine-owned` — so the bucket answers the question directly and the
+ * `userActions` probe would only re-derive what the value already states.
+ *
+ * The narrowing case is deliberately still `true`: a `system-data` grid that
+ * narrows to edit-only is still platform-schema/user-data and should read as
+ * such. The spec refuses `system-data` on an object that narrows away every
+ * write, so there is no "writable bucket with no writes" shape to worry about.
  */
 export declare function isSystemWritable(obj: SchemaLike | null | undefined): boolean;
 /**