@wildo-ai/saas-frontend-lib 1.1.9 → 1.1.11

package/dist/esm/core/resources/resources.frontend.schemas.js

@@ -1,6 +1,6 @@
 import { RESPONSIVE_MAX_WIDTH_VALUES } from '@wildo-ai/presets-components-models';
 import { z } from "zod";
-import { getZodObjectShape } from '@wildo-ai/zod-decorators';
+import { getZodObjectShape, withObjectFields } from '@wildo-ai/zod-decorators';
 import { ResourceOperationDisplayMode, ResourceOperationFrontendSurface, NavigationZoneName, OverlayAppearance, TransitionConfigSchema, ZoneEmptyBehavior, viewportDiscriminatedSchema, computePolymorphicVariantSchemas, } from '@wildo-ai/saas-models';
 import { ViewportBreakpoint, DisplayDirection } from '@wildo-ai/zod-decorators';
 import { VerticalPlacement, HorizontalPlacement, } from '@wildo-ai/presets-components-models';
@@ -49,6 +49,7 @@ export const NavigationOperationOverrideSchema = z.object({
 // Defined in resource-path.frontend.schemas.ts (import here only — no re-export).
 // --------------------------------
 import { FrontendResourceOperationPathSchema } from './resource-path.frontend.schemas.js';
+import { LauncherRuntimeAvailabilityConfigSchema } from '../../core/config/launcher-items.frontend.schemas.js';
 import { UpdateLikeMutationFallbackMode } from '../../core/resources/rmm/update-like-mutation-fallback.frontend.js';
 /** ──────────────────────────────────────────────────────────────
  * Internal Schemas (concrete, for method access)
@@ -104,11 +105,72 @@ export var ResourceFrontend_GuidanceFlowTriggerType;
 // ── Schema bridge key ───────────────────────────────────────────────
 /**
  * Symbol key used internally by `resourceUIBehavior()` to attach the schema
- * reference to the config object, and by `buildFrontendResourceConfigurations()`
+ * the resource PRESENTS to the config object, and by `buildFrontendResourceConfigurations()`
  * to extract it. Using a Symbol prevents collision with user-defined properties
  * and is invisible in Object.keys()/JSON serialization.
+ *
+ * The schema it carries is the resource's schema with every `fields` entry swapped in
+ * (#1308): a decorator returns a decorated copy, so a `fields` override reaches the
+ * frontend through this schema and through nothing else.
  */
 export const FRONTEND_SCHEMA_KEY = Symbol('frontendSchema');
+/**
+ * Symbol key for the schema a ui-behavior was DECLARED over: the schema its author passed in, before `fields` and
+ * `schemaOverride` are composed in (#2918). Per key, what `FRONTEND_SCHEMA_KEY` changes relative to it is the
+ * ui-behavior's presentation, which the frontend registry composes onto the resource's own schema — so the fields the
+ * resource factory adds (a polymorphic variant's parent key, `retentionStatus`, …) are kept rather than replaced by
+ * the schema the author held. A polymorphic variant's entry carries that variant's renamed declared schema, matching
+ * its renamed `FRONTEND_SCHEMA_KEY`.
+ *
+ * Absent on a config built by hand: the registry then reads the resource's own schema as the declared one.
+ */
+export const FRONTEND_DECLARED_SCHEMA_KEY = Symbol('frontendDeclaredSchema');
+/**
+ * The composed but UN-RENAMED schema of a polymorphic ui-behavior, kept on each variant entry so
+ * `polymorphicResourceUIBehaviorFrom()` derives from the base its `fields` keys name. Each variant's
+ * `FRONTEND_SCHEMA_KEY` is that schema with the variant's foreign keys renamed, whose field names a
+ * derived preset's `fields` do not use.
+ */
+const POLYMORPHIC_BASE_FRONTEND_SCHEMA_KEY = Symbol('polymorphicBaseFrontendSchema');
+/**
+ * The UN-RENAMED schema a polymorphic ui-behavior was declared over, beside its composed base: a derived preset's
+ * presentation is its base's `fields` plus its own, measured against this (#2918).
+ */
+const POLYMORPHIC_DECLARED_BASE_SCHEMA_KEY = Symbol('polymorphicDeclaredBaseSchema');
+/**
+ * The SHARED `fields` of a polymorphic ui-behavior, kept on each variant entry beside the shared base: a variant whose
+ * `variantOverrides` declares its own `fields` carries those as its `fields`, and a derived preset taking that entry as
+ * its base must not hand one variant's decorations to every other.
+ */
+const POLYMORPHIC_SHARED_FIELDS_KEY = Symbol('polymorphicSharedFields');
+/**
+ * The schema a ui-behavior presents: `schema` with each `fields` entry swapped in as the field it
+ * decorates (#1308).
+ *
+ * `fields: { status: schemaShape.status.enumUI(...) }` used to work by MUTATING the shared shape field,
+ * so nothing read `fields` at all — and every other resource, test or specification holding that field
+ * saw the decoration too. A decorator now returns a copy, so the copies are composed here into a row
+ * schema of this resource's own, which is what `FRONTEND_SCHEMA_KEY` carries.
+ *
+ * Refines nothing and adds no field: a key the schema does not declare is refused, and so is a
+ * non-empty `fields` on a schema that is not an object (decorate such a field where it is declared).
+ */
+function composeFrontendSchema(schema, fields, factoryName) {
+    const entries = Object.entries(fields ?? {}).filter(([, field]) => field !== undefined);
+    if (entries.length === 0)
+        return schema;
+    const type = schema?._zod?.def?.type;
+    if (type !== 'object') {
+        throw new Error(`${factoryName}: \`fields\` decorates fields of an object schema, and this resource's schema is a "${String(type)}" ` +
+            `(${entries.map(([key]) => key).join(', ')}). Decorate those fields where the schema declares them.`);
+    }
+    const shape = getZodObjectShape(schema);
+    const unknown = entries.map(([key]) => key).filter((key) => !(key in shape));
+    if (unknown.length > 0) {
+        throw new Error(`${factoryName}: \`fields\` names ${unknown.map((key) => `"${key}"`).join(', ')}, which the resource's schema does not declare.`);
+    }
+    return withObjectFields(schema, Object.fromEntries(entries));
+}
 /** @wildo_source:part:end saas.frontend.operation-key-and-resource-config-like */
 // ── Operation-level frontend config ─────────────────────────────────
 /**
@@ -157,51 +219,80 @@ export var CollectionFilterPanelVisibility;
     /** No trigger and no panel — narrowing happens through the tabs and pills only; the chips remain. */
     CollectionFilterPanelVisibility["HIDDEN"] = "hidden";
 })(CollectionFilterPanelVisibility || (CollectionFilterPanelVisibility = {}));
