@object-ui/data-objectstack 17.5.0 → 17.6.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { ObjectStackClient } from '@objectstack/client';
 import { DroppedFieldsEvent } from '@objectstack/spec/data';
 export { DroppedFieldsEvent } from '@objectstack/spec/data';
-import { RuntimeAuthoringIssue } from '@objectstack/spec/api';
+import { GetMetaItemLayeredResponse, RuntimeAuthoringIssue } from '@objectstack/spec/api';
 export { RuntimeAuthoringIssue } from '@objectstack/spec/api';
 import { DatasetSelection, AnalyticsResult } from '@objectstack/spec/contracts';
 import { DataSource, QueryParams, QueryResult, GlobalSearchResult, DataSourceMutationEvent, BatchTransactionOperation, ImportRequestOptions, ImportRecordsResult, CreateImportJobResult, ImportJobProgressInfo, ImportJobResultsInfo, ListImportJobsOptions, ImportJobSummaryInfo, ImportJobUndoResult, ExportDownloadRequest, DeleteViewResult, FileUploadResult } from '@object-ui/types';
@@ -146,9 +146,9 @@ interface MetadataDraftHeader {
  * metadata item to a FILE — `format: json|yaml|ts`, `path`, `indent`,
  * `prettify`, `sortKeys`, `backup`, `atomic`, `loader`. Not one of those keys
  * exists here, and not one of these exists there: this is the REST client's
- * request envelope — optimistic concurrency (`ifMatch` → `If-Match`), actor
- * attribution, the destructive-change override, the ADR-0033 draft/publish
- * mode, and the owning package. Same words, different layer.
+ * request envelope — optimistic concurrency (`ifMatch` → `If-Match`), the
+ * destructive-change override, the ADR-0033 draft/publish mode, and the
+ * owning package. Same words, different layer.
  */
 interface MetadataClientSaveOptions {
     /**
@@ -157,8 +157,6 @@ interface MetadataClientSaveOptions {
      * edits get a 409 instead of overwriting each other.
      */
     ifMatch?: string;
-    /** Optional actor id, sent as `X-Actor` for history attribution. */
-    actor?: string;
     /**
      * Bypass destructive-change protection (Phase 3a). The server returns
      * `409 destructive_change` with `issues[]` if a write would drop or
@@ -203,14 +201,74 @@ interface MetadataDeleteOptions extends MetadataClientSaveOptions {
      */
     state?: 'active' | 'draft';
 }
-/** Layered view of a metadata item — Phase 3a `?layers=true`. */
+/**
+ * Which layer an overlay was saved at — `'org'` for a tenant overlay, `'env'`
+ * for an environment-level one, `null` exactly when `overlay` is null.
+ *
+ * DERIVED from `@objectstack/spec`, not restated: the vocabulary lives once, in
+ * `GetMetaItemLayeredResponseSchema`'s `overlayScope`
+ * (`z.enum(['org', 'env']).nullable()`), and this alias indexes the published
+ * response type so a scope the spec adds arrives here with no edit. Restating
+ * the union locally is the fork `scripts/check-spec-symbol-derivation.mjs`
+ * exists to reject, and the mirror-image mistake — a consumer re-spelling a
+ * producer's enum — is what this field carried until objectui#4982.
+ *
+ * What it carried: `string | null`, under a comment naming the vocabulary as
+ * `organization | environment | package`. Not one of those three spellings is a
+ * value the producer emits (`metadata-protocol`'s two assignment sites write
+ * `'org'` / `'env'`); the schema rejects all three by name, and `package` is
+ * not a scope this field has ever had. Because the declared type was `string`
+ * the compiler had no opinion, so the wrong comment was the only description of
+ * the vocabulary — a planted premise rather than stale prose, and the reason
+ * the Studio's layer badge shipped the raw value straight to screen.
+ */
+type MetadataOverlayScope = GetMetaItemLayeredResponse['overlayScope'];
+/**
+ * ADR-0010 §3.6 — the four-state metadata protection lock
+ * (`none` / `no-overlay` / `no-delete` / `full`), read from
+ * `GetMetaItemLayeredResponseSchema`'s own `z.enum` rather than spelled out
+ * again here (objectui#5024).
+ *
+ * It used to be written out twice in this file, 42 lines apart: once as
+ * {@link MetadataLayered.lock} (optional) and once as
+ * {@link MetadataAuditEntry.lockState} (nullable), identical in every other
+ * respect and compared by no gate. A fifth state added to one would have left
+ * the other compiling — the same "declared N times, diffed by nothing" failure
+ * objectui#4972 and objectui#4984 record for other vocabularies.
+ *
+ * Deriving beats a local alias the two merely share. The producer of these
+ * values is the framework, and `packages/spec` already declares the vocabulary,
+ * so the copies were restating a schema that existed rather than filling a gap.
+ * The card that reported this recorded the opposite — "`@objectstack/spec` 也没
+ * 有对应的 `z.enum` 可派生" — and so did the audit panel's neighbouring comment;
+ * both predate the enum, which ships in `@objectstack/spec` 17.1.0. This is the
+ * same treatment {@link MetadataOverlayScope} above already gets, and it closes
+ * the cross-repo half of the drift, not just the in-repo half.
+ *
+ * ⚠️ This types what this repo may WRITE. It does NOT constrain what a server
+ * may SEND: {@link MetadataClient.layered} casts the wire value through
+ * unchecked, so every reader must still handle a value outside these four. The
+ * lock banner in `ResourceEditPage` is the worked example.
+ */
+type MetadataLockState = GetMetaItemLayeredResponse['lock'];
+/**
+ * Layered view of a metadata item — the body of
+ * `GET /meta/:type/:name/layers` (`GetMetaItemLayeredResponseSchema`).
+ *
+ * A subset by design: the response also carries `type` / `name`, which the
+ * caller already knows because it passed them in, so
+ * {@link MetadataClient.layered} does not hand them back.
+ */
 interface MetadataLayered<T = unknown> {
     /** Code-level (artifact) item; null if the item only exists as an overlay. */
     code: T | null;
     /** Org/environment overlay (just the saved delta or full overlay row). */
     overlay: T | null;
-    /** Overlay scope (`organization` | `environment` | `package` | null). */
-    overlayScope: string | null;
+    /**
+     * Which layer {@link MetadataLayered.overlay} came from, or null when there
+     * is no overlay. Spec-derived — see {@link MetadataOverlayScope}.
+     */
+    overlayScope: MetadataOverlayScope;
     /** Merged effective view — what the runtime actually sees. */
     effective: T | null;
     /**
@@ -222,7 +280,7 @@ interface MetadataLayered<T = unknown> {
      */
     _diagnostics?: MetadataDiagnostics;
     /** 4-state lock: `none` / `no-overlay` / `no-delete` / `full`. */
-    lock?: 'none' | 'no-overlay' | 'no-delete' | 'full';
+    lock?: MetadataLockState;
     /** Human-readable reason for the lock (tooltip text). */
     lockReason?: string;
     /** Which layer set the lock: artifact / package / overlay / env-forced. */
@@ -252,7 +310,10 @@ interface MetadataAuditEntry {
     id: unknown;
     /** ISO timestamp when the attempt happened. */
     occurredAt: string;
-    /** Who attempted the operation (`x-actor` header or `'system'`). */
+    /**
+     * Who attempted the operation — the identity the request was authorized
+     * as, or `'system'` for internal machine writes (objectstack#7941).
+     */
     actor: string;
     /** Code path that recorded the row (e.g. `protocol.saveMetaItem`). */
     source: string | null;
@@ -263,7 +324,7 @@ interface MetadataAuditEntry {
     /** Machine-readable reason code (`item_locked`, `ok`, …). */
     code: string;
     /** Effective lock at the moment of the attempt. */
-    lockState: 'none' | 'no-overlay' | 'no-delete' | 'full' | null;
+    lockState: MetadataLockState | null;
     /** True when admin forced the write through despite the lock. */
     lockOverridden: boolean;
     /** Request-id for trace correlation (if propagated). */
@@ -492,9 +553,35 @@ declare class MetadataClient {
         };
     } & Record<string, unknown>>;
     /**
-     * Get the 3-state layered view of a metadata item (Phase 3a). Returns
-     * `code` (the artifact / fallback default), `overlay` (the saved
-     * customisation, if any), and `effective` (what the runtime sees).
+     * Get the 3-state layered view of a metadata item: `code` (the packaged
+     * artifact baseline), `overlay` (the tenant customisation row alone) and
+     * `effective` (the merged value the runtime sees).
+     *
+     * Reads **`GET /meta/:type/:name/layers`** — the path the framework declares
+     * for this projection, with a response schema of its own
+     * (`GetMetaItemLayeredResponseSchema`, objectstack#5882 ruling B). It used to
+     * be reached by hanging a `layers` flag on the ordinary item read, which made
+     * one route answer two unrelated representations while `packages/spec`
+     * declared only one of them. That spelling still answers this same body
+     * inside its deprecation window (the response carries RFC 9745
+     * `Deprecation: true` and an RFC 8288 `Link: rel="successor-version"` back to
+     * this path) and is scheduled for removal upstream, so nothing here may
+     * depend on it — the repo-wide ratchet is
+     * `scripts/__tests__/layered-read-declared-path-4016.test.ts`.
+     *
+     * The request is built here rather than delegated to `@objectstack/client`
+     * because the SDK expresses no layered read in EITHER spelling: the
+     * framework's REST route ledger records this route as `server-only`,
+     * "consumed by objectui over plain HTTP", and whether the SDK should express
+     * it is an open upstream product call.
+     *
+     * One behaviour delta rides along with the path, and it is the server's
+     * choice rather than ours: the retired flag FELL THROUGH to the plain item
+     * read on a backend whose protocol implementation had no layered support,
+     * answering the `{ type, name, item }` envelope. A dedicated path refuses to
+     * answer a different resource under this one's declared shape, so it returns
+     * 501 `NOT_IMPLEMENTED` instead — which surfaces here as a thrown error
+     * rather than a view with `code` and `overlay` silently blank.
      */
     layered<T = unknown>(type: string, name: string, options?: {
         packageId?: string;
@@ -530,7 +617,6 @@ declare class MetadataClient {
      * overlay moved while the draft was sitting.
      */
     publish<T = unknown>(type: string, name: string, options?: {
-        actor?: string;
         message?: string;
     }): Promise<T>;
     /**
@@ -542,7 +628,6 @@ declare class MetadataClient {
      * when the target version is a delete tombstone.
      */
     rollback<T = unknown>(type: string, name: string, toVersion: number, options?: {
-        actor?: string;
         message?: string;
     }): Promise<T>;
     /**
@@ -747,66 +832,6 @@ interface MetadataCacheStats {
     hitRate: number;
 }
 
-/**
- * ObjectUI
- * 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.
- */
-/**
- * Contracts module integration for @objectstack/spec v3.0.0
- * Provides plugin contract validation and marketplace publishing utilities.
- */
-interface PluginContract {
-    /** Plugin name */
-    name: string;
-    /** Plugin version */
-    version: string;
-    /** Required peer dependencies */
-    peerDependencies?: Record<string, string>;
-    /** Exported component types */
-    exports: PluginExport[];
-    /** Required permissions */
-    permissions?: string[];
-    /** API surface contract */
-    api?: PluginAPIContract;
-}
-interface PluginExport {
-    /** Export name */
-    name: string;
-    /** Export type */
-    type: 'component' | 'hook' | 'utility' | 'provider';
-    /** Description */
-    description?: string;
-}
-interface PluginAPIContract {
-    /** Consumed data sources */
-    dataSources?: string[];
-    /** Required object schemas */
-    requiredSchemas?: string[];
-    /** Event subscriptions */
-    events?: string[];
-}
-interface ContractValidationResult {
-    valid: boolean;
-    errors: ContractValidationError[];
-    warnings: string[];
-}
-interface ContractValidationError {
-    field: string;
-    message: string;
-    code: string;
-}
-/**
- * Validate a plugin contract against the ObjectStack spec.
- */
-declare function validatePluginContract(contract: PluginContract): ContractValidationResult;
-/**
- * Generate a plugin contract manifest for marketplace publishing.
- */
-declare function generateContractManifest(contract: PluginContract): Record<string, unknown>;
-
 /**
  * ObjectStack-backed `UserDataAdapter` factory.
  *
@@ -886,344 +911,6 @@ interface UserDataAdapter<T> {
  */
 declare function createObjectStackUserStateAdapter<T = unknown>(options: ObjectStackUserStateAdapterOptions): UserDataAdapter<T>;
 
-/**
- * ObjectUI
- * 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.
- */
-/**
- * Integration module for @objectstack/spec v3.0.0
- * Provides third-party service connectors for Slack, email, webhooks.
- */
-type IntegrationProvider = 'slack' | 'email' | 'webhook' | 'teams' | 'discord';
-interface IntegrationConfig {
-    /** Integration provider type */
-    provider: IntegrationProvider;
-    /** Whether this integration is enabled */
-    enabled: boolean;
-    /** Provider-specific configuration */
-    config: Record<string, unknown>;
-    /** Event triggers */
-    triggers?: IntegrationTrigger[];
-}
-interface IntegrationTrigger {
-    /** Event name (e.g. 'record.created', 'record.updated') */
-    event: string;
-    /** Filter condition */
-    filter?: string;
-    /** Template for the message/payload */
-    template?: string;
-}
-interface SlackIntegrationConfig extends IntegrationConfig {
-    provider: 'slack';
-    config: {
-        webhookUrl: string;
-        channel?: string;
-        username?: string;
-        iconEmoji?: string;
-    };
-}
-interface EmailIntegrationConfig extends IntegrationConfig {
-    provider: 'email';
-    config: {
-        smtpHost: string;
-        smtpPort: number;
-        secure: boolean;
-        from: string;
-        to: string[];
-        subject?: string;
-    };
-}
-interface WebhookIntegrationConfig extends IntegrationConfig {
-    provider: 'webhook';
-    config: {
-        url: string;
-        method: 'GET' | 'POST' | 'PUT' | 'PATCH';
-        headers?: Record<string, string>;
-        retryCount?: number;
-        retryDelay?: number;
-    };
-}
-/**
- * Integration service manager.
- * Manages third-party service connections and event dispatching.
- */
-declare class IntegrationManager {
-    private integrations;
-    /**
-     * Register a new integration.
-     */
-    register(id: string, config: IntegrationConfig): void;
-    /**
-     * Remove an integration.
-     */
-    unregister(id: string): void;
-    /**
-     * Get all registered integrations.
-     */
-    getAll(): Map<string, IntegrationConfig>;
-    /**
-     * Get integrations that match a specific event.
-     */
-    getForEvent(event: string): IntegrationConfig[];
-    /**
-     * Dispatch an event to all matching integrations.
-     * Returns results for each integration.
-     */
-    dispatch(event: string, payload: Record<string, unknown>): Promise<Array<{
-        id: string;
-        success: boolean;
-        error?: string;
-    }>>;
-    /**
-     * Send payload to a specific integration.
-     */
-    private send;
-}
-
-/**
- * ObjectUI
- * 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.
- */
-/**
- * Security module integration for @objectstack/spec v3.0.0
- * Provides advanced security policies: CSP config, audit logging, data masking.
- */
-/**
- * Configuration for {@link SecurityManager} — this adapter's browser-side
- * security posture: the CSP header it generates, the in-memory audit log it
- * keeps, and the field-masking rules it applies before a record is rendered.
- *
- * NOT the spec's `SecurityPolicy` (`@objectstack/spec/kernel`), whose name this
- * interface wore until objectui#3160 (objectstack#4115 ledger batch 6). That one
- * is the PACKAGE SUPPLY-CHAIN policy — `{ id, name, autoScan, thresholds,
- * allowedLicenses, prohibitedLicenses, codeSigning, sandbox }` — the rules a
- * marketplace applies when scanning a plugin before install. It shares no key
- * with this one, so there was nothing to derive; the collision is the word
- * "security", not the concept.
- */
-interface SecurityManagerPolicy {
-    /** Content Security Policy configuration */
-    csp?: CSPConfig;
-    /** Audit logging configuration */
-    auditLog?: AuditLogConfig;
-    /** Data masking rules */
-    dataMasking?: DataMaskingConfig;
-}
-interface CSPConfig {
-    /** Script sources */
-    scriptSrc: string[];
-    /** Style sources */
-    styleSrc: string[];
-    /** Image sources */
-    imgSrc: string[];
-    /** Connect sources (APIs, WebSockets) */
-    connectSrc: string[];
-    /** Font sources */
-    fontSrc: string[];
-    /** Frame sources */
-    frameSrc?: string[];
-    /** Report URI for violations */
-    reportUri?: string;
-}
-interface AuditLogConfig {
-    /** Whether audit logging is enabled */
-    enabled: boolean;
-    /** Events to audit */
-    events: AuditEventType[];
-    /** Log retention days */
-    retentionDays?: number;
-    /** External log destination */
-    destination?: 'console' | 'server' | 'both';
-}
-type AuditEventType = 'auth.login' | 'auth.logout' | 'auth.failed' | 'data.create' | 'data.read' | 'data.update' | 'data.delete' | 'admin.config' | 'admin.user' | 'admin.role';
-interface DataMaskingConfig {
-    /** Fields to mask */
-    rules: DataMaskingRule[];
-    /** Default masking character */
-    maskChar?: string;
-}
-interface DataMaskingRule {
-    /** Field name or pattern */
-    field: string;
-    /** Masking strategy */
-    strategy: 'full' | 'partial' | 'hash' | 'redact';
-    /** Number of visible characters (for partial masking) */
-    visibleChars?: number;
-    /** Roles that can see unmasked data */
-    exemptRoles?: string[];
-}
-interface AuditLogEntry {
-    /** Event timestamp */
-    timestamp: string;
-    /** Event type */
-    event: AuditEventType;
-    /** User who triggered the event */
-    userId: string;
-    /** Target resource */
-    resource?: string;
-    /** Record ID */
-    recordId?: string;
-    /** Additional details */
-    details?: Record<string, unknown>;
-    /** IP address */
-    ipAddress?: string;
-}
-/**
- * Security policy manager.
- * Handles CSP generation, audit logging, and data masking.
- */
-declare class SecurityManager {
-    private policy;
-    private auditLog;
-    constructor(policy?: SecurityManagerPolicy);
-    /**
-     * Generate a CSP header string from the configuration.
-     */
-    generateCSPHeader(): string;
-    /**
-     * Record an audit log entry.
-     */
-    recordAudit(entry: Omit<AuditLogEntry, 'timestamp'>): void;
-    /**
-     * Get audit log entries.
-     */
-    getAuditLog(filter?: {
-        event?: AuditEventType;
-        userId?: string;
-        since?: string;
-    }): AuditLogEntry[];
-    /**
-     * Apply data masking to a record.
-     */
-    maskRecord(record: Record<string, unknown>, userRoles?: string[]): Record<string, unknown>;
-    /**
-     * Update the security policy.
-     */
-    updatePolicy(policy: Partial<SecurityManagerPolicy>): void;
-    /**
-     * Get current security policy.
-     */
-    getPolicy(): SecurityManagerPolicy;
-}
-
-/**
- * ObjectUI
- * 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.
- */
-/**
- * Studio module integration for @objectstack/spec v3.0.0
- * Provides visual designer schema improvements: canvas, property editors, theme builder.
- */
-interface StudioCanvasConfig {
-    /** Canvas width */
-    width: number;
-    /** Canvas height */
-    height: number;
-    /** Background type */
-    background: 'grid' | 'dots' | 'lines' | 'none';
-    /** Grid size in pixels */
-    gridSize: number;
-    /** Snap to grid */
-    snapToGrid: boolean;
-    /** Zoom range */
-    zoom: {
-        min: number;
-        max: number;
-        step: number;
-        current: number;
-    };
-    /** Pan offset */
-    panOffset: {
-        x: number;
-        y: number;
-    };
-    /** Show minimap */
-    showMinimap: boolean;
-    /** Minimap position */
-    minimapPosition: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-}
-interface StudioPropertyEditor {
-    /** Property name */
-    name: string;
-    /** Display label */
-    label: string;
-    /** Editor type */
-    type: 'text' | 'number' | 'boolean' | 'select' | 'color' | 'code' | 'expression';
-    /** Default value */
-    defaultValue?: unknown;
-    /** Options for select type */
-    options?: Array<{
-        label: string;
-        value: string;
-    }>;
-    /** Group/category */
-    group?: string;
-    /** Description */
-    description?: string;
-    /** Whether the property supports live preview */
-    livePreview?: boolean;
-}
-interface StudioThemeBuilderConfig {
-    /** Available color palettes */
-    palettes: StudioColorPalette[];
-    /** Typography presets */
-    typography: StudioTypographyPreset[];
-    /** Spacing scale */
-    spacing: number[];
-    /** Border radius options */
-    borderRadius: number[];
-    /** Shadow presets */
-    shadows: StudioShadowPreset[];
-}
-interface StudioColorPalette {
-    name: string;
-    colors: Record<string, string>;
-}
-interface StudioTypographyPreset {
-    name: string;
-    fontFamily: string;
-    fontSize: Record<string, string>;
-    fontWeight: Record<string, number>;
-    lineHeight: Record<string, string>;
-}
-interface StudioShadowPreset {
-    name: string;
-    value: string;
-}
-/**
- * Default canvas configuration for designers.
- */
-declare function createDefaultCanvasConfig(overrides?: Partial<StudioCanvasConfig>): StudioCanvasConfig;
-/**
- * Snap a position to the grid.
- */
-declare function snapToGrid(x: number, y: number, gridSize: number): {
-    x: number;
-    y: number;
-};
-/**
- * Calculate auto-layout positions for a set of items.
- * Uses a simple grid-based layout algorithm.
- */
-declare function calculateAutoLayout(items: Array<{
-    id: string;
-    width: number;
-    height: number;
-}>, canvasWidth: number, padding?: number, gap?: number): Array<{
-    id: string;
-    x: number;
-    y: number;
-}>;
-
 /**
  * Map human-readable filter operator names produced by SDUI view configs
  * (e.g. `lead.view.ts`) to the canonical operator symbols expected by the
@@ -1416,10 +1103,97 @@ declare class AnalyticsNotInstalledError extends Error {
     readonly code = "ANALYTICS_NOT_INSTALLED";
     /** The surface that was unavailable, for the message a host renders. */
     readonly surface: string;
-    constructor(surface: string, detail?: string);
+    /**
+     * The server's own ADR-0112 code — the field this branch was chosen BY, when
+     * a producer named one (`NOT_IMPLEMENTED` from the mounted route with no
+     * service behind it, `ROUTE_NOT_FOUND` from the dispatcher when the route is
+     * not mounted at all). Absent for the no-code residual, where a bare
+     * transport 404/501 is all there was to read.
+     *
+     * Additive (objectui#5663): carried so a reader can audit that the headline
+     * and the quoted `detail` below came off the same answer.
+     */
+    readonly serverCode?: string;
+    constructor(surface: string, detail?: string, serverCode?: string);
 }
 /** True when `error` is an {@link AnalyticsNotInstalledError} (or its wire twin). */
 declare function isAnalyticsNotInstalledError(error: unknown): boolean;
+/**
+ * Thrown when the dataset route ANSWERED and said the dataset this query named
+ * does not exist in this environment — `404` + ADR-0112 `NOT_FOUND`, the
+ * `body.datasetName` lookup miss in `@objectstack/rest`'s
+ * `registerAnalyticsEndpoints` (`Dataset "<name>" not found.`).
+ *
+ * A SIBLING of {@link AnalyticsNotInstalledError}, never a shade of it
+ * (objectui#5663). Both conditions answer **404** — routes-not-mounted through
+ * the runtime dispatcher's `ROUTE_NOT_FOUND`, an unknown dataset through this
+ * route's own `NOT_FOUND` — so a `res.status === 404` test cannot separate
+ * them, and the mapping that could not tell them apart reported EVERY unknown
+ * dataset as a missing server capability.
+ *
+ * Measured live on a prod tenant: four HotCRM Executive Overview widgets told
+ * the operator to install `@objectstack/service-analytics` and mount
+ * `AnalyticsServicePlugin`, while the analytics service was installed and
+ * answering the whole time. The real condition was an installed
+ * `app.objectstack.hotcrm` pinned at 1.3.0 whose datasets ship in 2.2.2. The
+ * remedy the banner named — install a server plugin — is the opposite corner of
+ * the system from the remedy that works: upgrade the installed app. A wrong
+ * diagnosis is not a smaller version of no diagnosis; it spends the operator's
+ * time in the wrong subsystem.
+ *
+ * The `code` is the ONLY field that separates the two, which is why this branch
+ * reads it and nothing else. See `readAnalyticsErrorEnvelope` below — the
+ * module-private reader that pulls the code out of either declared envelope.
+ */
+declare class AnalyticsDatasetNotFoundError extends Error {
+    readonly code = "ANALYTICS_DATASET_NOT_FOUND";
+    /**
+     * The dataset this query asked for, taken from the REQUEST rather than parsed
+     * back out of the server's prose: the request is what we know for certain,
+     * and re-reading the name out of a message would make the headline depend on
+     * that message's WORDING — the coupling framework#5367 spent a whole issue
+     * removing from the producing route.
+     */
+    readonly datasetName?: string;
+    /** The server's own ADR-0112 code — the field this branch was chosen BY. */
+    readonly serverCode?: string;
+    /** The server's own message, quoted verbatim in the parenthetical. */
+    readonly serverMessage?: string;
+    constructor(opts: {
+        datasetName?: string;
+        serverCode?: string;
+        serverMessage?: string;
+    });
+}
+/**
+ * Thrown when the dataset query was refused before it ran because the session
+ * is not authenticated — `401` + ADR-0112 `UNAUTHENTICATED`, the REST seam's
+ * `ANONYMOUS_DENY_BODY` (`@objectstack/core`'s `security/anonymous-deny.ts`,
+ * written verbatim by `enforceAuth`).
+ *
+ * The THIRD branch, and the one the reported card under-states (objectui#5663):
+ * it recorded a live `POST /api/v1/analytics/dataset/query -> 401
+ * UNAUTHENTICATED` and read it as evidence for the dataset-unknown branch. It
+ * is neither of the other two. An expired session reported as "the deployment
+ * is missing a capability" is the SAME defect wearing a different mask — an
+ * operator sent to install a server plugin because their token lapsed — so the
+ * separation is the point, not a nicety.
+ *
+ * Deliberately not left to the generic `Dataset query failed: 401 …` either:
+ * that string names a transport status where a person needs an action, and
+ * "sign in again" is an action.
+ */
+declare class AnalyticsUnauthenticatedError extends Error {
+    readonly code = "ANALYTICS_UNAUTHENTICATED";
+    /** The server's own ADR-0112 code — the field this branch was chosen BY. */
+    readonly serverCode?: string;
+    /** The server's own message, quoted verbatim in the parenthetical. */
+    readonly serverMessage?: string;
+    constructor(opts?: {
+        serverCode?: string;
+        serverMessage?: string;
+    });
+}
 /**
  * Thrown when the server REJECTED the analytics query body (HTTP 400 —
  * `VALIDATION_FAILED` since framework#4010 validates `/analytics/query` at the
@@ -1442,25 +1216,73 @@ declare class AnalyticsQueryRejectedError extends Error {
  *
  * `@objectstack/client`'s fetch wrapper throws on a non-2xx, decorating the
  * error with the semantic `code` string and the numeric `httpStatus` (the
- * ADR-0112 / framework#3842 shape this repo already reads elsewhere). Two
- * outcomes must NOT be conflated:
- *
- *   - **`not-installed`** — the deployment has no analytics service. Since
- *     framework#3891 retired the degraded in-kernel shim, that is a 404 (the
- *     routes aren't mounted at all, framework#4019) or a 501 `NOT_IMPLEMENTED`
- *     (REST's dataset route with no service behind it). Degrading to a
- *     client-side aggregate over a scoped `find()` is CORRECT here.
- *   - **`rejected`** — the server refused OUR body (400 `VALIDATION_FAILED`;
- *     framework#4010 validates `/analytics/query` at the entry). Degrading
- *     would answer our own contract violation with plausible numbers from a
- *     different code path and bury it — the misdirection framework#3878
- *     documented. It must be surfaced.
- *
- * Anything else (5xx, network) is `unknown`: degrade, but silently — it is a
- * transient failure, not a deployment that is missing a capability.
+ * ADR-0112 / framework#3842 shape this repo already reads elsewhere).
+ *
+ * ## The `code` is the contract; the status is a transport fact (objectui#5721)
+ *
+ * What stood here tested `status === 404 || status === 501` BEFORE the code
+ * operands that followed them, so the status short-circuited every one of
+ * them: any 404 on this face was `not-installed` whatever code it carried, and
+ * `NOT_IMPLEMENTED` / `ROUTE_NOT_FOUND` were unreachable for the very
+ * conditions they name. Three unrelated conditions answer 404 on this url —
+ *
+ *   route absent    404 `ROUTE_NOT_FOUND`  (runtime dispatcher, framework#4019)
+ *   cube unknown    404 `CUBE_NOT_FOUND`   (service-analytics' inference gate)
+ *   object unknown  404 `OBJECT_NOT_FOUND` (the `/data` fallback's own answer)
+ *
+ * — so a misspelled cube read as "this deployment has no analytics", told the
+ * operator to install a server plugin, and re-answered the chart from a
+ * different code path. Same defect as objectui#5663, arrived at from the other
+ * direction: the mapping read a field it did not quote. Branch on the `code`;
+ * consult the status only as a residual, when the answer declared no code at
+ * all. Comparisons go through `errorCodeIs`/`errorCodeIsAnyOf` — the pre- and
+ * post-ADR-0112 spellings both have to match (`@object-ui/types`).
+ *
+ * ### Both envelope families reach this function already decorated (MEASURED)
+ *
+ * `/analytics/query` exits through `@objectstack/runtime`'s
+ * `dispatcher-plugin.errorResponseBase`, i.e. the **wrapped** `{ success:
+ * false, error: { code, message } }` shape — not the flat one the dataset
+ * route writes — and its 401 is `enforceAuth`'s **flat** `ANONYMOUS_DENY_BODY`.
+ * The client's fetch wrapper flattens BOTH before throwing:
+ * `errorBody?.code ?? errorBody?.error?.code` → `error.code`, plus
+ * `error.httpStatus = res.status`. So no envelope reading belongs here; unlike
+ * `queryDataset` (which owns its `fetch` and must read the body itself), this
+ * function is handed the already-flattened error and reads one field.
+ *
+ * ## Each branch names ONE of the three outcomes the caller can take
+ *
+ *   - **`not-installed`** — *degrade LOUDLY*. The deployment has no analytics
+ *     service: 501 `NOT_IMPLEMENTED` (route mounted, nothing behind it) or 404
+ *     `ROUTE_NOT_FOUND` (framework#4019 stops mounting the routes at all).
+ *     A client-side aggregate over a scoped `find()` answers the chart
+ *     correctly, and the operator is told once that the semantic layer is off.
+ *   - **`rejected`** — *THROW*. The server refused OUR body (400
+ *     `VALIDATION_FAILED`; framework#4010 validates `/analytics/query` at the
+ *     entry). Degrading would answer our own contract violation with plausible
+ *     numbers from a different code path and bury it — the misdirection
+ *     framework#3878 documented.
+ *   - **`unauthenticated`** — *THROW*. 401 `UNAUTHENTICATED`: the request was
+ *     refused before it ran, so it is evidence about the SESSION and none at
+ *     all about the capability. Degrading is not merely misleading here, it is
+ *     futile: the fallback's `find()` carries the same lapsed token and is
+ *     refused the same way, so the chart cannot be answered either. "Sign in
+ *     again" is an action; "install @objectstack/service-analytics" is not.
+ *   - **`cube-not-found`** — *THROW*. 404 `CUBE_NOT_FOUND`
+ *     (`analytics-service.assertInferableCube`, framework#3867): analytics IS
+ *     installed and answering — the NAME does not exist. That gate throws only
+ *     when the name is neither a registered cube nor a registered object, and
+ *     the fallback asks `/data/<the same name>`, which objectql's
+ *     `assertObjectRegistered` (framework#3770) answers 404 `OBJECT_NOT_FOUND`.
+ *     So degrading cannot produce numbers; it can only swap a message that
+ *     names the fix ("Define a Cube in your stack, or check the object name")
+ *     for a distant one, behind a warning that instructs the wrong repair.
+ *   - **`unknown`** — *degrade SILENTLY*. Anything else (5xx, network, a code
+ *     this consumer does not know): a transient failure, not a deployment
+ *     missing a capability and not a request that named something absent.
  */
 declare function classifyAnalyticsFailure(error: unknown): {
-    kind: 'not-installed' | 'rejected' | 'unknown';
+    kind: 'not-installed' | 'rejected' | 'unauthenticated' | 'cube-not-found' | 'unknown';
     code?: string;
     message?: string;
 };
@@ -1630,6 +1452,85 @@ type WriteWarningListener = (event: WriteWarningEvent) => void;
  * prevent. Identity only — it names no cache key.
  */
 declare function viewItemObjectName(item: any): string | undefined;
+/**
+ * The keys a personalization overlay row legitimately OWNS (objectui#5233).
+ *
+ * One per `persistViewPatch` call site in app-shell's `ObjectView` — the ONLY
+ * production writer of these rows — read off the tree rather than recalled:
+ * `rowHeight` (the density toggle, spec-canonical since #2890), `sort`,
+ * `hiddenFields`, `columnState` and `inlineEdit`. Nothing else in such a row
+ * is an opinion the user expressed; anything else it carries is a COPY of the
+ * source view as it stood at write time, because `persistViewPatch` USED TO
+ * send `{ ...baseViewDef, ...patch }` and this adapter persists what it is
+ * given.
+ *
+ * That copy was the defect the maintainer ruled on (objectstack#7494, comment
+ * 5261754173): an overlay written by a mere column drag froze the view's
+ * effective `filter` — and its `columns`, `label`, `type`, `isDefault` … — as
+ * of that moment, and because the display merge is `{ ...source, ...override }`
+ * the frozen copy SHADOWED the source view forever. An admin then edited the
+ * view's filter and every user who once resized a column kept the old one,
+ * with nothing anywhere reporting it.
+ *
+ * Both halves of that ruling have now landed, and this adapter's behaviour is
+ * unchanged by either — it still persists what it is given:
+ *
+ * - **read** (PR #5272, {@link narrowPersonalizationOverlay}): the consumer
+ *   that MERGES an overlay over a source view contributes only these keys, so
+ *   every already-stored fat row stops shadowing its source.
+ * - **write** (objectui#5233, `buildPersistedViewBody` in app-shell's
+ *   `ObjectView`, unblocked by `columnState`'s admission to the view-metadata
+ *   surface as a runtime-only overlay key — objectstack#9933, released in
+ *   `@objectstack/spec` 17.1.0): a *system view's* overlay is now written as
+ *   the patch alone, so no new row freezes anything, and because the write is
+ *   a whole-document PUT the next toggle also strips an old fat row. A *saved
+ *   view's* own row is deliberately still written whole — for it the body IS
+ *   the view, not a copy of one.
+ *
+ * A fat row is therefore a legacy shape, not a shape this product still
+ * produces; the list below is still what a reader is allowed to trust from one.
+ *
+ * ⛔ Do not grow this list to make some other key "stick" through an overlay.
+ * A key that belongs to the view belongs in the view; the overlay is a patch,
+ * and a patch that carries the whole document is what this list exists to
+ * stop. Adding a sixth entry is only correct alongside a sixth
+ * `persistViewPatch` call site — {@link narrowPersonalizationOverlay} is what
+ * a reader checks that against.
+ */
+declare const VIEW_OVERLAY_OWNED_KEYS: readonly ["rowHeight", "sort", "hiddenFields", "columnState", "inlineEdit"];
+/**
+ * Reduce a personalization overlay row to the keys it owns — the read-side
+ * half of objectui#5233, and the half that reaches rows ALREADY STORED.
+ *
+ * Rows written before this shipped carry the whole source view (see
+ * {@link VIEW_OVERLAY_OWNED_KEYS}). Of the three dispositions the issue names
+ * for them — strip on next write, migrate, tolerate on read — this is the
+ * third, chosen deliberately and stated here rather than left implicit,
+ * because it is the only one that is already true for every existing row the
+ * moment it ships: strip-on-next-write heals a row only when its user happens
+ * to touch that view again (and leaves the frozen filter live until then),
+ * and a migration needs a runner this product does not have for `sys_metadata`
+ * rows an operator may not even know exist. What the issue forbids is SILENT
+ * tolerance; this is the explicit, pinned kind (`viewOverlayPatchOnly.test.ts`
+ * in this package, `ObjectView.overlayPatchOnly.test.tsx` in app-shell).
+ *
+ * Applied by the consumer that MERGES an override over a source view
+ * (app-shell's `sanitizeViewOverride`, the one seam both of
+ * `loadViewOverrides`' read branches pass through), NOT by
+ * {@link ObjectStackAdapter.listViewOverrides} / {@link ObjectStackAdapter.getView}:
+ * those two answer with the stored DOCUMENT, their equality is itself pinned
+ * ("same key space, same document" — `listViewOverrides.test.ts`), and
+ * `InterfaceListPage` hydrates a hollow view out of that document. Narrowing
+ * belongs where a row is read AS A PATCH, not where it is read as a row.
+ *
+ * Non-overlay rows — a genuine saved view's own body, which the same batch
+ * read enumerates — are returned by REFERENCE, untouched: for those the row
+ * IS the view, and every key on it is an opinion its author expressed.
+ * Classification is {@link isPersonalizationOverlayRow}, the same predicate
+ * {@link ObjectStackAdapter.listViews} excludes rows by, so a row cannot be a
+ * saved view for one reader and an overlay for the other.
+ */
+declare function narrowPersonalizationOverlay<T>(row: T): T;
 
 /**
  * ObjectStack Data Source Adapter
@@ -2213,23 +2114,54 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      */
     getView(objectName: string, viewId: string): Promise<unknown | null>;
     /**
-     * Persist a view definition for an object.
-     *
-     * Symmetric counterpart to {@link getView}: writes the view to the
-     * server metadata store via `client.meta.saveItem`, then invalidates
-     * the matching cache entry so the next {@link getView} reflects the
-     * new payload. Returns the persisted item when the server echoes it,
-     * otherwise undefined.
-     *
-     * Used by ObjectView for "live" toolbar persistence (density,
-     * column widths, sort, etc.) and by the View Config Panel for
-     * explicit saves.
+     * Persist a toolbar-driven view config patch — density, column widths,
+     * sort, hidden columns, inline edit. Symmetric counterpart to
+     * {@link getView}: writes the row to the server metadata store via
+     * `client.meta.saveItem`, then invalidates the matching cache entry so the
+     * next {@link getView} reflects the new payload. Returns the persisted item
+     * when the server echoes it, otherwise undefined.
+     *
+     * Called from exactly ONE production site — `ObjectView`'s
+     * `persistViewPatch`, for the toolbar toggle — but that ONE call site
+     * fires for BOTH kinds of active tab: a code-defined **system** view (no
+     * row of its own yet) and a genuinely user-created **saved** view (already
+     * has a row — the toggle is editing ITS OWN definition, not laying an
+     * overlay on top of it). Which one a given call means is NOT re-derived
+     * here from the write's shape (objectui#4227's own lesson: shape inference
+     * on this namespace is exactly what let a system view masquerade as
+     * saved) — the caller already knows, via the same `isSavedViewId`
+     * classification that gates the switcher's readonly flag and its five
+     * mutating handlers, and passes it as {@link opts.isSavedView}.
+     *
+     * - `isSavedView` false/omitted (system-view target, the common case and
+     *   the default for backward compatibility): stamps
+     *   {@link VIEW_OVERLAY_MARKER} so {@link listViews} excludes the row —
+     *   the original objectui#4227 fix.
+     * - `isSavedView` true: the marker is withheld. Stamping it here would
+     *   flag the saved view's OWN row as a personalization overlay, and
+     *   `listViews()` would exclude it on the very next read — the user's own
+     *   view would vanish from the switcher the moment they toggled its
+     *   density (objectui#4227 follow-up, PM review on PR #4713, measured:
+     *   `persistViewPatch` has no gate on which kind of tab is active, and
+     *   this method writes to the exact same `(type='view', name=viewId)` key
+     *   {@link createView}/the ADR-0034 `viewEnvelope` seam already used for
+     *   that view, so the write is an upsert onto the saved view's row, not a
+     *   new one).
+     *
+     * Per objectstack#7494's ruling, the overlay this writes (system-view
+     * case) is ORG-WIDE shared view settings, not a per-user preference — a
+     * true per-user scope is a parked v18 direction on the platform side.
      *
      * @param objectName - Object name (e.g. 'lead')
      * @param viewId - View identifier (e.g. 'all_leads')
      * @param config - Full view definition to persist
+     * @param opts.isSavedView - Whether `viewId` already names a saved view
+     *   (vs. a system view being personalized for the first time). Omit /
+     *   `false` for the default overlay-marking behavior.
      */
-    updateViewConfig(objectName: string, viewId: string, config: Record<string, any>): Promise<Record<string, any> | void>;
+    updateViewConfig(objectName: string, viewId: string, config: Record<string, any>, opts?: {
+        isSavedView?: boolean;
+    }): Promise<Record<string, any> | void>;
     /**
      * List user-created views for a given object via the metadata overlay
      * API (ADR-0005). Replaces the legacy `find('sys_view', {...})` path
@@ -2403,8 +2335,13 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * Ask the by-name meta app route WHY an app is not in this session's app list
      * (objectui#4252).
      *
-     * `GET /api/v1/meta/apps` is filtered per session server-side
-     * (`filterAppForUser`), so an app withheld by `requiredPermissions` and an app
+     * The app LIST is the generic metadata list route `GET /api/v1/meta/:type`,
+     * requested with the singular type segment `app` — the same address this
+     * method appends a name to below, and the one `MetadataProvider` reads its
+     * items from. The server filters that list per session in `filterAppForUser`
+     * (`packages/rest/src/rest-server.ts`, applied inside the `:type` list handler
+     * once the type segment resolves to `app`), so an app withheld by
+     * `requiredPermissions` and an app
      * that does not exist are byte-identical there: both are simply absent. A
      * console reading only that list has one fact and two conditions, and it
      * renders its copy for the wrong one — "it may still be publishing" over a
@@ -2672,4 +2609,4 @@ declare function createObjectStackAdapter<T = unknown>(config: {
     reconnectDelay?: number;
 }): DataSource<T>;
 
-export { API_ACCESS_DENIED_CODES, APP_PERMISSION_DENIED_CODE, AnalyticsNotInstalledError, AnalyticsQueryRejectedError, type AppAccessVerdict, type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, ConcurrentUpdateError, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, DataApiValidationError, type DataMaskingConfig, type DataMaskingRule, type EmailIntegrationConfig, FILTER_OPERATOR_ALIASES, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, MalformedFilterError, type MetadataAuditEntry, type MetadataAuditResponse, type MetadataCacheStats, MetadataClient, type MetadataClientConfig, type MetadataClientSaveOptions, type MetadataDeleteOptions, type MetadataDiagnostics, type MetadataDiagnosticsEntry, type MetadataDiagnosticsOptions, type MetadataDiagnosticsSummary, type MetadataDraftHeader, type MetadataError, type MetadataGetOptions, type MetadataHistoryOptions, type MetadataLayered, type MetadataListOptions, MetadataNotFoundError, type MetadataReference, type MetadataSaveAdvisoryEvent, type MetadataSaveAdvisoryListener, type MetadataValidationIssue, ObjectStackAdapter, ObjectStackError, type ObjectStackUserStateAdapterOptions, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityManagerPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, type UserDataAdapter, type WebhookIntegrationConfig, type WriteWarningEvent, type WriteWarningListener, calculateAutoLayout, classifyAnalyticsFailure, clearSharedDiscoveryCache, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, createObjectStackUserStateAdapter, createQuietHttpLogger, formatHttpFailureMessage, generateContractManifest, getSharedDiscovery, is404Error, isAnalyticsNotInstalledError, isApiAccessDeniedError, isAppPermissionDeniedError, isConcurrentUpdateError, isErrorType, isMalformedFilterError, isObjectStackError, normaliseClientError, readSaveAdvisories, readTransactionalBatchCapability, serializeOrderBy, snapToGrid, validatePluginContract, viewItemObjectName };
+export { API_ACCESS_DENIED_CODES, APP_PERMISSION_DENIED_CODE, AnalyticsDatasetNotFoundError, AnalyticsNotInstalledError, AnalyticsQueryRejectedError, AnalyticsUnauthenticatedError, type AppAccessVerdict, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, ConcurrentUpdateError, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, DataApiValidationError, FILTER_OPERATOR_ALIASES, MalformedFilterError, type MetadataAuditEntry, type MetadataAuditResponse, type MetadataCacheStats, MetadataClient, type MetadataClientConfig, type MetadataClientSaveOptions, type MetadataDeleteOptions, type MetadataDiagnostics, type MetadataDiagnosticsEntry, type MetadataDiagnosticsOptions, type MetadataDiagnosticsSummary, type MetadataDraftHeader, type MetadataError, type MetadataGetOptions, type MetadataHistoryOptions, type MetadataLayered, type MetadataListOptions, type MetadataLockState, MetadataNotFoundError, type MetadataOverlayScope, type MetadataReference, type MetadataSaveAdvisoryEvent, type MetadataSaveAdvisoryListener, type MetadataValidationIssue, ObjectStackAdapter, ObjectStackError, type ObjectStackUserStateAdapterOptions, type UserDataAdapter, VIEW_OVERLAY_OWNED_KEYS, type WriteWarningEvent, type WriteWarningListener, classifyAnalyticsFailure, clearSharedDiscoveryCache, createErrorFromResponse, createObjectStackAdapter, createObjectStackUserStateAdapter, createQuietHttpLogger, formatHttpFailureMessage, getSharedDiscovery, is404Error, isAnalyticsNotInstalledError, isApiAccessDeniedError, isAppPermissionDeniedError, isConcurrentUpdateError, isErrorType, isMalformedFilterError, isObjectStackError, narrowPersonalizationOverlay, normaliseClientError, readSaveAdvisories, readTransactionalBatchCapability, serializeOrderBy, viewItemObjectName };