@object-ui/data-objectstack 17.3.0 → 17.5.0

package/dist/index.d.ts

@@ -1,8 +1,12 @@
 import { ObjectStackClient } from '@objectstack/client';
 import { DroppedFieldsEvent } from '@objectstack/spec/data';
 export { DroppedFieldsEvent } from '@objectstack/spec/data';
-import { DataSource, QueryParams, QueryResult, GlobalSearchResult, DataSourceMutationEvent, BatchTransactionOperation, ImportRequestOptions, ImportRecordsResult, CreateImportJobResult, ImportJobProgressInfo, ImportJobResultsInfo, ListImportJobsOptions, ImportJobSummaryInfo, ImportJobUndoResult, ExportDownloadRequest, FileUploadResult } from '@object-ui/types';
-export { FileUploadResult } from '@object-ui/types';
+import { 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';
+export { DeleteViewResult, FileUploadResult, ViewHomeDeleteOutcome } from '@object-ui/types';
+import { DatasetDrillRange } from '@object-ui/core';
 
 /**
  * ObjectUI
@@ -12,975 +16,971 @@ export { FileUploadResult } from '@object-ui/types';
  * LICENSE file in the root directory of this source tree.
  */
 /**
- * Base error class for all ObjectStack adapter errors
- */
-declare class ObjectStackError extends Error {
-    code: string;
-    statusCode?: number | undefined;
-    details?: Record<string, unknown> | undefined;
-    /**
-     * Create a new ObjectStackError
-     *
-     * @param message - Human-readable error message
-     * @param code - Unique error code for programmatic handling
-     * @param statusCode - Optional HTTP status code
-     * @param details - Optional additional error details for debugging
-     */
-    constructor(message: string, code: string, statusCode?: number | undefined, details?: Record<string, unknown> | undefined);
-    /**
-     * Convert error to JSON for logging/debugging
-     */
-    toJSON(): {
-        name: string;
-        message: string;
-        code: string;
-        statusCode: number | undefined;
-        details: Record<string, unknown> | undefined;
-        stack: string | undefined;
-    };
-}
-/**
- * Error thrown when requested metadata/schema is not found
+ * MetadataClient
+ *
+ * Thin, framework-agnostic HTTP client for the ObjectStack metadata
+ * API (`/api/v1/meta/*`). Used by the platform Setup app surfaces in
+ * `@object-ui/plugin-designer` (Object Manager, Field Designer, etc.)
+ * so they can read and write protocol metadata without depending on
+ * `ObjectStackAdapter` (which is a generic data-source binding and
+ * carries a lot of view/dashboard-specific behaviour we don't need
+ * here).
+ *
+ * Endpoints (see `packages/rest/src/rest-server.ts`):
+ *   GET    /api/v1/meta                  — list all metadata types
+ *   GET    /api/v1/meta/:type            — list items of a type
+ *   GET    /api/v1/meta/:type/:name      — get one item (returns the
+ *                                          unwrapped item content)
+ *   PUT    /api/v1/meta/:type/:name      — save (overlay) one item
+ *                                          honours `If-Match` for OCC
+ *   DELETE /api/v1/meta/:type/:name      — reset overlay to artifact
+ *   GET    /api/v1/meta/:type/:name/history — durable change log
+ *
+ * The client deliberately keeps the response shape opaque (typed as
+ * `unknown`/generic `T`) so callers explicitly narrow per-metadata-
+ * type, mirroring the framework's "single Zod source per type" rule.
  */
-declare class MetadataNotFoundError extends ObjectStackError {
-    constructor(objectName: string, details?: Record<string, unknown>);
-}
+
 /**
- * Error thrown when a bulk operation fails
+ * Emitted after a {@link MetadataClient.save} whose response carried a
+ * non-empty `advisories` array. The save SUCCEEDED — the row persisted and the
+ * server returned 200 — so this is advisory, never a failure.
+ *
+ * Deliberately the same shape of seam as `ObjectStackAdapter.onWriteWarning`
+ * (#3431/#3455): a successful write whose response carries something the author
+ * needs to be told, surfaced to the shell as an event so the data layer never
+ * imports a toaster. The difference is only which door produced it — that one
+ * is record CRUD, this one is the metadata save door.
  */
-declare class BulkOperationError extends ObjectStackError {
-    successCount: number;
-    failureCount: number;
-    errors: Array<{
-        index: number;
-        error: unknown;
-    }>;
-    /**
-     * Create a new BulkOperationError
-     *
-     * @param operation - The bulk operation that failed (create, update, delete)
-     * @param successCount - Number of successful operations
-     * @param failureCount - Number of failed operations
-     * @param errors - Array of individual errors
-     * @param details - Additional error details
-     */
-    constructor(operation: 'create' | 'update' | 'delete', successCount: number, failureCount: number, errors: Array<{
-        index: number;
-        error: unknown;
-    }>, details?: Record<string, unknown>);
+interface MetadataSaveAdvisoryEvent {
+    /** Metadata type saved (e.g. `'flow'`). */
+    type: string;
+    /** Item name saved. */
+    name: string;
     /**
-     * Get a summary of the bulk operation failure
+     * The save mode the call used. `'draft'` writes are **never gated** — the
+     * framework returns at `runtime-authoring-gate.ts`'s D1 early-return
+     * (`if (args.state !== 'active') return null`), so a draft save produces no
+     * findings at all and this event never fires for one. Carried anyway so a
+     * consumer reading the event can tell which door it came through.
      */
-    getSummary(): {
-        operation: string;
-        total: number;
-        successful: number;
-        failed: number;
-        failureRate: number;
-        errors: {
-            index: number;
-            error: unknown;
-        }[];
-    };
-}
-/**
- * Error thrown when connection to ObjectStack server fails
- */
-declare class ConnectionError extends ObjectStackError {
-    url?: string | undefined;
-    constructor(message: string, url?: string | undefined, details?: Record<string, unknown>, statusCode?: number);
-}
-/**
- * Error thrown when authentication fails
- */
-declare class AuthenticationError extends ObjectStackError {
-    constructor(message?: string, details?: Record<string, unknown>, statusCode?: number);
+    mode: 'draft' | 'publish';
+    /** The findings. Never empty — the event is not emitted otherwise. */
+    advisories: RuntimeAuthoringIssue[];
 }
+/** Event listener type for save-advisory events. */
+type MetadataSaveAdvisoryListener = (event: MetadataSaveAdvisoryEvent) => void;
 /**
- * Error thrown when the ObjectStack data API rejects a write as invalid.
- *
- * NOT the spec's `ValidationError` (`@objectstack/spec/kernel`), whose name this
- * class wore until objectui#3160 (objectstack#4115 ledger batch 6). That one is
- * a plain DATA SHAPE — `{ field, message, code? }`, one entry in a plugin
- * manifest's validation report — and `@object-ui/types` re-exports it under that
- * name. This is a runtime `Error` subclass carrying an HTTP status plus a list
- * of such entries, so the two are not even the same KIND of thing.
+ * Read the `advisories` array off a save response, defensively.
  *
- * The name follows the convention registered on objectstack#4115 for this
- * family — `<what was validated>Validation<Error|Result>`. `@object-ui/core`
- * took `SchemaNodeValidationError` for its SDUI-tree walk; this one belongs to
- * the data API.
+ * The server omits the key entirely on a clean save, so `undefined` is the
+ * common case and means "nothing to say". Anything that is not an array of
+ * objects carrying the six required keys is dropped rather than rendered: a
+ * half-shaped finding would print blanks at the author, and this channel must
+ * never turn a successful save into noise.
  */
-declare class DataApiValidationError extends ObjectStackError {
-    field?: string | undefined;
-    validationErrors?: Array<{
-        field: string;
-        message: string;
-    }> | undefined;
+declare function readSaveAdvisories(body: unknown): RuntimeAuthoringIssue[];
+interface MetadataClientConfig {
+    /** Base URL of the ObjectStack server (no trailing slash needed). */
+    baseUrl: string;
     /**
-     * Create a new DataApiValidationError
-     *
-     * @param message - Human-readable error message
-     * @param field - The field that failed validation (optional)
-     * @param validationErrors - Array of validation error details
-     * @param details - Additional error details
+     * Optional environment ID to scope reads/writes to a tenant. When
+     * provided, requests use the scoped path
+     * `/api/v1/environments/:environmentId/meta/...` and overlays are
+     * persisted in the environment's own metadata store.
      */
-    constructor(message: string, field?: string | undefined, validationErrors?: Array<{
-        field: string;
-        message: string;
-    }> | undefined, details?: Record<string, unknown>);
+    environmentId?: string;
+    /** Optional custom fetch implementation (defaults to `globalThis.fetch`). */
+    fetch?: typeof fetch;
+    /** Additional headers (e.g. auth) included on every request. */
+    headers?: Record<string, string>;
     /**
-     * Get all validation errors as a formatted list
+     * ADR-0037 Live Canvas — render the world **as-if-published**. When true,
+     * `list()` and `get()` append `?preview=draft`, which the framework
+     * dispatcher maps to `getMetaItems/getMetaItem({ previewDrafts: true })`:
+     * pending ADR-0033 drafts overlay the active registry (draft wins by name,
+     * draft-only items surface). Reads only — writes are unaffected, and
+     * nothing the preview shows is live until Publish.
      */
-    getValidationErrors(): {
-        field: string;
-        message: string;
-    }[];
+    previewDrafts?: boolean;
+    /**
+     * Called after a {@link MetadataClient.save} whose 2xx response carried a
+     * non-empty `advisories` array (objectstack#7435). The save already
+     * succeeded; this is how the shell learns there is something to tell the
+     * author instead of the findings being discarded client-side.
+     *
+     * Set on the CONFIG rather than exposed as a `subscribe()` method on purpose:
+     * console metadata clients are minted per-component by `useMetadataClient`,
+     * so there is no long-lived instance to subscribe to — but every one of them
+     * is built by the single `createConsoleMetadataClient` factory, which is
+     * where this gets wired exactly once for every save call site in the app.
+     *
+     * A throw from this callback is swallowed — an advisory channel must never
+     * be able to fail a save that the server already committed.
+     */
+    onSaveAdvisory?: MetadataSaveAdvisoryListener;
 }
-/**
- * Helper function to create an error from an HTTP response
- *
- * @param response - Response object or error from fetch/axios
- * @param context - Additional context for debugging
- * @returns Appropriate error instance
- */
-declare function createErrorFromResponse(response: Record<string, unknown>, context?: string): ObjectStackError;
-/**
- * Type guard to check if an error is an ObjectStackError
- */
-declare function isObjectStackError(error: unknown): error is ObjectStackError;
-/**
- * Type guard to check if an error is a specific ObjectStack error type
- */
-declare function isErrorType<T extends ObjectStackError>(error: unknown, errorClass: new (...args: any[]) => T): error is 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.
- */
-/**
- * Statistics reported by {@link MetadataCache.getStats} for monitoring.
- *
- * NOT the spec's `CacheStats` (`@objectstack/spec/contracts`), whose name this
- * interface wore until objectui#3160 (objectstack#4115 ledger batch 6). That one
- * describes the platform's `ICacheService` — a server-side KV cache measured by
- * `keyCount` and `memoryUsage`. This one describes the browser-side LRU in front
- * of `/api/v1/meta/*`: it is bounded (`size`/`maxSize`), it evicts, it coalesces
- * concurrent fetches onto one in-flight promise, and it reports a `hitRate`.
- * Neither type has a key the other has, so this is a name collision, not a
- * dialect — deriving would have replaced every field.
- */
-interface MetadataCacheStats {
-    size: number;
-    maxSize: number;
-    hits: number;
-    misses: number;
-    evictions: number;
-    /** Number of concurrent fetches that were coalesced onto an in-flight request. */
-    coalesced: number;
-    hitRate: number;
+interface MetadataListOptions {
+    /** Filter by source package id (matches the `package` query param). */
+    packageId?: string;
 }
-
-/**
- * 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.
- */
 /**
- * Cloud namespace integration for @objectstack/spec v3.0.0
- * Replaces the legacy Hub namespace for cloud deployment, hosting, and marketplace schemas.
+ * A pending DRAFT metadata item (ADR-0033), as returned by {@link MetadataClient.listDrafts}.
+ * Light header — no body — carrying the owning package so the console can group
+ * pending changes by app package.
  */
-interface CloudDeploymentConfig {
-    /** Target environment */
-    environment: 'development' | 'staging' | 'production';
-    /** Cloud region */
-    region?: string;
-    /** Auto-scaling configuration */
-    scaling?: {
-        minInstances: number;
-        maxInstances: number;
-        targetCPU?: number;
-    };
-    /** Environment variables */
-    envVars?: Record<string, string>;
-}
-interface CloudHostingConfig {
-    /** Custom domain */
-    customDomain?: string;
-    /** SSL configuration */
-    ssl?: {
-        enabled: boolean;
-        autoRenew: boolean;
-    };
-    /** CDN configuration */
-    cdn?: {
-        enabled: boolean;
-        regions?: string[];
-    };
-}
-interface CloudMarketplaceEntry {
-    /** Plugin or app ID */
-    id: string;
-    /** Display name */
+interface MetadataDraftHeader {
+    type: string;
     name: string;
-    /** Description */
-    description: string;
-    /** Version */
-    version: string;
-    /** Author */
-    author: string;
-    /** Category */
-    category: string;
-    /** Tags */
-    tags: string[];
-    /** Rating (1-5) */
-    rating?: number;
-    /** Install count */
-    installCount?: number;
-    /** Price (0 = free) */
-    price?: number;
+    packageId: string | null;
+    updatedAt: string | null;
+    updatedBy: string | null;
 }
 /**
- * Cloud operations helper for ObjectStack adapter.
- * Provides methods for cloud deployment, hosting, and marketplace operations.
+ * Options for {@link MetadataClient.save} — a WRITE OVER HTTP to
+ * `/api/v1/meta/:type/:name`.
+ *
+ * NOT the spec's `MetadataSaveOptions` (`@objectstack/spec/system` and
+ * `/kernel`), whose name this interface wore until objectui#3160
+ * (objectstack#4115 ledger batch 6). Both spec copies describe writing a
+ * 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.
  */
-declare class CloudOperations {
-    private getClient;
-    constructor(getClient: () => any);
+interface MetadataClientSaveOptions {
     /**
-     * Deploy an application to the cloud.
+     * Optimistic concurrency token (the `checksum` returned by the last
+     * read). When present, sent as the `If-Match` header so concurrent
+     * edits get a 409 instead of overwriting each other.
      */
-    deploy(appId: string, config: CloudDeploymentConfig): Promise<{
-        deploymentId: string;
-        status: string;
-    }>;
+    ifMatch?: string;
+    /** Optional actor id, sent as `X-Actor` for history attribution. */
+    actor?: string;
     /**
-     * Get deployment status.
-     */
-    getDeploymentStatus(deploymentId: string): Promise<{
-        status: string;
-        url?: string;
-    }>;
+     * Bypass destructive-change protection (Phase 3a). The server returns
+     * `409 destructive_change` with `issues[]` if a write would drop or
+     * narrow data; setting `force: true` adds `?force=true` to the request
+     * so the operator can confirm and proceed.
+     */
+    force?: boolean;
     /**
-     * Search marketplace entries.
+     * Save mode — `'draft'` writes a pending draft row (invisible to the
+     * runtime until `publish()` is called); `'publish'` writes directly
+     * to the active overlay. Omit (or set `'publish'`) for the legacy
+     * "save = live" behaviour.
      */
-    searchMarketplace(query?: string, category?: string): Promise<CloudMarketplaceEntry[]>;
+    mode?: 'draft' | 'publish';
     /**
-     * Install a marketplace plugin.
+     * Software-package id to bind the saved row to (sent as the `package`
+     * query param → `sys_metadata.package_id`). Set when authoring inside a
+     * Studio package workspace. Omit for an env-local overlay.
      */
-    installPlugin(pluginId: string): Promise<{
-        success: boolean;
-    }>;
+    packageId?: string;
+}
+interface MetadataGetOptions {
+    /**
+     * Read a specific overlay state. `'draft'` returns the pending draft
+     * body (no fallback to the published overlay or the registry); omit
+     * to read the active (published) value.
+     */
+    state?: 'active' | 'draft';
+    /**
+     * Software-package id to scope resolution (sent as the `package` query
+     * param → server prefer-local, ADR-0048). Set when reading one item that
+     * may collide by name across installed packages (e.g. the Studio editor
+     * passes the edited item's owning package). Omit for context-free reads.
+     */
+    packageId?: string;
+}
+interface MetadataDeleteOptions extends MetadataClientSaveOptions {
+    /**
+     * Target state. `'draft'` discards the pending draft (keeps the
+     * published overlay intact). Omit to reset the active overlay back
+     * to the artifact default (the legacy behaviour).
+     */
+    state?: 'active' | 'draft';
+}
+/** Layered view of a metadata item — Phase 3a `?layers=true`. */
+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;
+    /** Merged effective view — what the runtime actually sees. */
+    effective: T | null;
+    /**
+     * Load-time validation result for `effective` (server-computed via
+     * the same Zod registry used at save time). Undefined for types
+     * without a registered Zod schema. Surfaced by the Studio as a
+     * banner + inline field errors so operators can spot bad metadata
+     * without having to hit Save.
+     */
+    _diagnostics?: MetadataDiagnostics;
+    /** 4-state lock: `none` / `no-overlay` / `no-delete` / `full`. */
+    lock?: 'none' | 'no-overlay' | 'no-delete' | 'full';
+    /** Human-readable reason for the lock (tooltip text). */
+    lockReason?: string;
+    /** Which layer set the lock: artifact / package / overlay / env-forced. */
+    lockSource?: 'artifact' | 'package' | 'overlay' | 'env-forced';
+    /** Optional docs URL for the lock reason (rendered as "View docs →"). */
+    lockDocsUrl?: string;
+    /** Origin of the item: `package` (loader) | `org` (tenant) | `env-forced`. */
+    provenance?: 'package' | 'org' | 'env-forced';
+    /** Owning package id (denormalised from the loader tag). */
+    packageId?: string;
+    /** Owning package version. */
+    packageVersion?: string;
+    /** True when the editor should allow Save (PUT). */
+    editable?: boolean;
+    /** True when the editor should allow Delete. */
+    deletable?: boolean;
+    /** True when "Reset to package default" applies (has overlay + artifact). */
+    resettable?: boolean;
 }
-
 /**
- * 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.
+ * One row in the metadata protection-audit trail
+ * (ADR-0010 §3.6 / Phase 4.1). Mirrors `sys_metadata_audit` columns
+ * the API exposes.
  */
+interface MetadataAuditEntry {
+    /** Stable audit-row id (uuid). */
+    id: unknown;
+    /** ISO timestamp when the attempt happened. */
+    occurredAt: string;
+    /** Who attempted the operation (`x-actor` header or `'system'`). */
+    actor: string;
+    /** Code path that recorded the row (e.g. `protocol.saveMetaItem`). */
+    source: string | null;
+    /** Which lifecycle op was attempted. */
+    operation: 'save' | 'publish' | 'rollback' | 'delete' | 'reset';
+    /** Decision: allowed / denied / forced (admin override). */
+    outcome: 'allowed' | 'denied' | 'forced';
+    /** 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;
+    /** True when admin forced the write through despite the lock. */
+    lockOverridden: boolean;
+    /** Request-id for trace correlation (if propagated). */
+    requestId: string | null;
+    /** Free-text note (often the lock reason). */
+    note: string | null;
+}
+/** Response shape for `MetadataClient.audit()`. */
+interface MetadataAuditResponse {
+    events: MetadataAuditEntry[];
+}
 /**
- * Contracts module integration for @objectstack/spec v3.0.0
- * Provides plugin contract validation and marketplace publishing utilities.
+ * Load-time validation envelope attached to metadata items by the
+ * framework. Mirrors `MetadataValidationResult` in the kernel spec.
  */
-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 MetadataDiagnostics {
+    valid: boolean;
+    errors?: Array<{
+        path: string;
+        message: string;
+        code?: string;
+    }>;
+    warnings?: Array<{
+        path: string;
+        message: string;
+    }>;
 }
-interface PluginExport {
-    /** Export name */
+/** Options for the cross-type `/meta/diagnostics` sweep call. */
+interface MetadataDiagnosticsOptions {
+    /** Restrict the sweep to a single metadata type (e.g. `'view'`). */
+    type?: string;
+    /**
+     * `'error'` (default) returns only items that fail validation.
+     * `'warning'` also includes items whose only diagnostics are warnings.
+     */
+    severity?: 'error' | 'warning';
+    /** Restrict to items owned by this package id. */
+    packageId?: string;
+}
+/** One row in the `/meta/diagnostics` response. */
+interface MetadataDiagnosticsEntry {
+    type: string;
     name: string;
-    /** Export type */
-    type: 'component' | 'hook' | 'utility' | 'provider';
-    /** Description */
-    description?: string;
+    diagnostics: MetadataDiagnostics;
 }
-interface PluginAPIContract {
-    /** Consumed data sources */
-    dataSources?: string[];
-    /** Required object schemas */
-    requiredSchemas?: string[];
-    /** Event subscriptions */
-    events?: string[];
+/** Top-level envelope returned by `/meta/diagnostics`. */
+interface MetadataDiagnosticsSummary {
+    entries: MetadataDiagnosticsEntry[];
+    /** Number of `entries` returned (post-filter). */
+    total: number;
+    /** How many metadata types the sweep visited. */
+    scannedTypes: number;
+    /** How many individual items were validated. */
+    scannedItems: number;
+    /**
+     * Per-type aggregate stats — count of items and the list of
+     * packages contributing to each type. Computed in the same sweep
+     * so a single call serves both the diagnostics governance page and
+     * the directory tile counts / package filter.
+     *
+     * Optional for backward compatibility with older framework
+     * versions that do not yet emit it; clients should fall back to
+     * an empty record.
+     */
+    stats?: Record<string, {
+        count: number;
+        locked?: number;
+        packages: string[];
+    }>;
 }
-interface ContractValidationResult {
-    valid: boolean;
-    errors: ContractValidationError[];
-    warnings: string[];
+/** Reference back-pointer — Phase 3a `/references`. */
+interface MetadataReference {
+    /** Referencing item's metadata type. */
+    fromType: string;
+    /** Referencing item's name. */
+    fromName: string;
+    /** JSON path within the referencing item that holds the reference. */
+    path: string;
+    /** The actual value seen at `path` (the referenced name). */
+    value: string;
 }
-interface ContractValidationError {
-    field: string;
+interface MetadataHistoryOptions {
+    /** Only return events after this sequence number. */
+    sinceSeq?: number;
+    /** Limit the number of events returned. */
+    limit?: number;
+}
+/** A single field-anchored spec-validation issue (server `error.details.issues`). */
+interface MetadataValidationIssue {
+    /** Dot-path to the offending field, e.g. `fields.amount.type` (`''` = root). */
+    path: string;
     message: string;
-    code: string;
+    code?: string;
+}
+interface MetadataError extends Error {
+    status: number;
+    code?: string;
+    body?: unknown;
+    /** Structured spec-validation issues, when the failure was a validation error. */
+    issues?: MetadataValidationIssue[];
 }
 /**
- * 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.
- *
- * Persists arbitrary per-user UI state (favorites, recently-accessed items, …)
- * as a single JSON blob per `(user_id, key)` row in the **unified per-user
- * KV store** — the `sys_user_preference` object shipped by every
- * `@objectstack/plugin-auth`-enabled environment.
- *
- * Using the existing `sys_user_preference` table (rather than a parallel
- * `user_app_state` table) keeps things consistent with the platform's
- * "one KV store per scope" pattern:
- *
- *   - `sys_setting`         ← tenant / env scope
- *   - `sys_user_preference` ← per-user scope  ← we live here
+ * MetadataClient — read/write protocol metadata via the framework REST API.
  *
- * Callers are encouraged to namespace their keys (e.g. `ui.favorites`,
- * `ui.recent`, `ui.grid.account.state`) so explicit settings (`theme`,
- * `locale`) and machine-written UI traces stay easy to tell apart.
- *
- * ## Schema this adapter expects
- *
- * The canonical `sys_user_preference` schema (from
- * `@objectstack/platform-objects`):
- *
- * ```yaml
- * object: sys_user_preference
- * fields:
- *   user_id:    lookup(sys_user)  # indexed
- *   key:        string            # indexed  (e.g. "ui.favorites")
- *   value:      json              # the serialised list
- *   updated_at: datetime          # auto-managed
- * unique: [user_id, key]
+ * @example
+ * ```ts
+ * const client = new MetadataClient({ baseUrl: 'http://localhost:3000' });
+ * const objects = await client.list<{ name: string; label?: string }>('object');
+ * const account = await client.get<{ fields: Record<string, unknown> }>('object', 'account');
+ * await client.save('object', 'account', { ...account, label: 'Customer' });
  * ```
- *
- * ## Failure modes
- *
- * The adapter is designed to **degrade silently**. Any error — missing
- * schema, 4xx/5xx, network — is caught:
- *
- * - `load()` returns `[]`, so the hosting provider keeps its localStorage state.
- * - `save()` resolves without throwing, so UI mutations never surface a toast.
- *
- * As soon as the backend supports `sys_user_preference`, persistence
- * "lights up" with no code change.
- *
- * @module
  */
-
-interface ObjectStackUserStateAdapterOptions {
-    /** Connected data source (usually the one provided by `<AdapterProvider>`). */
-    dataSource: DataSource<any>;
-    /** Authenticated user id. */
-    userId: string;
+declare class MetadataClient {
+    private readonly base;
+    private readonly fetchImpl;
+    private readonly headers;
+    /** ADR-0037: when true, reads render the draft-overlaid world. */
+    readonly previewDrafts: boolean;
+    /** #4133 — sink for post-save advisory findings; see the config field. */
+    private readonly onSaveAdvisory;
+    constructor(config: MetadataClientConfig);
+    /** Update the client's environment scope at runtime. */
+    withEnvironment(environmentId: string | undefined): MetadataClient;
     /**
-     * Storage key. Should be a dotted, namespaced string so UI traces
-     * don't collide with user-facing preferences. Examples:
-     * `ui.favorites`, `ui.recent`, `ui.grid.account.state`.
+     * Derive a client whose reads render the draft-overlaid world (or not).
+     * Same base/fetch/headers; used by the app-shell to switch the whole
+     * renderer tree into ADR-0037 preview mode off one URL flag.
      */
-    key: string;
-    /** Override the storage object name. Defaults to `"sys_user_preference"`. */
-    resource?: string;
+    withPreviewDrafts(previewDrafts: boolean): MetadataClient;
+    /** List all registered metadata types (returns the registry rows). */
+    listTypes(): Promise<unknown[]>;
+    /** List items of a metadata type (e.g. `object`, `field`, `view`). */
+    list<T = unknown>(type: string, options?: MetadataListOptions): Promise<T[]>;
     /**
-     * Optional console logger for development diagnostics. Defaults to noop so
-     * production builds stay quiet.
+     * List pending DRAFT items (ADR-0033) — what an AI authored but nobody
+     * published yet. `list()` only sees published/active metadata, so a
+     * just-built app package looks empty there; this surfaces the drafts so the
+     * console can show a "pending changes" view and draft-aware package contents.
+     * Optionally narrow by `packageId` and/or `type`. Returns light headers
+     * (no body) carrying `packageId` for grouping.
      */
-    onError?: (where: 'load' | 'save', error: unknown) => void;
-}
-interface UserDataAdapter<T> {
-    load(): Promise<T[]>;
-    save(items: T[]): Promise<void>;
-}
-/**
- * Build a `UserDataAdapter<T>` backed by ObjectStack.
- *
- * Each adapter instance is bound to a single `(user, key)` pair; create
- * one per slot you want to persist.
- */
-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;
+    listDrafts(options?: {
+        packageId?: string;
+        type?: string;
+    }): Promise<MetadataDraftHeader[]>;
     /**
-     * Register a new integration.
+     * Fetch a single metadata item and return the response body EXACTLY as the
+     * server sent it — envelope and all.
+     *
+     * The one transport both {@link get} (which unwraps) and {@link getDraft}
+     * (which does not) sit on, so the two can differ in what they hand back
+     * without differing in how they ask. Private on purpose: the envelope is a
+     * wire detail, and the two published contracts above are the supported ways
+     * to read an item.
      */
-    register(id: string, config: IntegrationConfig): void;
+    private readItemResponse;
     /**
-     * Remove an integration.
+     * Get a single metadata item. Returns the unwrapped item CONTENT — the
+     * metadata document itself, so `obj.fields` / `obj.label` are reachable
+     * directly.
+     *
+     * The framework answers `GET /meta/:type/:name` with the spec-declared
+     * envelope `{ type, name, item, …protection fields }`
+     * (`GetMetaItemResponseSchema`; objectstack#5563 collapsed this read to that
+     * ONE shape), so the envelope is unwrapped here — at the client boundary,
+     * once — rather than by each caller.
+     *
+     * **This method used to return the envelope while promising the body**
+     * (objectui#4271). Nothing detected the disagreement, because the test
+     * doubles across the repo were written against this docblock: every consumer
+     * reading `obj.fields` got `undefined` in production and a field list in
+     * unit tests. The visible cost was the entire field half of the permission
+     * matrix reporting "No fields registered for this object." for every object,
+     * plus dead RLS CEL autocomplete, an inert report drill-down and a designer
+     * that saved the envelope back over the object body.
+     *
+     * A response that is NOT the envelope (an older server answering the bare
+     * document, or a body of its own shape) passes through untouched, and `null`
+     * still comes back on 404 to keep the call site ergonomic.
      */
-    unregister(id: string): void;
+    get<T = unknown>(type: string, name: string, options?: MetadataGetOptions): Promise<T | null>;
     /**
-     * Get all registered integrations.
+     * Read the pending draft body for an item (`?state=draft`). Returns
+     * `null` when there is no draft pending. Draft reads do NOT fall
+     * back to the published overlay or the artifact registry — a `null`
+     * unambiguously means "nothing to publish".
+     *
+     * Note: this method hands back the `{ type, name, item }` envelope the
+     * framework sends, NOT the body — callers read `.item`. That asymmetry with
+     * {@link get} is deliberate and long-standing (the draft envelope's identity
+     * and protection carriers are part of what a draft reader inspects), so it
+     * is preserved by reading the transport directly instead of going through
+     * `get()`'s unwrap. `unwrapDraftBody` (app-shell) and `unwrapViewDraft`
+     * (this package) are the shared helpers for taking the body out.
      */
-    getAll(): Map<string, IntegrationConfig>;
+    getDraft<T = unknown>(type: string, name: string, options?: {
+        packageId?: string;
+    }): Promise<T | null>;
     /**
-     * Get integrations that match a specific event.
+     * Save (PUT) a metadata item. The framework accepts both the bare
+     * item payload and the `{ item: ... }` / `{ metadata: ... }`
+     * envelopes; we send bare for consistency. Pass `mode: 'draft'` to
+     * stage the change without publishing (Studio's "Save" button).
      */
-    getForEvent(event: string): IntegrationConfig[];
+    save<T = unknown>(type: string, name: string, item: unknown, options?: MetadataClientSaveOptions): Promise<T>;
     /**
-     * Dispatch an event to all matching integrations.
-     * Returns results for each integration.
+     * Publish a single pending draft BY REFERENCE — promotes the draft row for
+     * `(type, name)` into the active overlay and drops the draft. Works for ANY
+     * draft, including ones with no `packageId` binding (which the package-scoped
+     * `/packages/:id/publish-drafts` flow cannot reach). Use this to publish the
+     * exact set returned by {@link listDrafts} without needing a package.
+     *
+     * Returns the server result. For `seed` drafts the protocol also materializes
+     * the rows and reports under `seedApplied` — a data problem never fails the
+     * publish, so callers should check `seedApplied?.success` and warn the user
+     * rather than assume the data went live.
      */
-    dispatch(event: string, payload: Record<string, unknown>): Promise<Array<{
-        id: string;
-        success: boolean;
-        error?: string;
-    }>>;
+    publishDraft(type: string, name: string): Promise<{
+        success?: boolean;
+        seedApplied?: {
+            success: boolean;
+            inserted?: number;
+            updated?: number;
+            error?: string;
+            errors?: unknown[];
+        };
+    } & Record<string, unknown>>;
     /**
-     * Send payload to a specific integration.
+     * 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).
      */
-    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.
- */
-/**
- * MetadataClient
- *
- * Thin, framework-agnostic HTTP client for the ObjectStack metadata
- * API (`/api/v1/meta/*`). Used by the platform Setup app surfaces in
- * `@object-ui/plugin-designer` (Object Manager, Field Designer, etc.)
- * so they can read and write protocol metadata without depending on
- * `ObjectStackAdapter` (which is a generic data-source binding and
- * carries a lot of view/dashboard-specific behaviour we don't need
- * here).
- *
- * Endpoints (see `packages/rest/src/rest-server.ts`):
- *   GET    /api/v1/meta                  — list all metadata types
- *   GET    /api/v1/meta/:type            — list items of a type
- *   GET    /api/v1/meta/:type/:name      — get one item (returns the
- *                                          unwrapped item content)
- *   PUT    /api/v1/meta/:type/:name      — save (overlay) one item
- *                                          honours `If-Match` for OCC
- *   DELETE /api/v1/meta/:type/:name      — reset overlay to artifact
- *   GET    /api/v1/meta/:type/:name/history — durable change log
- *
- * The client deliberately keeps the response shape opaque (typed as
- * `unknown`/generic `T`) so callers explicitly narrow per-metadata-
- * type, mirroring the framework's "single Zod source per type" rule.
- */
-interface MetadataClientConfig {
-    /** Base URL of the ObjectStack server (no trailing slash needed). */
-    baseUrl: string;
+    layered<T = unknown>(type: string, name: string, options?: {
+        packageId?: string;
+    }): Promise<MetadataLayered<T>>;
     /**
-     * Optional environment ID to scope reads/writes to a tenant. When
-     * provided, requests use the scoped path
-     * `/api/v1/environments/:environmentId/meta/...` and overlays are
-     * persisted in the environment's own metadata store.
-     */
-    environmentId?: string;
-    /** Optional custom fetch implementation (defaults to `globalThis.fetch`). */
-    fetch?: typeof fetch;
-    /** Additional headers (e.g. auth) included on every request. */
-    headers?: Record<string, string>;
-    /**
-     * ADR-0037 Live Canvas — render the world **as-if-published**. When true,
-     * `list()` and `get()` append `?preview=draft`, which the framework
-     * dispatcher maps to `getMetaItems/getMetaItem({ previewDrafts: true })`:
-     * pending ADR-0033 drafts overlay the active registry (draft wins by name,
-     * draft-only items surface). Reads only — writes are unaffected, and
-     * nothing the preview shows is live until Publish.
+     * Cross-type sweep of load-time validation results — calls
+     * `GET /meta/diagnostics`. Returns every entry the framework
+     * considers invalid (or, when `severity: 'warning'`, also entries
+     * with only warnings).
+     *
+     * Used by the Studio's governance overview page and by the
+     * directory page to show "N invalid" badges per metadata type.
      */
-    previewDrafts?: boolean;
-}
-interface MetadataListOptions {
-    /** Filter by source package id (matches the `package` query param). */
-    packageId?: string;
-}
-/**
- * A pending DRAFT metadata item (ADR-0033), as returned by {@link MetadataClient.listDrafts}.
- * Light header — no body — carrying the owning package so the console can group
- * pending changes by app package.
- */
-interface MetadataDraftHeader {
-    type: string;
-    name: string;
-    packageId: string | null;
-    updatedAt: string | null;
-    updatedBy: string | null;
-}
-/**
- * Options for {@link MetadataClient.save} — a WRITE OVER HTTP to
- * `/api/v1/meta/:type/:name`.
- *
- * NOT the spec's `MetadataSaveOptions` (`@objectstack/spec/system` and
- * `/kernel`), whose name this interface wore until objectui#3160
- * (objectstack#4115 ledger batch 6). Both spec copies describe writing a
- * 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.
- */
-interface MetadataClientSaveOptions {
+    diagnostics(options?: MetadataDiagnosticsOptions): Promise<MetadataDiagnosticsSummary>;
     /**
-     * Optimistic concurrency token (the `checksum` returned by the last
-     * read). When present, sent as the `If-Match` header so concurrent
-     * edits get a 409 instead of overwriting each other.
+     * Find every metadata item that references this one (Phase 3a). Useful
+     * for pre-delete impact analysis: "Are any views pointing at this
+     * object before I drop it?".
      */
-    ifMatch?: string;
-    /** Optional actor id, sent as `X-Actor` for history attribution. */
-    actor?: string;
+    references(type: string, name: string): Promise<MetadataReference[]>;
     /**
-     * Bypass destructive-change protection (Phase 3a). The server returns
-     * `409 destructive_change` with `issues[]` if a write would drop or
-     * narrow data; setting `force: true` adds `?force=true` to the request
-     * so the operator can confirm and proceed.
+     * Reset a metadata customization overlay back to the artifact default.
+     * Idempotent: returns the result even when no overlay row existed.
+     * Pass `state: 'draft'` to discard the pending draft only (keeps the
+     * published overlay intact) — useful for a Studio "Discard draft" button.
      */
-    force?: boolean;
+    reset<T = unknown>(type: string, name: string, options?: MetadataDeleteOptions): Promise<T>;
     /**
-     * Save mode — `'draft'` writes a pending draft row (invisible to the
-     * runtime until `publish()` is called); `'publish'` writes directly
-     * to the active overlay. Omit (or set `'publish'`) for the legacy
-     * "save = live" behaviour.
+     * Promote the pending draft of an item to the active overlay
+     * (POST `/meta/:type/:name/publish`). Returns
+     * `{ success, version, seq, message }`. Throws a `404 no_draft` if
+     * nothing is pending and `409 metadata_conflict` if the published
+     * overlay moved while the draft was sitting.
      */
-    mode?: 'draft' | 'publish';
+    publish<T = unknown>(type: string, name: string, options?: {
+        actor?: string;
+        message?: string;
+    }): Promise<T>;
     /**
-     * Software-package id to bind the saved row to (sent as the `package`
-     * query param → `sys_metadata.package_id`). Set when authoring inside a
-     * Studio package workspace. Omit for an env-local overlay.
+     * Restore an item to a previous version (POST `/meta/:type/:name/rollback`).
+     * The server reads the history row at `toVersion`, writes its body back
+     * as the active overlay with `operation_type='revert'`. Returns
+     * `{ success, version, seq, restoredFromVersion, message }`. Throws
+     * `404 version_not_found` for unknown versions and `409 version_not_restorable`
+     * when the target version is a delete tombstone.
      */
-    packageId?: string;
-}
-interface MetadataGetOptions {
+    rollback<T = unknown>(type: string, name: string, toVersion: number, options?: {
+        actor?: string;
+        message?: string;
+    }): Promise<T>;
     /**
-     * Read a specific overlay state. `'draft'` returns the pending draft
-     * body (no fallback to the published overlay or the registry); omit
-     * to read the active (published) value.
+     * Compute a structured top-level key diff between two history versions
+     * (GET `/meta/:type/:name/diff?from=&to=`). Returns
+     * `{ added, removed, changed }` where each entry carries a `path` and
+     * the relevant value(s). Useful for "what changed in this draft?" and
+     * pre-rollback previews.
      */
-    state?: 'active' | 'draft';
+    diff<T = unknown>(type: string, name: string, fromVersion?: number, toVersion?: number): Promise<T>;
+    /** Fetch the durable history (change log) for one metadata item. */
+    history<T = unknown>(type: string, name: string, options?: MetadataHistoryOptions): Promise<T>;
     /**
-     * Software-package id to scope resolution (sent as the `package` query
-     * param → server prefer-local, ADR-0048). Set when reading one item that
-     * may collide by name across installed packages (e.g. the Studio editor
-     * passes the edited item's owning package). Omit for context-free reads.
+     * Fetch the protection-audit trail for one metadata item
+     * (ADR-0010 §3.6 / Phase 4.1). Shows every save/publish/rollback/
+     * delete/reset attempt — allowed, denied, or forced — so the
+     * Studio "审计日志 / Audit log" tab can render who tried what
+     * and whether a lock blocked it.
      */
-    packageId?: string;
+    audit(type: string, name: string, options?: {
+        limit?: number;
+    }): Promise<MetadataAuditResponse>;
 }
-interface MetadataDeleteOptions extends MetadataClientSaveOptions {
+
+/**
+ * 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.
+ */
+/**
+ * Base error class for all ObjectStack adapter errors
+ */
+declare class ObjectStackError extends Error {
+    code: string;
+    statusCode?: number | undefined;
+    details?: Record<string, unknown> | undefined;
     /**
-     * Target state. `'draft'` discards the pending draft (keeps the
-     * published overlay intact). Omit to reset the active overlay back
-     * to the artifact default (the legacy behaviour).
+     * Create a new ObjectStackError
+     *
+     * @param message - Human-readable error message
+     * @param code - Unique error code for programmatic handling
+     * @param statusCode - Optional HTTP status code
+     * @param details - Optional additional error details for debugging
      */
-    state?: 'active' | 'draft';
-}
-/** Layered view of a metadata item — Phase 3a `?layers=true`. */
-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;
-    /** Merged effective view — what the runtime actually sees. */
-    effective: T | null;
+    constructor(message: string, code: string, statusCode?: number | undefined, details?: Record<string, unknown> | undefined);
     /**
-     * Load-time validation result for `effective` (server-computed via
-     * the same Zod registry used at save time). Undefined for types
-     * without a registered Zod schema. Surfaced by the Studio as a
-     * banner + inline field errors so operators can spot bad metadata
-     * without having to hit Save.
+     * Convert error to JSON for logging/debugging
      */
-    _diagnostics?: MetadataDiagnostics;
-    /** 4-state lock: `none` / `no-overlay` / `no-delete` / `full`. */
-    lock?: 'none' | 'no-overlay' | 'no-delete' | 'full';
-    /** Human-readable reason for the lock (tooltip text). */
-    lockReason?: string;
-    /** Which layer set the lock: artifact / package / overlay / env-forced. */
-    lockSource?: 'artifact' | 'package' | 'overlay' | 'env-forced';
-    /** Optional docs URL for the lock reason (rendered as "View docs →"). */
-    lockDocsUrl?: string;
-    /** Origin of the item: `package` (loader) | `org` (tenant) | `env-forced`. */
-    provenance?: 'package' | 'org' | 'env-forced';
-    /** Owning package id (denormalised from the loader tag). */
-    packageId?: string;
-    /** Owning package version. */
-    packageVersion?: string;
-    /** True when the editor should allow Save (PUT). */
-    editable?: boolean;
-    /** True when the editor should allow Delete. */
-    deletable?: boolean;
-    /** True when "Reset to package default" applies (has overlay + artifact). */
-    resettable?: boolean;
+    toJSON(): {
+        name: string;
+        message: string;
+        code: string;
+        statusCode: number | undefined;
+        details: Record<string, unknown> | undefined;
+        stack: string | undefined;
+    };
 }
 /**
- * One row in the metadata protection-audit trail
- * (ADR-0010 §3.6 / Phase 4.1). Mirrors `sys_metadata_audit` columns
- * the API exposes.
+ * Error thrown when requested metadata/schema is not found
  */
-interface MetadataAuditEntry {
-    /** Stable audit-row id (uuid). */
-    id: unknown;
-    /** ISO timestamp when the attempt happened. */
-    occurredAt: string;
-    /** Who attempted the operation (`x-actor` header or `'system'`). */
-    actor: string;
-    /** Code path that recorded the row (e.g. `protocol.saveMetaItem`). */
-    source: string | null;
-    /** Which lifecycle op was attempted. */
-    operation: 'save' | 'publish' | 'rollback' | 'delete' | 'reset';
-    /** Decision: allowed / denied / forced (admin override). */
-    outcome: 'allowed' | 'denied' | 'forced';
-    /** 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;
-    /** True when admin forced the write through despite the lock. */
-    lockOverridden: boolean;
-    /** Request-id for trace correlation (if propagated). */
-    requestId: string | null;
-    /** Free-text note (often the lock reason). */
-    note: string | null;
-}
-/** Response shape for `MetadataClient.audit()`. */
-interface MetadataAuditResponse {
-    events: MetadataAuditEntry[];
+declare class MetadataNotFoundError extends ObjectStackError {
+    constructor(objectName: string, details?: Record<string, unknown>);
 }
 /**
- * Load-time validation envelope attached to metadata items by the
- * framework. Mirrors `MetadataValidationResult` in the kernel spec.
+ * Error thrown when a bulk operation fails
  */
-interface MetadataDiagnostics {
-    valid: boolean;
-    errors?: Array<{
-        path: string;
-        message: string;
-        code?: string;
+declare class BulkOperationError extends ObjectStackError {
+    successCount: number;
+    failureCount: number;
+    errors: Array<{
+        index: number;
+        error: unknown;
     }>;
-    warnings?: Array<{
-        path: string;
-        message: string;
-    }>;
-}
-/** Options for the cross-type `/meta/diagnostics` sweep call. */
-interface MetadataDiagnosticsOptions {
-    /** Restrict the sweep to a single metadata type (e.g. `'view'`). */
-    type?: string;
     /**
-     * `'error'` (default) returns only items that fail validation.
-     * `'warning'` also includes items whose only diagnostics are warnings.
+     * Create a new BulkOperationError
+     *
+     * @param operation - The bulk operation that failed (create, update, delete)
+     * @param successCount - Number of successful operations
+     * @param failureCount - Number of failed operations
+     * @param errors - Array of individual errors
+     * @param details - Additional error details
      */
-    severity?: 'error' | 'warning';
-    /** Restrict to items owned by this package id. */
-    packageId?: string;
+    constructor(operation: 'create' | 'update' | 'delete', successCount: number, failureCount: number, errors: Array<{
+        index: number;
+        error: unknown;
+    }>, details?: Record<string, unknown>);
+    /**
+     * Get a summary of the bulk operation failure
+     */
+    getSummary(): {
+        operation: string;
+        total: number;
+        successful: number;
+        failed: number;
+        failureRate: number;
+        errors: {
+            index: number;
+            error: unknown;
+        }[];
+    };
 }
-/** One row in the `/meta/diagnostics` response. */
-interface MetadataDiagnosticsEntry {
-    type: string;
-    name: string;
-    diagnostics: MetadataDiagnostics;
+/**
+ * Error thrown when connection to ObjectStack server fails
+ */
+declare class ConnectionError extends ObjectStackError {
+    url?: string | undefined;
+    constructor(message: string, url?: string | undefined, details?: Record<string, unknown>, statusCode?: number);
 }
-/** Top-level envelope returned by `/meta/diagnostics`. */
-interface MetadataDiagnosticsSummary {
-    entries: MetadataDiagnosticsEntry[];
-    /** Number of `entries` returned (post-filter). */
-    total: number;
-    /** How many metadata types the sweep visited. */
-    scannedTypes: number;
-    /** How many individual items were validated. */
-    scannedItems: number;
+/**
+ * Error thrown when authentication fails
+ */
+declare class AuthenticationError extends ObjectStackError {
+    constructor(message?: string, details?: Record<string, unknown>, statusCode?: number);
+}
+/**
+ * Error thrown when the ObjectStack data API rejects a write as invalid.
+ *
+ * NOT the spec's `ValidationError` (`@objectstack/spec/kernel`), whose name this
+ * class wore until objectui#3160 (objectstack#4115 ledger batch 6). That one is
+ * a plain DATA SHAPE — `{ field, message, code? }`, one entry in a plugin
+ * manifest's validation report — and `@object-ui/types` re-exports it under that
+ * name. This is a runtime `Error` subclass carrying an HTTP status plus a list
+ * of such entries, so the two are not even the same KIND of thing.
+ *
+ * The name follows the convention registered on objectstack#4115 for this
+ * family — `<what was validated>Validation<Error|Result>`. `@object-ui/core`
+ * took `SchemaNodeValidationError` for its SDUI-tree walk; this one belongs to
+ * the data API.
+ */
+declare class DataApiValidationError extends ObjectStackError {
+    field?: string | undefined;
+    validationErrors?: Array<{
+        field: string;
+        message: string;
+    }> | undefined;
     /**
-     * Per-type aggregate stats — count of items and the list of
-     * packages contributing to each type. Computed in the same sweep
-     * so a single call serves both the diagnostics governance page and
-     * the directory tile counts / package filter.
+     * Create a new DataApiValidationError
      *
-     * Optional for backward compatibility with older framework
-     * versions that do not yet emit it; clients should fall back to
-     * an empty record.
+     * @param message - Human-readable error message
+     * @param field - The field that failed validation (optional)
+     * @param validationErrors - Array of validation error details
+     * @param details - Additional error details
      */
-    stats?: Record<string, {
-        count: number;
-        locked?: number;
-        packages: string[];
-    }>;
+    constructor(message: string, field?: string | undefined, validationErrors?: Array<{
+        field: string;
+        message: string;
+    }> | undefined, details?: Record<string, unknown>);
+    /**
+     * Get all validation errors as a formatted list
+     */
+    getValidationErrors(): {
+        field: string;
+        message: string;
+    }[];
 }
-/** Reference back-pointer — Phase 3a `/references`. */
-interface MetadataReference {
-    /** Referencing item's metadata type. */
-    fromType: string;
-    /** Referencing item's name. */
-    fromName: string;
-    /** JSON path within the referencing item that holds the reference. */
-    path: string;
-    /** The actual value seen at `path` (the referenced name). */
-    value: string;
+/**
+ * Helper function to create an error from an HTTP response
+ *
+ * @param response - Response object or error from fetch/axios
+ * @param context - Additional context for debugging
+ * @returns Appropriate error instance
+ */
+declare function createErrorFromResponse(response: Record<string, unknown>, context?: string): ObjectStackError;
+/**
+ * Type guard to check if an error is an ObjectStackError
+ */
+declare function isObjectStackError(error: unknown): error is ObjectStackError;
+/**
+ * Type guard to check if an error is a specific ObjectStack error type
+ */
+declare function isErrorType<T extends ObjectStackError>(error: unknown, errorClass: new (...args: any[]) => T): error is 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.
+ */
+/**
+ * Statistics reported by {@link MetadataCache.getStats} for monitoring.
+ *
+ * NOT the spec's `CacheStats` (`@objectstack/spec/contracts`), whose name this
+ * interface wore until objectui#3160 (objectstack#4115 ledger batch 6). That one
+ * describes the platform's `ICacheService` — a server-side KV cache measured by
+ * `keyCount` and `memoryUsage`. This one describes the browser-side LRU in front
+ * of `/api/v1/meta/*`: it is bounded (`size`/`maxSize`), it evicts, it coalesces
+ * concurrent fetches onto one in-flight promise, and it reports a `hitRate`.
+ * Neither type has a key the other has, so this is a name collision, not a
+ * dialect — deriving would have replaced every field.
+ */
+interface MetadataCacheStats {
+    size: number;
+    maxSize: number;
+    hits: number;
+    misses: number;
+    evictions: number;
+    /** Number of concurrent fetches that were coalesced onto an in-flight request. */
+    coalesced: number;
+    hitRate: number;
 }
-interface MetadataHistoryOptions {
-    /** Only return events after this sequence number. */
-    sinceSeq?: number;
-    /** Limit the number of events returned. */
-    limit?: 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;
 }
-/** A single field-anchored spec-validation issue (server `error.details.issues`). */
-interface MetadataValidationIssue {
-    /** Dot-path to the offending field, e.g. `fields.amount.type` (`''` = root). */
-    path: string;
-    message: string;
-    code?: string;
+interface PluginExport {
+    /** Export name */
+    name: string;
+    /** Export type */
+    type: 'component' | 'hook' | 'utility' | 'provider';
+    /** Description */
+    description?: string;
 }
-interface MetadataError extends Error {
-    status: number;
-    code?: string;
-    body?: unknown;
-    /** Structured spec-validation issues, when the failure was a validation error. */
-    issues?: MetadataValidationIssue[];
+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;
 }
 /**
- * MetadataClient — read/write protocol metadata via the framework REST API.
+ * 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.
  *
- * @example
- * ```ts
- * const client = new MetadataClient({ baseUrl: 'http://localhost:3000' });
- * const objects = await client.list<{ name: string; label?: string }>('object');
- * const account = await client.get<{ fields: Record<string, unknown> }>('object', 'account');
- * await client.save('object', 'account', { ...account, label: 'Customer' });
+ * Persists arbitrary per-user UI state (favorites, recently-accessed items, …)
+ * as a single JSON blob per `(user_id, key)` row in the **unified per-user
+ * KV store** — the `sys_user_preference` object shipped by every
+ * `@objectstack/plugin-auth`-enabled environment.
+ *
+ * Using the existing `sys_user_preference` table (rather than a parallel
+ * `user_app_state` table) keeps things consistent with the platform's
+ * "one KV store per scope" pattern:
+ *
+ *   - `sys_setting`         ← tenant / env scope
+ *   - `sys_user_preference` ← per-user scope  ← we live here
+ *
+ * Callers are encouraged to namespace their keys (e.g. `ui.favorites`,
+ * `ui.recent`, `ui.grid.account.state`) so explicit settings (`theme`,
+ * `locale`) and machine-written UI traces stay easy to tell apart.
+ *
+ * ## Schema this adapter expects
+ *
+ * The canonical `sys_user_preference` schema (from
+ * `@objectstack/platform-objects`):
+ *
+ * ```yaml
+ * object: sys_user_preference
+ * fields:
+ *   user_id:    lookup(sys_user)  # indexed
+ *   key:        string            # indexed  (e.g. "ui.favorites")
+ *   value:      json              # the serialised list
+ *   updated_at: datetime          # auto-managed
+ * unique: [user_id, key]
  * ```
+ *
+ * ## Failure modes
+ *
+ * The adapter is designed to **degrade silently**. Any error — missing
+ * schema, 4xx/5xx, network — is caught:
+ *
+ * - `load()` returns `[]`, so the hosting provider keeps its localStorage state.
+ * - `save()` resolves without throwing, so UI mutations never surface a toast.
+ *
+ * As soon as the backend supports `sys_user_preference`, persistence
+ * "lights up" with no code change.
+ *
+ * @module
  */
-declare class MetadataClient {
-    private readonly base;
-    private readonly fetchImpl;
-    private readonly headers;
-    /** ADR-0037: when true, reads render the draft-overlaid world. */
-    readonly previewDrafts: boolean;
-    constructor(config: MetadataClientConfig);
-    /** Update the client's environment scope at runtime. */
-    withEnvironment(environmentId: string | undefined): MetadataClient;
-    /**
-     * Derive a client whose reads render the draft-overlaid world (or not).
-     * Same base/fetch/headers; used by the app-shell to switch the whole
-     * renderer tree into ADR-0037 preview mode off one URL flag.
-     */
-    withPreviewDrafts(previewDrafts: boolean): MetadataClient;
-    /** List all registered metadata types (returns the registry rows). */
-    listTypes(): Promise<unknown[]>;
-    /** List items of a metadata type (e.g. `object`, `field`, `view`). */
-    list<T = unknown>(type: string, options?: MetadataListOptions): Promise<T[]>;
-    /**
-     * List pending DRAFT items (ADR-0033) — what an AI authored but nobody
-     * published yet. `list()` only sees published/active metadata, so a
-     * just-built app package looks empty there; this surfaces the drafts so the
-     * console can show a "pending changes" view and draft-aware package contents.
-     * Optionally narrow by `packageId` and/or `type`. Returns light headers
-     * (no body) carrying `packageId` for grouping.
-     */
-    listDrafts(options?: {
-        packageId?: string;
-        type?: string;
-    }): Promise<MetadataDraftHeader[]>;
-    /**
-     * Get a single metadata item. Returns the unwrapped item content
-     * (matching the framework REST handler which calls `res.json(item)`).
-     * Returns `null` on 404 to keep the call-site ergonomic.
-     */
-    get<T = unknown>(type: string, name: string, options?: MetadataGetOptions): Promise<T | null>;
-    /**
-     * Read the pending draft body for an item (`?state=draft`). Returns
-     * `null` when there is no draft pending. Draft reads do NOT fall
-     * back to the published overlay or the artifact registry — a `null`
-     * unambiguously means "nothing to publish".
-     *
-     * Note: the framework wraps draft responses in an envelope
-     * `{ type, name, item }` (matching `getMetaItem`); callers should
-     * read `.item` to get the body. The legacy `get()` returns the
-     * unwrapped body, so this method preserves that asymmetry by
-     * returning whatever the server sent.
-     */
-    getDraft<T = unknown>(type: string, name: string, options?: {
-        packageId?: string;
-    }): Promise<T | null>;
-    /**
-     * Save (PUT) a metadata item. The framework accepts both the bare
-     * item payload and the `{ item: ... }` / `{ metadata: ... }`
-     * envelopes; we send bare for consistency. Pass `mode: 'draft'` to
-     * stage the change without publishing (Studio's "Save" button).
-     */
-    save<T = unknown>(type: string, name: string, item: unknown, options?: MetadataClientSaveOptions): Promise<T>;
-    /**
-     * Publish a single pending draft BY REFERENCE — promotes the draft row for
-     * `(type, name)` into the active overlay and drops the draft. Works for ANY
-     * draft, including ones with no `packageId` binding (which the package-scoped
-     * `/packages/:id/publish-drafts` flow cannot reach). Use this to publish the
-     * exact set returned by {@link listDrafts} without needing a package.
-     *
-     * Returns the server result. For `seed` drafts the protocol also materializes
-     * the rows and reports under `seedApplied` — a data problem never fails the
-     * publish, so callers should check `seedApplied?.success` and warn the user
-     * rather than assume the data went live.
-     */
-    publishDraft(type: string, name: string): Promise<{
-        success?: boolean;
-        seedApplied?: {
-            success: boolean;
-            inserted?: number;
-            updated?: number;
-            error?: string;
-            errors?: unknown[];
-        };
-    } & Record<string, unknown>>;
+
+interface ObjectStackUserStateAdapterOptions {
+    /** Connected data source (usually the one provided by `<AdapterProvider>`). */
+    dataSource: DataSource<any>;
+    /** Authenticated user id. */
+    userId: string;
     /**
-     * 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).
+     * Storage key. Should be a dotted, namespaced string so UI traces
+     * don't collide with user-facing preferences. Examples:
+     * `ui.favorites`, `ui.recent`, `ui.grid.account.state`.
      */
-    layered<T = unknown>(type: string, name: string, options?: {
-        packageId?: string;
-    }): Promise<MetadataLayered<T>>;
+    key: string;
+    /** Override the storage object name. Defaults to `"sys_user_preference"`. */
+    resource?: string;
     /**
-     * Cross-type sweep of load-time validation results — calls
-     * `GET /meta/diagnostics`. Returns every entry the framework
-     * considers invalid (or, when `severity: 'warning'`, also entries
-     * with only warnings).
-     *
-     * Used by the Studio's governance overview page and by the
-     * directory page to show "N invalid" badges per metadata type.
+     * Optional console logger for development diagnostics. Defaults to noop so
+     * production builds stay quiet.
      */
-    diagnostics(options?: MetadataDiagnosticsOptions): Promise<MetadataDiagnosticsSummary>;
+    onError?: (where: 'load' | 'save', error: unknown) => void;
+}
+interface UserDataAdapter<T> {
+    load(): Promise<T[]>;
+    save(items: T[]): Promise<void>;
+}
+/**
+ * Build a `UserDataAdapter<T>` backed by ObjectStack.
+ *
+ * Each adapter instance is bound to a single `(user, key)` pair; create
+ * one per slot you want to persist.
+ */
+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;
     /**
-     * Find every metadata item that references this one (Phase 3a). Useful
-     * for pre-delete impact analysis: "Are any views pointing at this
-     * object before I drop it?".
+     * Register a new integration.
      */
-    references(type: string, name: string): Promise<MetadataReference[]>;
+    register(id: string, config: IntegrationConfig): void;
     /**
-     * Reset a metadata customization overlay back to the artifact default.
-     * Idempotent: returns the result even when no overlay row existed.
-     * Pass `state: 'draft'` to discard the pending draft only (keeps the
-     * published overlay intact) — useful for a Studio "Discard draft" button.
+     * Remove an integration.
      */
-    reset<T = unknown>(type: string, name: string, options?: MetadataDeleteOptions): Promise<T>;
+    unregister(id: string): void;
     /**
-     * Promote the pending draft of an item to the active overlay
-     * (POST `/meta/:type/:name/publish`). Returns
-     * `{ success, version, seq, message }`. Throws a `404 no_draft` if
-     * nothing is pending and `409 metadata_conflict` if the published
-     * overlay moved while the draft was sitting.
+     * Get all registered integrations.
      */
-    publish<T = unknown>(type: string, name: string, options?: {
-        actor?: string;
-        message?: string;
-    }): Promise<T>;
+    getAll(): Map<string, IntegrationConfig>;
     /**
-     * Restore an item to a previous version (POST `/meta/:type/:name/rollback`).
-     * The server reads the history row at `toVersion`, writes its body back
-     * as the active overlay with `operation_type='revert'`. Returns
-     * `{ success, version, seq, restoredFromVersion, message }`. Throws
-     * `404 version_not_found` for unknown versions and `409 version_not_restorable`
-     * when the target version is a delete tombstone.
+     * Get integrations that match a specific event.
      */
-    rollback<T = unknown>(type: string, name: string, toVersion: number, options?: {
-        actor?: string;
-        message?: string;
-    }): Promise<T>;
+    getForEvent(event: string): IntegrationConfig[];
     /**
-     * Compute a structured top-level key diff between two history versions
-     * (GET `/meta/:type/:name/diff?from=&to=`). Returns
-     * `{ added, removed, changed }` where each entry carries a `path` and
-     * the relevant value(s). Useful for "what changed in this draft?" and
-     * pre-rollback previews.
+     * Dispatch an event to all matching integrations.
+     * Returns results for each integration.
      */
-    diff<T = unknown>(type: string, name: string, fromVersion?: number, toVersion?: number): Promise<T>;
-    /** Fetch the durable history (change log) for one metadata item. */
-    history<T = unknown>(type: string, name: string, options?: MetadataHistoryOptions): Promise<T>;
+    dispatch(event: string, payload: Record<string, unknown>): Promise<Array<{
+        id: string;
+        success: boolean;
+        error?: string;
+    }>>;
     /**
-     * Fetch the protection-audit trail for one metadata item
-     * (ADR-0010 §3.6 / Phase 4.1). Shows every save/publish/rollback/
-     * delete/reset attempt — allowed, denied, or forced — so the
-     * Studio "审计日志 / Audit log" tab can render who tried what
-     * and whether a lock blocked it.
+     * Send payload to a specific integration.
      */
-    audit(type: string, name: string, options?: {
-        limit?: number;
-    }): Promise<MetadataAuditResponse>;
+    private send;
 }
 
 /**
@@ -1320,6 +1320,83 @@ declare function readTransactionalBatchCapability(discovery: unknown): boolean |
  * tripping on the property-name mismatch.
  */
 declare function is404Error(error: unknown): boolean;
+/**
+ * The two denials the server derives from an object's `enable` block —
+ * `apiAccessDenialFromEnable` (objectstack `packages/rest/src/rest-server.ts`).
+ *
+ *   - `OBJECT_API_DISABLED` (404) — `enable.apiEnabled: false`; the object is
+ *     not exposed over the data API at all.
+ *   - `OBJECT_API_METHOD_NOT_ALLOWED` (405) — the operation is absent from the
+ *     `enable.apiMethods` whitelist.
+ *
+ * Both are **pure functions of the object's metadata**: no user, no permission,
+ * no context, no request body. So neither is transient and neither is
+ * per-user — when one happens it is a permanent property of that object, and
+ * every retry of every persona gets the identical answer.
+ *
+ * That is exactly why they must not be degraded into "no data". A 404 from a
+ * missing collection means *this backend doesn't have that table*, which the
+ * optional-collection probes below legitimately read as "feature unavailable";
+ * a 404 from `OBJECT_API_DISABLED` means *this page can never work*. Answering
+ * the second with an empty result set renders "you have no records" over a
+ * surface that is not allowed to have any (objectui#4408 — it also hid the
+ * upstream defect objectstack#7544 for its entire life, because a merely
+ * unpopulated page invites nobody to click through).
+ */
+declare const API_ACCESS_DENIED_CODES: readonly ["OBJECT_API_DISABLED", "OBJECT_API_METHOD_NOT_ALLOWED"];
+/**
+ * True when `error` is an `enable`-block API denial (see
+ * {@link API_ACCESS_DENIED_CODES}).
+ *
+ * Discriminates on the ADR-0112 `code`, never on the status: 404 alone cannot
+ * separate a disabled object from a missing collection, and 405 alone cannot
+ * separate a withheld method from any other method rejection. The code survives
+ * the transport — `@objectstack/client`'s fetch wrapper stamps `error.code`
+ * from the response envelope, and both spellings are declared members of the
+ * spec's `StandardErrorCode` — so no heuristic on status is needed or wanted.
+ */
+declare function isApiAccessDeniedError(error: unknown): boolean;
+/**
+ * What the by-name meta app route said about THIS session's access to an app
+ * (objectui#4252 / objectstack#8013).
+ *
+ *  - `granted` — the route served the app document.
+ *  - `denied`  — the app EXISTS and the session lacks its `requiredPermissions`.
+ *    The only verdict a caller may render as an authorization refusal.
+ *  - `unknown` — anything else: an absent app, an unpublished one, an app
+ *    withheld by an absent optional service, an unreachable server, an adapter
+ *    that cannot ask. All of these are cases where the server declined to say
+ *    that a permission of the caller's is missing, so no caller may claim it.
+ *
+ * Three values rather than a boolean because the third is not a shade of the
+ * other two: "the app is missing" and "I could not find out" both have to leave
+ * the caller's existing copy alone, and collapsing them into `false` invites a
+ * consumer to read a failed probe as a positive absence.
+ */
+type AppAccessVerdict = 'granted' | 'denied' | 'unknown';
+/**
+ * The ADR-0112 standard catalog code the by-name meta app route answers with
+ * when an app exists and the session lacks its `requiredPermissions`
+ * (objectstack#8013, `sendError(res, 403, 'PERMISSION_DENIED', …)` in
+ * `packages/rest/src/rest-server.ts`).
+ *
+ * Deliberately NOT a member of {@link API_ACCESS_DENIED_CODES}: those two are
+ * pure functions of an object's `enable` metadata — permanent, identical for
+ * every persona — whereas this one is a statement about the CALLER, and the same
+ * request by a different session succeeds. Same word "denied", different
+ * question, so a consumer that wants one must never match the other.
+ */
+declare const APP_PERMISSION_DENIED_CODE = "PERMISSION_DENIED";
+/**
+ * True when `error` is the by-name app route's permission denial.
+ *
+ * Discriminates on the ADR-0112 `code`, never on the status (objectui#4408): the
+ * route answers 403 for this and 404 for absence today, but a status is a
+ * transport fact many conditions share, while the code is the contract. The
+ * console's whole reason to call this is to tell two REFUSALS apart, and both
+ * are errors.
+ */
+declare function isAppPermissionDeniedError(error: unknown): boolean;
 /**
  * Thrown when the deployment has no analytics capability installed
  * (framework#3891 / #4019).
@@ -1434,6 +1511,50 @@ declare function isConcurrentUpdateError(error: unknown): error is ConcurrentUpd
  *     instead of showing one undirected toast.
  */
 declare function normaliseClientError(error: unknown): unknown;
+/**
+ * Fold an @objectstack/client HTTP-failure `meta` bag into the log MESSAGE.
+ *
+ * The client already hands us everything worth knowing —
+ * `logger.error("HTTP request failed", undefined, { method, url, status, error })`
+ * — but it hands it as the THIRD argument. Everything that flattens a console
+ * record to text (a headless/CDP console capture, a log shipper, a copied
+ * DevTools line) keeps only the message and renders the rest as `[object
+ * Object]` / `Object`, so a wall of failures carried no method, no URL and no
+ * status: the reporter of objectui#4042 had to diff the network panel by hand
+ * to find out that 30 red lines were all one benign pre-login burst.
+ *
+ * So the identifying fields go into the string itself, and the structured bag
+ * is STILL passed alongside for DevTools to expand — text for the flatteners,
+ * object for the inspectors, neither at the other's expense.
+ *
+ * Exported for tests. Returns `null` when `meta` carries none of the three
+ * fields, so callers keep the original message rather than printing a husk.
+ */
+declare function formatHttpFailureMessage(message: string, meta?: Record<string, any>): string | null;
+/**
+ * Build a Logger compatible with @objectstack/client that (a) spells every
+ * request failure out in the message — see {@link formatHttpFailureMessage} —
+ * and (b) demotes expected 404 noise to console.debug. The client logs every
+ * non-2xx response with
+ * `logger.error("HTTP request failed", undefined, { method, url, status, error })`,
+ * but 404s on optional collections (sys_presence, sys_activity, …) are part of
+ * normal degraded operation when those plugins aren't installed on the
+ * server — they should not surface as errors in the browser DevTools.
+ *
+ * NOTE the asymmetry, and keep it: 404-on-an-optional-collection is demoted
+ * because it is an EXPECTED outcome of a request we still mean to make. No
+ * other status is demoted — a 401 that survives the console's session gate
+ * (objectui#4042: a mid-session expiry, say) is a real event and must stay a
+ * visible, fully-identified error. The cure for doomed requests is not issuing
+ * them, never hiding them once issued.
+ *
+ * Returned object is loosely typed because the spec's Logger interface lives
+ * in a transitive package; using `any` keeps us decoupled.
+ *
+ * Exported so the console's log contract is testable, and so an app wiring its
+ * own `ObjectStackClient` gets the same identified failures.
+ */
+declare function createQuietHttpLogger(): any;
 /**
  * Connection state for monitoring
  */
@@ -1480,6 +1601,36 @@ interface WriteWarningEvent {
 /** Event listener type for write-warning (dropped-fields) events. */
 type WriteWarningListener = (event: WriteWarningEvent) => void;
 
+/**
+ * Resolve which object a `type='view'` metadata item belongs to.
+ *
+ * The metadata index is name-only, not field-typed: `GET /api/v1/meta/view`
+ * accepts `?package=` and `?preview=draft` and nothing else (measured on
+ * framework `packages/rest/src/rest-server.ts` — the `GET /meta/:type`
+ * handler — and on `client.meta.getItems(type, { packageId })`). So every
+ * reader of the view namespace enumerates `type='view'` once and narrows to
+ * one object HERE, client-side.
+ *
+ * ONE spelling, one place, deliberately: {@link ObjectStackAdapter.listViews}
+ * and {@link ObjectStackAdapter.listViewOverrides} read the same rows out of
+ * the same namespace, and two private copies of "which object is this?" is a
+ * drift waiting to happen — the switcher showing a view whose override the
+ * grid cannot find, or the reverse.
+ *
+ * `object` is the identity field the write path stamps (and that the
+ * framework's overlay heals onto identity-less personalization rows —
+ * objectstack#2555); `data.object` is the config's data-provider target and
+ * `objectName` the legacy artifact spelling.
+ *
+ * **Exported** since objectui#4373, for the same one-spelling reason: a writer
+ * outside this module that holds a view BODY but not its object name (app-shell's
+ * `MetadataService`) needs the object to name the keys
+ * {@link ObjectStackAdapter.invalidateViewKeys} drops, and a fourth private copy
+ * of "which object is this?" is exactly the drift this accessor exists to
+ * prevent. Identity only — it names no cache key.
+ */
+declare function viewItemObjectName(item: any): string | undefined;
+
 /**
  * ObjectStack Data Source Adapter
  *
@@ -1532,6 +1683,7 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     private atomicBatchCapability;
     private mutationListeners;
     private writeWarningListeners;
+    private saveAdvisoryListeners;
     constructor(config: {
         baseUrl: string;
         token?: string;
@@ -1652,6 +1804,82 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * this to toast the user; the write itself already succeeded.
      */
     onWriteWarning(callback: WriteWarningListener): () => void;
+    /**
+     * Subscribe to metadata save-advisory events — the runtime authoring gate's
+     * advisory findings on a save that SUCCEEDED (#4237; backend
+     * objectstack#7435). Returns an unsubscribe function.
+     *
+     * Deliberately the same seam as {@link onWriteWarning} (#3431/#3455), which
+     * is what {@link MetadataSaveAdvisoryEvent}'s own declaration already said it
+     * was modelled on. It is a SIBLING of that channel rather than a second
+     * payload pushed down it: `WriteWarningEvent` is a closed shape whose
+     * `droppedFields` is required and means "fields the write legally stripped",
+     * so carrying advisories on it would either force every existing
+     * `onWriteWarning` consumer to grow a branch or make the event lie about what
+     * happened. The seam's SHAPE is what is reused here — a long-lived instance
+     * with a `subscribe → unsubscribe` registration that `AdapterProvider` wires
+     * once — not its event type.
+     *
+     * Why here and not on the config, which is how the other client class does it
+     * (#4133/#4236): `MetadataClient` is minted per component by
+     * `useMetadataClient`, so it has no instance to subscribe to and its sink
+     * rides the factory. `ObjectStackAdapter` is the opposite — one long-lived
+     * instance per app, already carrying this exact subscription pattern.
+     */
+    onSaveAdvisory(callback: MetadataSaveAdvisoryListener): () => void;
+    /**
+     * Notify all save-advisory subscribers. Isolated exactly like
+     * {@link emitWriteWarning}: a throwing listener must neither break the save
+     * nor starve the others.
+     */
+    private emitSaveAdvisory;
+    /**
+     * Install the ONE emitter for the metadata save door (#4237).
+     *
+     * ## Why this seam, and what it covers
+     *
+     * `ObjectStackClient.meta.saveItem` is the second client class that writes
+     * through `PUT /api/v1/meta/:type/:name`, and every one of its callers reaches
+     * it through an adapter this class constructed — the four inside this file
+     * (`updateViewConfig`, the two view paths, `updateDashboard`) via
+     * `this.client`, and every caller outside it via {@link getClient}, which
+     * hands back this same instance: `MetadataService` (app-shell, five saves),
+     * `useNavigationSync`, and plugin-designer's Create/EditAppPage. Wrapping the
+     * method once here therefore covers all of them WITHOUT a per-site edit, which
+     * is the whole point — a toast copied into a dozen call sites is the shape
+     * #4133 rejected for the other client class and it is no better here.
+     *
+     * `meta` is an own, writable property assigned per instance in the SDK's
+     * constructor (`this.meta = { … }`), and the client this adapter builds is
+     * never shared, so the wrap is bounded to an object this adapter owns for its
+     * whole lifetime. It is not a prototype or global patch.
+     *
+     * ## Response shape — measured, not assumed
+     *
+     * The two client classes' envelopes coincide at the top level, which is what
+     * makes `readSaveAdvisories` reusable unchanged across both. `SaveMetaItem-
+     * ResponseSchema` puts `advisories` at the body's top level next to
+     * `success` / `version` / `seq` / `state`, and the SDK's `unwrapResponse`
+     * strips its `{ success, data }` envelope only when the body actually HAS a
+     * `data` key — this body does not, so it is returned verbatim. So the same
+     * reader that `MetadataClient.save` uses reads this response correctly, and
+     * the pins in `onSaveAdvisory.test.ts` drive a real SDK client through a fake
+     * `fetch` rather than stubbing `meta`, so that continues to be measured.
+     *
+     * ## Draft-door honesty (D1)
+     *
+     * Drafts are NEVER gated: the framework returns at its D1 early-return
+     * (`if (args.state !== 'active') return null`) before running a rule, so a
+     * draft save produces no findings to withhold. This client class has no draft
+     * door at all to worry about — the SDK's `saveItem(type, name, item)` takes no
+     * mode and always writes the active door, which is exactly why the gate DOES
+     * run for its callers. `mode` on the emitted event is therefore derived from
+     * the response's own `state` rather than from a request-side flag that does
+     * not exist here: `'draft'` when the server says the row landed as a draft,
+     * `'publish'` otherwise. That keeps the event truthful about which door it
+     * came through instead of hard-coding one.
+     */
+    private installSaveAdvisoryInterceptor;
     create(resource: string, data: Partial<T>): Promise<T>;
     /**
      * Update an existing record.
@@ -1887,23 +2115,90 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * @returns Promise resolving to discovery data, or null if not connected
      */
     getDiscovery(): Promise<unknown | null>;
+    /**
+     * **The one place that knows which cache keys a view-row write invalidates.**
+     *
+     * Two reads are cached under view-shaped keys, and both go stale when any
+     * writer touches a view row for `objectName`:
+     *
+     * | reader                     | key                        |
+     * |----------------------------|----------------------------|
+     * | {@link getView}            | `view:{object}:{viewName}` |
+     * | {@link listViewOverrides}  | `view-overrides:{object}`  |
+     *
+     * Every writer routes here rather than restating that pair. The repo has now
+     * paid twice for restatement: objectui#3778 removed five copies of a key
+     * (`views:{object}`) that no reader had ever populated, and objectui#4363
+     * fixed four copies that named only half the live set — and objectui#4373 is
+     * the measured proof that the failure recurs by default, because the console's
+     * real create/publish flow writes these same rows through the ADR-0034
+     * metadata seam and never learned the key list at all. A pin suite can only
+     * guard the writers that exist; a mandatory seam makes the next writer
+     * structurally unable to forget.
+     *
+     * The rule is uniform per WRITE, not per branch: a write to a view row drops
+     * both keys, in that order. Draft-addressed writes over-invalidate on purpose
+     * — both readers enumerate PUBLISHED rows, so a draft write stales neither —
+     * because the costs are not symmetric. An unnecessary invalidation costs one
+     * refetch; a missed one costs up to the cache's 5-minute TTL of stale
+     * overrides, and "which half am I in?" is not a question a future writer
+     * should have to re-answer to stay correct.
+     *
+     * Public because the writers are not all in this class: app-shell's ADR-0034
+     * seam (`runtime-metadata-persistence.ts`) and `MetadataService` write the
+     * same rows through `client.meta` / the `/meta` draft-publish API, and they
+     * reach this adapter as the `dataSource` they were already handed.
+     *
+     * @param objectName - Object the view belongs to (the `{object}` in both keys)
+     * @param viewName - The view's canonical `name` — the identity
+     *   {@link getView} reads back by and {@link listViewOverrides} keys its map
+     *   with. Callers that hold a qualified `<object>.<key>` name pass it as-is:
+     *   it is the row key, not a path to be split.
+     */
+    invalidateViewKeys(objectName: string, viewName: string): void;
     /**
      * Batch-fetch all persisted view overrides for an object.
      *
-     * Per-view runtime overrides (density, column widths, sort, …) are
-     * stored in the metadata registry under key `<objectName>/<viewName>`.
-     * Loading them per-view fires N HTTP GETs that return 404 for views
-     * the user has never customized — generates console noise on every
-     * page load. This batch method performs a single
-     * `GET /api/v1/meta/<objectName>` (returns `{type, items}`) and
-     * returns a `{viewName: override}` map. Returns an empty map if the
-     * server doesn't expose the listing or returns no items.
+     * Per-view runtime overrides (density, column widths, sort, hidden
+     * columns, inlineEdit …) live in the SAME metadata namespace the
+     * write path uses: `type='view'`, `name=<viewId>` (see
+     * {@link updateViewConfig}). Loading them per-view fires N HTTP GETs
+     * that 404 for every view the user never customized — console noise on
+     * every page load. This batch method performs a single
+     * `GET /api/v1/meta/view` (returns `{type, items}`) and narrows the
+     * result to `objectName` client-side, exactly as {@link listViews}
+     * does over the same rows (shared accessor: {@link viewItemObjectName}).
+     *
+     * objectui#3774 — this used to enumerate `GET /api/v1/meta/<objectName>`,
+     * putting the OBJECT name in the metadata TYPE slot. That key space is
+     * disjoint from the one the write path lands in, so the batch map came
+     * back empty for every object, forever, and every saved personalization
+     * read back as "setting didn't save".
      *
-     * Result is cached identically to {@link getView}; saving a view via
-     * {@link updateViewConfig} invalidates the cache.
+     * FAILURES REJECT — they are not answered as `{}`. An empty map is an
+     * authoritative "this object has no overrides" (callers may trust it and
+     * skip the per-view reads); a transport/permission failure is "I could
+     * not tell", and reporting the two as the same value is what made
+     * ObjectView's per-view {@link getView} fallback unreachable code. When
+     * we cannot tell, we do not pretend we can. Rejections are not cached
+     * (the cache stores on success only), so a transient failure does not
+     * pin an empty answer for the TTL.
+     *
+     * Result is cached identically to {@link getView}, and EVERY view write —
+     * on this adapter and above it — invalidates it through the one seam,
+     * {@link invalidateViewKeys}. For a long time only {@link updateViewConfig}
+     * did (objectui#4363), which left the other three adapter paths stale
+     * for the cache's 5-minute TTL. That gap does not self-heal: the consumer
+     * (`loadViewOverrides`, app-shell `ObjectView`) treats a RESOLVED map as
+     * authoritative and deliberately does not re-probe per view — objectui#3774,
+     * and correct, since re-probing reinstates the 404 flurry the batch read
+     * exists to remove. So a stale map here is served in full, and the per-view
+     * {@link getView} fallback that would have masked it never runs.
      *
      * @param objectName - Object name (e.g. 'lead')
      * @returns Map keyed by view name with the persisted override config
+     * @throws whatever the metadata transport throws — callers that have a
+     *   per-view fallback should catch and use it.
      */
     listViewOverrides(objectName: string): Promise<Record<string, any>>;
     /**
@@ -1942,8 +2237,10 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * match the view spec shape.
      *
      * Returns view spec objects with their canonical `name` as identifier.
-     * Filters by `data.object === objectName` (or top-level `object`)
-     * client-side because the metadata index is name-only, not field-typed.
+     * Narrows to one object client-side via {@link viewItemObjectName} —
+     * the metadata index is name-only, not field-typed, so the route has no
+     * `?object=` to push the filter down into. {@link listViewOverrides}
+     * reads the same rows through the same accessor.
      */
     listViews(objectName: string, options?: {
         previewDrafts?: boolean;
@@ -1971,23 +2268,127 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      *
      * Generates a snake_case name if `spec.name` is not provided by appending
      * a short timestamp suffix to the source-name hint.
+     *
+     * Invalidates through {@link invalidateViewKeys}, like every other writer —
+     * see {@link listViewOverrides} for why the batch map is the one that cannot
+     * heal itself (objectui#4363).
      */
     createView(objectName: string, spec: Record<string, any>): Promise<Record<string, any> | void>;
     /**
      * Apply a partial update to an existing overlay view. Reads the current
-     * overlay (or seeds from artifact), merges, and writes back. ADR-0005
-     * overlay rows store the *full* view document, so partial updates require
-     * a read-merge-write cycle.
+     * document, merges, and writes it back. ADR-0005 overlay rows store the
+     * *full* view document, so partial updates require a read-merge-write cycle.
+     *
+     * **Both halves address the same row (#4139).** A view has two possible
+     * homes and the read must resolve the one the write will target:
+     *
+     * - a pending per-item **draft** (`?state=draft` / `?mode=draft`) — where
+     *   ADR-0034 stages every runtime-created view, so a view made from the `+`
+     *   tab lives ONLY here until an explicit Publish;
+     * - the **published** overlay (`client.meta.getItem` / `saveItem`).
+     *
+     * The draft is probed FIRST, and a hit is merged and written straight back
+     * as a draft. Two things that ordering buys, both load-bearing:
+     *
+     * 1. A draft-only view is no longer invisible to the read. It used to 404,
+     *    and a `catch {}` labelled "treat missing as create-equivalent"
+     *    substituted `current = {}` — so a rename merged onto nothing and went
+     *    out as a `{label, name, object}` partial the server rejects (422),
+     *    while the draft row the UI reads back through `?preview=draft` kept the
+     *    old label. The edit was lost with no error surfaced to the user.
+     * 2. A draft is never bypassed. Writing the published row while a draft is
+     *    pending would put the edit somewhere the draft shadows — and Publish
+     *    would then overwrite it with the pre-edit body, losing the change a
+     *    second time, later, where nothing connects it to this call.
+     *
+     * A draft edit stays a draft: `mode: 'draft'` keeps ADR-0037's guarantee
+     * that nothing the preview shows goes live until Publish. Renaming a
+     * *published* view (no draft pending) is unchanged — it writes the
+     * published overlay, as before.
+     *
+     * **Both halves invalidate through {@link invalidateViewKeys}** (objectui#4363,
+     * #4373) — same call, same key set, so the draft half's deliberate
+     * over-invalidation is the seam's uniform rule rather than a per-branch
+     * decision this method has to keep re-making.
+     *
+     * @throws when the view resolves in neither home, or when either read fails
+     *   for any other reason (network, permission). Both used to be swallowed
+     *   and converted into the bad partial write above; a caller that wants a
+     *   view created should call {@link createView}, which is the operation that
+     *   actually means "create".
      */
     updateView(objectName: string, viewName: string, partial: Record<string, any>): Promise<Record<string, any> | void>;
     /**
-     * Delete an overlay view (reset to artifact default if one exists, or
-     * remove entirely if it was a user-created view). Routes to
-     * `DELETE /api/v1/meta/view/:name`.
+     * Delete an overlay view — from **every home it has**.
+     *
+     * A view has two possible homes, the same two {@link updateView} addresses:
+     * the pending per-item **draft** (`DELETE /meta/view/:name?state=draft`) and
+     * the **published** overlay (`DELETE /meta/view/:name`). This method used to
+     * issue only the second, and the three cases came out like this (#4479):
+     *
+     * | case               | before                                              |
+     * |--------------------|-----------------------------------------------------|
+     * | draft-only view    | BUG — the published delete answered `reset:false` /  |
+     * |                    | "nothing to delete", the draft survived, and the tab |
+     * |                    | was still there after reload                        |
+     * | published-only     | correct — `reset:true`, tab gone                     |
+     * | published + draft  | ACCIDENTALLY correct — the published row went, so    |
+     * |                    | the tab went; the orphan draft stayed behind        |
+     *
+     * **Why this is not the mechanical mirror of #4139.** `updateView` probes
+     * the draft first and writes back to whichever home the read resolved, and
+     * that is right for an update in all three cases. Copying it here would be
+     * wrong in the third: `persistRuntimeMetadata` (app-shell) stages EVERY
+     * runtime edit as a draft, so "publish a view, then edit it" routinely
+     * produces a pair — and a draft-first-only delete on a pair discards the
+     * draft and leaves the published row serving the view. That is not Delete
+     * view, it is **Discard draft**, a deliberately different operation that
+     * already exists (`discardRuntimeDraft`, documented as "the published
+     * overlay is untouched"). The clean statement of the asymmetry: for an
+     * update, one home is the right home; for a delete, "remove this view" is
+     * satisfied only when NO home is left serving it.
+     *
+     * So both homes are deleted, **draft first**. The order is load-bearing on
+     * the failure path: a fault between the two calls leaves the PUBLISHED
+     * overlay intact, so the view is still served and the operation is cleanly
+     * retryable. The reverse order would strand a draft-only view — which is
+     * precisely the bug shape above.
+     *
+     * **Two blind calls, no probe.** The framework's `deleteMetaItem` answers a
+     * missing home with a **200** carrying `reset:false` (`"No pending draft
+     * for view/x."` / `"No view 'x' found — nothing to delete."`), never a 404,
+     * so there is nothing for a probe to protect against. `updateView` needs its
+     * probe for a different reason — its read must resolve the row the merge
+     * writes back to — and that reason has no counterpart for a delete.
+     *
+     * **One transport, one error contract.** Both halves go through
+     * {@link MetadataClient} (`reset`), the transport that can express the
+     * `?state=` qualifier and the one `updateView`'s draft half already uses.
+     * The published half used to go through `client.meta.deleteItem`; measured,
+     * that issues the byte-identical request (`DELETE
+     * {baseUrl}/api/v1/meta/view/:name`, no environment scoping is configured on
+     * this adapter), so routing it here costs no addressing change and buys a
+     * single `MetadataError` shape across both calls instead of two.
+     *
+     * @returns `deleted` is true only when no home is left serving the view AND
+     *   at least one actually held a row. A view that existed in neither home
+     *   still answers `false`, unchanged. The per-home outcomes are additive:
+     *   a partial result is observable rather than rounded up to `true`.
+     * @throws when either delete fails, matching {@link updateView}'s
+     *   convention of surfacing the fault rather than degrading. A failure of
+     *   the PUBLISHED half after the draft was discarded carries the partial
+     *   state on the error's `outcome` — "draft gone, overlay left" is exactly
+     *   what the old `{ deleted: boolean }` could not express.
+     *
+     * Invalidates through {@link invalidateViewKeys}: the deleted row leaves the
+     * batch override map too, and a ghost entry there is what the object page
+     * would keep applying (objectui#4363). Fired in a `finally`, so it happens
+     * once per call on EVERY outcome including the throw — after a half-failure
+     * the draft row really is gone, and #4363's asymmetry decides it: an
+     * unnecessary invalidation costs one refetch, a missed one costs the cache's
+     * full 5-minute TTL of stale overrides.
      */
-    deleteView(objectName: string, viewName: string): Promise<{
-        deleted: boolean;
-    }>;
+    deleteView(objectName: string, viewName: string): Promise<DeleteViewResult>;
     /**
      * Get an application definition by name or ID.
      * Attempts to fetch from the server metadata API.
@@ -1998,6 +2399,43 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * @returns Promise resolving to the app definition or null
      */
     getApp(appId: string): Promise<unknown | null>;
+    /**
+     * 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
+     * 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
+     * permanent authorization decision, which cost a downstream acceptance round
+     * two test batches spent chasing a platform defect that was a missing
+     * permission-set binding.
+     *
+     * The maintainer ruling (2026-08-12) put the answer on the BY-NAME route
+     * rather than in the list, so the enumeration surface is not widened past what
+     * a by-name probe already implies (objectstack#8013 / PR #8135): an app that
+     * exists and whose `requiredPermissions` the session lacks answers `403` with
+     * `PERMISSION_DENIED` in the declared envelope, and absence — a nonexistent
+     * name, an unpublished app, an app gated by an absent optional service —
+     * keeps answering `404 RESOURCE_NOT_FOUND`.
+     *
+     * ## Why this is a separate method and not a flavour of {@link getApp}
+     *
+     *  - `getApp` degrades EVERY failure to `null`, which is exactly the
+     *    conflation this exists to undo; changing it would silently re-point its
+     *    own callers' fallback-to-static-config path.
+     *  - `getApp` memoises in `metadataCache`. A verdict about the CALLER must not
+     *    be cached beside a document about the APP — one grant, and a cached
+     *    denial outlives the session it described.
+     *
+     * Nothing here throws: a probe that cannot reach an answer returns `unknown`
+     * and the caller keeps whatever it was already showing. Only the measured
+     * `code` produces `denied` — never a status, never a message (objectui#4408).
+     *
+     * @param appName - the app name as it appears in the URL segment
+     */
+    probeAppAccess(appName: string): Promise<AppAccessVerdict>;
     /**
      * Get a page definition from ObjectStack.
      * Uses the metadata API to fetch page layouts.
@@ -2057,44 +2495,67 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * silently returning wrong numbers.
      *
      * @param dataset - An inline dataset definition (draft) OR a saved dataset name.
-     * @param selection - Dimension/measure names to project + runtime directives.
-     */
-    queryDataset(dataset: Record<string, unknown> | string, selection: {
-        dimensions?: string[];
-        measures: string[];
-        runtimeFilter?: Record<string, unknown>;
-        timeDimensions?: unknown[];
-        compareTo?: {
-            kind: 'previousPeriod' | 'previousYear';
-            dimension: string;
-        };
-        order?: Record<string, 'asc' | 'desc'>;
-        limit?: number;
-        offset?: number;
-        timezone?: string;
-        /** Marginal-aggregate groupings (e.g. `[rows, [colDim], []]`) — server
-         *  computes each subtotal with the measure's TRUE aggregate (never client
-         *  re-derived). `[]` is the grand total. */
-        totals?: {
-            groupings: string[][];
-        };
-    }): Promise<{
+     * @param selection - The spec's {@link DatasetSelection} — dimension/measure
+     *   names to project plus runtime directives. This parameter IS the spec type
+     *   by reference, never a local restatement of it (objectui#3613): a hand
+     *   copy of a contract is a second dialect of it, and the copy this replaced
+     *   had already drifted three ways from `@objectstack/spec` — it required
+     *   `compareTo.dimension` (optional since objectstack#5011, and resolved by
+     *   the EXECUTOR, so requiring it pushed callers into exactly the
+     *   consumer-side dimension guess AGENTS.md #0.1 forbids), it widened
+     *   `timeDimensions` to `unknown[]` and `runtimeFilter` to
+     *   `Record<string, unknown>`, and it had never grown `dateGranularity` at
+     *   all. Pinned in `queryDataset.test.ts`.
+     */
+    queryDataset(dataset: Record<string, unknown> | string, selection: DatasetSelection): Promise<{
         rows: Array<Record<string, unknown>>;
-        /** Column metadata: a display `label` (dimensions and measures), and a
-         *  measure's numeral `format` + declared `currency` for value formatting. */
-        fields: Array<{
-            name: string;
-            type: string;
-            label?: string;
-            format?: string;
-            currency?: string;
-        }>;
+        /**
+         * Column metadata — the spec's `AnalyticsResult.fields[]` element BY
+         * REFERENCE, never a local restatement of it (objectui#3752). Read
+         * `@objectstack/spec` for what a column carries; this comment deliberately
+         * does not re-list the keys, because the enumeration it replaced was the
+         * bug: it named five (`name`/`type`/`label`/`format`/`currency`) and stopped
+         * at the contract of the day it was written, so it never grew
+         * `percentScale` — the server's answer to whether a percentage column is a
+         * 0–1 fraction or already percentage points. The spec says a renderer that
+         * receives it "must scale by it instead of guessing from the value"
+         * (objectui#3136), so a declaration that hides the key steers a typed
+         * consumer into exactly the guess-by-magnitude the issue banned. Pinned in
+         * `queryDataset.test.ts`.
+         *
+         * Only this element is spec-owned: the envelope around it (`object` /
+         * `dimensionFields` / `drillRawRows`) is ADR-0021 D2 drill metadata the REST
+         * route adds on top of `AnalyticsResult`, and this method never returns the
+         * result's `sql`, so the whole envelope is NOT an `AnalyticsResult`.
+         */
+        fields: Array<AnalyticsResult['fields'][number]>;
         /** ADR-0021 D2 drill-through: the dataset's base object (records to drill into). */
         object?: string;
         /** Drillable dimension NAME → underlying object FIELD name. */
         dimensionFields?: Record<string, string>;
         /** Raw grouped values per row (aligned to `rows` by index) for drill filters. */
         drillRawRows?: Array<Record<string, unknown>>;
+        /**
+         * Half-open date-range drill scope per row (framework#1752), aligned to
+         * `rows` by index: dimension NAME → the field and `[gte, lt)` bounds of that
+         * row's time bucket. The RANGE companion to `drillRawRows`, which handles
+         * equality dims only — a `dateGranularity` dimension groups a SPAN of
+         * records into one bucket, so the server excludes date dims from
+         * `dimensionFields`/`drillRawRows` and sends this sidecar instead.
+         *
+         * The entry type is `@object-ui/core`'s `DatasetDrillRange` BY REFERENCE,
+         * not a local restatement of it (objectui#3613/#3752 discipline): the same
+         * declaration is what `buildDatasetDrillFilter` — the single consumer that
+         * turns these bounds into an ObjectQL `{ $gte, $lt }` — accepts, and what
+         * `DatasetWidget` / `DatasetReportRenderer` type their state with. Nothing
+         * in `@objectstack/spec` owns this shape yet (the server's own
+         * `AnalyticsResultWithDrill` is local to `service-analytics`), so the shared
+         * in-repo interface is the one contract available; restating it here would
+         * make a third dialect of it. Like `drillRawRows`, only the ARRAY is
+         * validated below — the bounds are unvalidated payload, which is exactly why
+         * `DatasetDrillRange` declares them `unknown`.
+         */
+        drillRanges?: Array<Record<string, DatasetDrillRange>>;
         /** Server-computed marginal aggregates, one entry per requested grouping. */
         totals?: Array<{
             dimensions: string[];
@@ -2211,4 +2672,4 @@ declare function createObjectStackAdapter<T = unknown>(config: {
     reconnectDelay?: number;
 }): DataSource<T>;
 
-export { AnalyticsNotInstalledError, AnalyticsQueryRejectedError, type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, type CloudDeploymentConfig, type CloudHostingConfig, type CloudMarketplaceEntry, CloudOperations, 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 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, generateContractManifest, getSharedDiscovery, is404Error, isAnalyticsNotInstalledError, isConcurrentUpdateError, isErrorType, isMalformedFilterError, isObjectStackError, normaliseClientError, readTransactionalBatchCapability, serializeOrderBy, snapToGrid, validatePluginContract };
+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 };