+/**
+ * @wildo_source:part:start saas.frontend.collection-filter-presets facet:layer:frontend facet:family:resource-operation facet:audience:app-developer
+ */
 /**
  * A DATE WINDOW named relative to NOW, for a preset filter that must mean the same thing tomorrow.
  *
  * A preset is authored once and clicked forever, so "created today" cannot be an authored pair of
  * instants — it has to be RESOLVED at the moment it is applied. The vocabulary is closed and small
  * on purpose: each member is a window a person actually asks for, and each resolves to the
- * `{ startDate, endDate }` pair the framework's date-range filter already carries end to end, so a
- * preset needs no filter grammar of its own and no backend change.
- *
- * Resolution is in the VIEWER's timezone, which is the only one that makes "today" true for the
- * person reading the screen. The backend compares instants, so the boundaries travel as absolute
- * times and nothing downstream has to know a timezone was involved.
+ * `{ startDate?, endDate? }` pair the framework's date-range filter already carries end to end, so a
+ * preset needs no filter grammar of its own and no backend change. A window may be open on one side:
+ * "before today" has no start, and the filter treats an absent bound as unbounded on every adapter.
+ *
+ * Every member is a span of WHOLE calendar days counted from today in the reader's resolved timezone
+ * (member, then organization, then floor), which is the only one that makes "today" true for the person
+ * reading the screen, and the one the list's own date words use. Over an instant field the window runs
+ * between that zone's midnights; over a calendar-day field (`isCalendarDate()`) it covers those calendar
+ * days, held as UTC midnights, so a due date is the same day for every reader. Both bounds are included,
+ * as the backend's range filter includes them, so the window ends one millisecond before the day after
+ * its last day begins. The backend compares instants, so nothing downstream has to know a zone was involved.
  */
 export var CollectionFilterPresetRelativeRange;
 (function (CollectionFilterPresetRelativeRange) {
-    /** Midnight this morning until midnight tonight, local. */
+    /** Today, from the reader's midnight this morning to the last instant before midnight tonight. */
     CollectionFilterPresetRelativeRange["TODAY"] = "today";
-    /** The same window, one day back. */
+    /** All of yesterday, in the reader's calendar. */
     CollectionFilterPresetRelativeRange["YESTERDAY"] = "yesterday";
     /** The last seven days INCLUDING today — the rolling week, not the last seven whole days. */
     CollectionFilterPresetRelativeRange["LAST_7_DAYS"] = "last_7_days";
     /** The last thirty days including today. */
     CollectionFilterPresetRelativeRange["LAST_30_DAYS"] = "last_30_days";
-    /** The first of this calendar month until now. */
+    /** The first of this calendar month through the end of today. */
     CollectionFilterPresetRelativeRange["THIS_MONTH"] = "this_month";
-    /** The first of this calendar year until now. */
+    /** The first of this calendar year through the end of today. */
     CollectionFilterPresetRelativeRange["THIS_YEAR"] = "this_year";
+    /**
+     * Every day BEFORE today in the reader's calendar: what an "overdue" list shows on a due-date field. The window has
+     * no start and ends at the last instant of yesterday, so a due date of TODAY is due, not overdue. A deadline with a
+     * time earlier today is in TODAY, not here: the window is whole days, like every other member, so the pill reads the
+     * same all day.
+     */
+    CollectionFilterPresetRelativeRange["BEFORE_TODAY"] = "before_today";
+    /** Today and the six calendar days after it, in the reader's calendar: "due this week" from today. */
+    CollectionFilterPresetRelativeRange["NEXT_7_DAYS"] = "next_7_days";
+    /** Today and the twenty-nine calendar days after it, in the reader's calendar. */
+    CollectionFilterPresetRelativeRange["NEXT_30_DAYS"] = "next_30_days";
 })(CollectionFilterPresetRelativeRange || (CollectionFilterPresetRelativeRange = {}));
 /**
- * What a preset ASSIGNS to one filter field.
- *
- * Two members, and the split is between a value that is FIXED at authoring time and one that can
- * only be known when the pill is clicked. A literal covers every enum value, id, number and flag —
- * which is the whole of "filter to HIGH priority". A relative range covers the temporal case, whose
- * defining property is that an authored answer would be wrong by tomorrow.
+ * A value a preset can only know once it is clicked, because it depends on WHO is looking. Resolved from the
+ * viewer's session at that moment, like a relative range is resolved from the clock, so "My jobs" means the person
+ * reading the list, whoever that is.
  *
- * A NUMERIC BOUND is the third, and it is the one that needed the rest of the stack before it could
- * mean anything: the framework's collection filters carried a date range and scalars and no numeric
- * range, so a preset could have declared "cost below 500" and nothing between here and the database
- * would have honoured it. It is expressible now because `Resources_Filter_NumberRangeSchema`, the
- * controller's fail-closed value guard and the cross-adapter normalizer all learned the `{ min, max }`
- * vocabulary — a preset assigning one is writing the same value the filter panel's own two inputs do.
+ * A preset naming one is unavailable to a viewer the value cannot be resolved for (no signed-in user): the pill is
+ * disabled rather than applied without the field, which would show a different list under the same name.
+ */
+export var CollectionFilterPresetContextValue;
+(function (CollectionFilterPresetContextValue) {
+    /** The signed-in user's id, for a reference field such as an assignee or owner. */
+    CollectionFilterPresetContextValue["CURRENT_USER"] = "current_user";
+})(CollectionFilterPresetContextValue || (CollectionFilterPresetContextValue = {}));
+/**
+ * What a preset ASSIGNS to one filter field.
  *
- * Both bounds optional, for the same reason the schema has them optional: "under 500" is a range
- * with no floor, and that is the commonest threshold anyone asks for.
+ * Four kinds, split by WHEN the value is known:
+ *
+ * - a LITERAL (string, number, boolean) is fixed at authoring time and covers every enum value, id, number and flag,
+ *   which is the whole of "filter to HIGH priority";
+ * - a RELATIVE RANGE (`{ relativeRange }`) is the temporal case, resolved when the pill is clicked, because an authored
+ *   answer would be wrong by tomorrow;
+ * - a NUMERIC BOUND (`{ min?, max? }`) writes the same value the filter panel's own two number inputs do, and the
+ *   backend applies it on every adapter. Both bounds are optional because "under 500" has no floor, and that is the
+ *   commonest threshold anyone asks for;
+ * - a CONTEXT VALUE (`{ contextValue }`) is known only from who is looking, such as "assigned to me", and is resolved
+ *   when the pill is clicked, so the same authored preset shows each viewer their own rows.
  */
 export const CollectionFilterPresetValueSchema = z.union([
     z.string(),
@@ -209,6 +300,7 @@ export const CollectionFilterPresetValueSchema = z.union([
     z.boolean(),
     z.object({ relativeRange: z.enum(CollectionFilterPresetRelativeRange) }),
     z.object({ min: z.number().optional(), max: z.number().optional() }),
+    z.object({ contextValue: z.enum(CollectionFilterPresetContextValue) }),
 ]);
 /**
  * ONE named, one-click narrowing of a collection, rendered as a toggleable pill above the list.
@@ -240,6 +332,7 @@ export const CollectionFilterPresetSchema = z.object({
      */
     filters: z.record(z.string(), CollectionFilterPresetValueSchema),
 });
+/** @wildo_source:part:end saas.frontend.collection-filter-presets */
 /**
  * How CARDS-mode items are arranged. Orthogonal to {@link CollectionDisplayMode}
  * (this only shapes the CARDS body; TABLE ignores it). LIST and GRID are kept as
@@ -529,12 +622,19 @@ export var DisabledActionHandling;
  * - SUMMARY (dense list/table rows) HIDES actions an unmet `enabledCondition`
  *   disables and caps direct actions at 3 before the `…` menu: on a row, a greyed
  *   button is noise repeated N times.
- * - DETAIL (the read view and the bulk bar) SHOWS them, uncapped. Both views used
- *   to hide, on the reasoning that "an inapplicable, greyed button is noise" — true
- *   of a greyed button that explained nothing. An unavailable action now opens its
- *   reason (and, for a bulk selection, offers to keep only the eligible rows), so on
- *   the surface where someone is deciding what to do, hiding it would hide the
- *   answer to "why can't I?".
+ * - DETAIL (the read view, and the bulk bar's disabled-action handling) SHOWS them.
+ *   On the record's own action bar it also caps direct actions at 3 before the `…`
+ *   menu, since the record header puts them on the name's own line. The bulk bar
+ *   takes DETAIL's disabled-action handling but not its cap: it fits its actions to
+ *   the selection bar's width instead (words, then icons, then two and `…`). Both
+ *   views used to hide, on the reasoning that "an inapplicable, greyed button is
+ *   noise" — true of a greyed button that explained nothing. An unavailable action
+ *   now opens its reason (and, for a bulk selection, offers to keep only the eligible
+ *   rows), so on the surface where someone is deciding what to do, hiding it would
+ *   hide the answer to "why can't I?".
+ * - One exception, in the bulk bar only: a bulk action that NO selected row can take
+ *   is hidden, whatever the view's policy — with nothing eligible there is no row to
+ *   keep and no way through, only a greyed button beside the count.
  *
  * A resource overrides either view via `layout.actionDisclosure`.
  */
@@ -552,8 +652,14 @@ export const DEFAULT_ACTION_DISCLOSURE = {
      * bulk bar renders in DETAIL, so a bulk action a selection does not qualify for is now visible and
      * says which rows are the problem.
      */
+    /*
+     * Three actions in view, the rest behind "⋯" (2026-09-30). The detail header now puts the actions on
+     * the TITLE's line, so an uncapped cluster decides how much of the record's name survives: measured
+     * on a Wonder Todos todo in the split pane, six icon buttons plus a view launcher took 328px of a
+     * 670px header and the title wrapped onto three lines. `displayPriority` decides which three stay.
+     */
     [ResourceOperationDisplayMode.DETAIL]: {
-        maxPrimaryActions: undefined,
+        maxPrimaryActions: 3,
         disabledActionHandling: DisabledActionHandling.SHOW_DISABLED,
     },
 };
@@ -585,10 +691,14 @@ export const CardActionPlacementSchema = z.object({
 /**
  * Who paints the identity GLYPH on this operation's page header.
  *
- * The header band renders the resource's registry icon beside the identity line by default. A
- * `layout.header` template that composes its own record-linked glyph (a per-row kind icon, a
+ * The header band renders the resource's registry icon at the start of its title line by default.
+ * A `layout.header` template that composes its own record-linked glyph (a per-row kind icon, a
  * per-family symbol) would otherwise sit BESIDE the resource icon — two glyphs naming one thing.
  *
+ * With `TEMPLATE_OWNED`, wrap that glyph in `<ResourceHeaderLeading>`: it then renders on the
+ * title line, before the name, where the registry icon would have been. Left unwrapped, it stays
+ * with the rest of the template, on the facts line under the name.
+ *
  * Declared at the OPERATION layer rather than detected from the template, deliberately: the
  * resource icon renders before the template mounts, so detection could only suppress it after the
  * fact — a glyph that flashes and vanishes on every load. Mirrors
@@ -620,6 +730,20 @@ export const ResourceOperationFrontendConfigSchema = z.object({
      * (the common case) behaves as `ALWAYS`.
      */
     actionVisibility: z.enum(ActionVisibility).optional(),
+    /**
+     * The shell's runtime capabilities this operation's action needs (#2649), the contract launcher items and settings
+     * sections use (`requiredCapabilities` AND, `requiredRoles` OR). Unmet, the action is left out of every action bar,
+     * as `ActionVisibility.HIDDEN` would leave it; met or omitted, nothing changes.
+     *
+     * For an action whose availability depends on something a row cannot carry and an `enabledCondition` cannot read,
+     * which is the application's configuration of the CURRENT organization. SCIM's Generate and Rotate need a type that
+     * declares `scimProvisioning`: an `enabledCondition` sees the organization row but not what its type declares.
+     *
+     * Presentation, never authorization: the backend still decides the operation, and must refuse it on its own (SCIM's
+     * custom implementation answers 409 `SCIM_TOKEN_ORGANIZATION_TYPE_NOT_DIRECTORY_PROVISIONED`). Read against the
+     * shell's current organization, like every launcher capability.
+     */
+    runtimeAvailability: LauncherRuntimeAvailabilityConfigSchema.optional(),
     /**
      * Where this operation's action sits in the bar — see {@link ActionPlacement}.
      * Omitted derives from `riskLevel` (HIGH/CRITICAL → danger zone, else primary).
@@ -652,30 +776,32 @@ export const ResourceOperationFrontendConfigSchema = z.object({
     rowTargetRequestField: z.string().optional(),
     /**
      * How this operation runs when it is update-like (`resourceOperationLike: UPDATE`) and targets one
-     * row. Omitted means {@link UpdateLikeMutationFallbackMode.RMM_REQUIRED}: it runs through the row's
-     * RMM and fails closed without one, which is right for anything that edits the row's own fields.
+     * row. Omitted, it is DERIVED from the resource:
      *
-     * Declare `DIRECT_OPERATION_FALLBACK` for an ACTION on a row whose resource has no field-write
-     * operation, so no RMM can ever exist for it. A read-only row with a "set this secret" verb is the
-     * case: `resourceOperationLike: UPDATE` is what gives the verb its `…/{id}/<verb>` route, and it
-     * also made every host demand an RMM, so the form refused to submit ("This action failed") and a
-     * form-less verb could not run at all.
+     * - the resource registers a field-write route (the literal `update`, over HTTP):
+     *   {@link UpdateLikeMutationFallbackMode.RMM_REQUIRED}. The action runs through the row's RMM and
+     *   fails closed without one, which is right for anything that edits the row's own fields;
+     * - it registers none: `DIRECT_OPERATION_FALLBACK`, because no RMM can ever exist for its rows. A
+     *   read-only row with verbs (a relationship's Suspend and End, a key's Rotate) is the case:
+     *   `resourceOperationLike: UPDATE` gives each verb its `…/{id}/<verb>` route, and demanding an RMM
+     *   there made every form-bearing verb fail with "This action failed" and send nothing (#1956).
      *
-     * What it means, in every host: use the row's RMM when there is one, and run the operation directly
-     * when there is not. The row id is still resolved first (from the route, else the canonical READ).
-     * What the direct run gives up is the RMM's optimistic state and its version-conflict details. The row
-     * is still re-read after success: the RMM-less `ResourceAutomaticDisplayer` re-reads when
+     * What the direct lane means, in every host: use the row's RMM when there is one, and run the operation
+     * directly when there is not. The row id is still resolved first (from the route, else the canonical
+     * READ). What the direct run gives up is the RMM's optimistic state and its version-conflict details.
+     * The row is still re-read after success: the RMM-less `ResourceAutomaticDisplayer` re-reads when
      * `RESOURCE_OPERATION_EXECUTED` names its row (#1782).
      *
-     * Explicit on purpose. `update-like-mutation-fallback.frontend.ts` makes the weaker lane an opt-in
-     * rather than something a host infers, and this is the per-operation door that opt-in lacked. Every
-     * host that runs an operation reads it through `resolveDeclaredUpdateLikeMutationFallbackMode`: the
-     * form, the form-less `useOperationDirectExecution`, and `useResourceOperationSurface`. A mode a host
+     * So declare it only to override the derivation: `DIRECT_OPERATION_FALLBACK` for an action that does
+     * not edit the row's fields on a resource that HAS an `update` (it then runs even where that route is
+     * not addressable), or `RMM_REQUIRED` to refuse the direct lane outright. Every host that runs an
+     * operation reads the lane through `resolveUpdateLikeMutationFallbackMode`: the form, the form-less
+     * `useOperationDirectExecution`, `useResourceOperationSurface` and the execution surface. A mode a host
      * passes explicitly still outranks it.
      *
      * @example
-     * [Secrets_Operations.SET, {
-     *   surface: ResourceOperationFrontendSurface.EMBEDDED,
+     * // A verb that sends a reminder about an invoice, on a resource that also has `update`.
+     * ['sendReminder', {
      *   updateLikeMutationFallbackMode: UpdateLikeMutationFallbackMode.DIRECT_OPERATION_FALLBACK,
      * }],
      */
@@ -701,9 +827,10 @@ export const ResourceOperationFrontendConfigSchema = z.object({
         displayMode: z.enum(CollectionDisplayMode).optional(),
         userSwitchableDisplayMode: z.boolean().optional(),
         /**
-         * Promote ONE enum filter field to a prominent quick-filter tab strip
-         * rendered above the collection toolbar ("All · <value> · <value> …" —
-         * the Stripe/Ignisign webhook-dashboard idiom, e.g. All/Delivered/Failed).
+         * Promote ONE enum filter field to the collection toolbar's first line: a
+         * segmented control ("All · <value> · <value> …" — the Stripe/Ignisign
+         * webhook-dashboard idiom, e.g. All/Delivered/Failed) while the toolbar is wide,
+         * and a select when it is narrow, where segments would clip.
          *
          * The named field MUST be an enum member of the operation's backend
          * `filterFields` — the tabs write into the SAME filter state as the
@@ -715,9 +842,11 @@ export const ResourceOperationFrontendConfigSchema = z.object({
          */
         quickFilterField: z.string().optional(),
         /**
-         * Named one-click narrowings, rendered as a row of toggleable pills between the quick-filter
-         * tabs and the toolbar. See {@link CollectionFilterPresetSchema} for the semantics and for why
-         * this is not the same mechanism as `quickFilterField`.
+         * Named one-click narrowings, rendered as toggleable pills in the toolbar's action row, beside
+         * search and sort (on a line of their own when the toolbar is narrow). A pressed pill is the
+         * readout of its narrowing, so the field it assigns gets no filter chip. See
+         * {@link CollectionFilterPresetSchema} for the semantics and for why this is not the same
+         * mechanism as `quickFilterField`.
          *
          * Each preset's words come from `resources.<resourceType>.filterPresets.<ref>.label`; a preset
          * whose label is not authored renders its raw `ref`, so a missing label LOOKS missing instead
@@ -727,6 +856,8 @@ export const ResourceOperationFrontendConfigSchema = z.object({
          * presetFilters: [
          *   { ref: 'urgent', filters: { priority: 'high' } },
          *   { ref: 'created-today', filters: { createdAt: { relativeRange: CollectionFilterPresetRelativeRange.TODAY } } },
+         *   { ref: 'overdue', filters: { dueAt: { relativeRange: CollectionFilterPresetRelativeRange.BEFORE_TODAY }, status: 'open' } },
+         *   { ref: 'mine', filters: { assigneeUserId: { contextValue: CollectionFilterPresetContextValue.CURRENT_USER } } },
          * ]
          */
         presetFilters: z.array(CollectionFilterPresetSchema).optional(),
@@ -1028,7 +1159,13 @@ export var ResourceLayoutInlineEditDefault;
  * ```
  */
 export function createPolymorphicFrontendPreset(declaration, config) {
-    const schema = config[FRONTEND_SCHEMA_KEY];
+    // The base the shared and per-variant `fields` name: the un-renamed schema a derived preset carries over,
+    // else the schema the factory was given. Composed BEFORE the foreign-key renames, under the base's names.
+    const derivedBase = config[POLYMORPHIC_BASE_FRONTEND_SCHEMA_KEY];
+    const givenSchema = derivedBase ?? config[FRONTEND_SCHEMA_KEY];
+    const schema = givenSchema === undefined ? undefined : composeFrontendSchema(givenSchema, config.fields, 'createPolymorphicFrontendPreset');
+    // What the presentation is measured against (#2918): the schema the factory was given, carried over by a derived preset.
+    const declaredBase = derivedBase !== undefined ? config[POLYMORPHIC_DECLARED_BASE_SCHEMA_KEY] : givenSchema;
     const { variantOverrides, views: sharedViewsEntries, ...sharedRest } = config;
     const sharedViews = new Map(sharedViewsEntries);
     const sharedConfig = { ...sharedRest, views: sharedViews };
@@ -1038,18 +1175,30 @@ export function createPolymorphicFrontendPreset(declaration, config) {
     // FK fields per variant (e.g. `billingAccountId` →
     // `organizationBillingAccountId` for the ORGANIZATIONS variant). If we
     // attach the un-renamed base schema as `FRONTEND_SCHEMA_KEY` on every
-    // variant, `buildFrontendResourceConfigurations` later replaces the
-    // renamed `mainSchema` with the un-renamed base — and the FK→parent
-    // resolution check throws because the base's `billingAccountId` doesn't
-    // resolve to a unique parent. Mirror the factory's rename at this seam
-    // so per-variant `FRONTEND_SCHEMA_KEY` matches the per-variant
-    // `mainSchema` keys.
-    const variantSchemas = schema !== undefined && schema?._zod?.def?.type === 'object'
-        ? computePolymorphicVariantSchemas(schema, declaration.variants)
+    // variant, its presentation names fields the renamed `mainSchema` does not
+    // have (`billingAccountId`), and the decorations on them never reach the
+    // variant. Mirror the factory's rename at this seam so per-variant
+    // `FRONTEND_SCHEMA_KEY` (and the declared schema beside it, #2918) match
+    // the per-variant `mainSchema` keys.
+    const renamedVariantSchemas = (base) => base !== undefined && base?._zod?.def?.type === 'object'
+        ? computePolymorphicVariantSchemas(base, declaration.variants)
         : null;
+    const variantSchemas = renamedVariantSchemas(schema);
+    const declaredVariantSchemas = renamedVariantSchemas(declaredBase);
+    const declaredFor = (parentResourceType) => declaredVariantSchemas?.get(parentResourceType) ?? declaredBase;
     if (schema !== undefined) {
         sharedConfig[FRONTEND_SCHEMA_KEY] = schema;
+        sharedConfig[POLYMORPHIC_BASE_FRONTEND_SCHEMA_KEY] = schema;
+    }
+    if (declaredBase !== undefined) {
+        sharedConfig[FRONTEND_DECLARED_SCHEMA_KEY] = declaredBase;
+        sharedConfig[POLYMORPHIC_DECLARED_BASE_SCHEMA_KEY] = declaredBase;
     }
+    else {
+        // A derived preset spreads its base's first variant entry, whose declared schema is that variant's RENAMED one.
+        delete sharedConfig[FRONTEND_DECLARED_SCHEMA_KEY];
+    }
+    sharedConfig[POLYMORPHIC_SHARED_FIELDS_KEY] = config.fields;
     const result = {};
     for (const variant of declaration.variants) {
         const override = variantOverrides?.[variant.parentResourceType];
@@ -1064,9 +1213,19 @@ export function createPolymorphicFrontendPreset(declaration, config) {
                 ...overrideRest,
                 views: overrideViewsEntries ? new Map(overrideViewsEntries) : sharedViews,
             };
-            if (variantSchema !== undefined) {
+            // A variant's own `fields` decorate ITS copy only (#1308): composed onto the shared base before that
+            // variant's renames, where they once mutated the field every variant shares.
+            const overrideFields = overrideRest.fields;
+            if (schema !== undefined && overrideFields !== undefined) {
+                // The variant's own base stays OFF the shared-base key, which a derived preset reads (see above).
+                const variantBase = composeFrontendSchema(schema, overrideFields, 'createPolymorphicFrontendPreset (variantOverrides)');
+                concreteConfig[FRONTEND_SCHEMA_KEY] = renamedVariantSchemas(variantBase)?.get(variant.parentResourceType) ?? variantBase;
+            }
+            else if (variantSchema !== undefined) {
                 concreteConfig[FRONTEND_SCHEMA_KEY] = variantSchema;
             }
+            if (declaredBase !== undefined)
+                concreteConfig[FRONTEND_DECLARED_SCHEMA_KEY] = declaredFor(variant.parentResourceType);
             result[variant.resourceType] = concreteConfig;
         }
         else if (variantSchemas && variantSchema !== schema) {
@@ -1074,6 +1233,8 @@ export function createPolymorphicFrontendPreset(declaration, config) {
             // keeps its own FRONTEND_SCHEMA_KEY rather than sharing the base.
             const concreteConfig = { ...sharedConfig, views: sharedViews };
             concreteConfig[FRONTEND_SCHEMA_KEY] = variantSchema;
+            if (declaredBase !== undefined)
+                concreteConfig[FRONTEND_DECLARED_SCHEMA_KEY] = declaredFor(variant.parentResourceType);
             result[variant.resourceType] = concreteConfig;
         }
         else {
@@ -1100,7 +1261,7 @@ export function variant(op, variantKey) {
  *
  * All generics are inferred from the `_factory` argument — no explicit type
  * parameters needed. The callback receives `{ schema, schemaShape, opsVariantResolver }`:
- * - `schema` — the Zod schema (for schema-level mutations like `.stringUI()`, `.enumUI()`, etc.)
+ * - `schema` — the Zod schema (decorate a COPY of it for `schemaOverride`, e.g. `schema.objectUI(...)`)
  * - `schemaShape` — the typed shape object (for per-field decorator overrides with autocomplete)
  * - `opsVariantResolver` — typed variant tuple helper constrained to valid operation keys
  *
@@ -1131,8 +1292,9 @@ export function resourceUIBehavior(_factory, schema, configFactory) {
         ? schema.shape
         : getZodObjectShape(schema));
     const opsVariantResolver = (op, variantKey) => [op, variantKey];
-    const { schemaOverride: _, views: viewsEntries, ...config } = configFactory({ schema, schemaShape, opsVariantResolver: opsVariantResolver });
-    config[FRONTEND_SCHEMA_KEY] = schema;
+    const { schemaOverride, views: viewsEntries, ...config } = configFactory({ schema, schemaShape, opsVariantResolver: opsVariantResolver });
+    config[FRONTEND_SCHEMA_KEY] = composeFrontendSchema(schemaOverride ?? schema, config.fields, 'resourceUIBehavior');
+    config[FRONTEND_DECLARED_SCHEMA_KEY] = schema;
     return {
         ...config,
         views: new Map(viewsEntries),
@@ -1197,6 +1359,11 @@ export function resourceUIBehaviorFrom(_factory, base, overrideFn) {
             executionViews: { ...base.executionViews, ...overrideExecutionViews },
         }),
         views: overrideViews ? new Map(overrideViews) : base.views,
+        // The base's schema already carries the base's `fields`; the derived ones are composed onto a copy, so the
+        // base preset keeps presenting what it declared (#1308).
+        [FRONTEND_SCHEMA_KEY]: composeFrontendSchema(schema, overrideFields, 'resourceUIBehaviorFrom'),
+        // The base's declared schema (#2918): the derived presentation is the base's plus its own.
+        [FRONTEND_DECLARED_SCHEMA_KEY]: base[FRONTEND_DECLARED_SCHEMA_KEY],
     };
 }
 /**
@@ -1236,7 +1403,9 @@ export function polymorphicResourceUIBehaviorFrom(declaration, _factory, baseEnt
     if (!baseConfig) {
         throw new Error(`polymorphicResourceUIBehaviorFrom: no base config found for first variant "${firstVariantType}"`);
     }
-    const schema = baseConfig[FRONTEND_SCHEMA_KEY];
+    // The composed, UN-renamed base: the first variant's FRONTEND_SCHEMA_KEY has that variant's foreign keys
+    // renamed, and deriving from it would rename them a second time.
+    const schema = (baseConfig[POLYMORPHIC_BASE_FRONTEND_SCHEMA_KEY] ?? baseConfig[FRONTEND_SCHEMA_KEY]);
     const schemaShape = (schema && 'shape' in schema
         ? schema.shape
         : getZodObjectShape(schema));
@@ -1253,9 +1422,8 @@ export function polymorphicResourceUIBehaviorFrom(declaration, _factory, baseEnt
         ...(overrideLayout !== undefined && {
             layout: { ...baseConfig.layout, ...overrideLayout },
         }),
-        ...(overrideFields !== undefined && {
-            fields: { ...baseConfig.fields, ...overrideFields },
-        }),
+        // The SHARED fields, never the first variant's own (its `variantOverrides` may have declared some).
+        fields: { ...(baseConfig[POLYMORPHIC_SHARED_FIELDS_KEY] ?? baseConfig.fields), ...(overrideFields ?? {}) },
         ...(overrideCompositeViews !== undefined && {
             compositeViews: { ...baseConfig.compositeViews, ...overrideCompositeViews },
         }),
@@ -1266,6 +1434,8 @@ export function polymorphicResourceUIBehaviorFrom(declaration, _factory, baseEnt
         ...(overrideVariantOverrides !== undefined && {
             variantOverrides: overrideVariantOverrides,
         }),
+        [POLYMORPHIC_BASE_FRONTEND_SCHEMA_KEY]: schema,
+        [POLYMORPHIC_DECLARED_BASE_SCHEMA_KEY]: baseConfig[POLYMORPHIC_DECLARED_BASE_SCHEMA_KEY],
     };
     return createPolymorphicFrontendPreset(declaration, mergedPolyConfig);
 }