@object-ui/data-objectstack 17.6.0 → 18.0.0

package/dist/index.d.ts

@@ -1,62 +1,171 @@
 import { ObjectStackClient } from '@objectstack/client';
-import { DroppedFieldsEvent } from '@objectstack/spec/data';
+import { DroppedFieldsEvent, EngineAggregateOptions } from '@objectstack/spec/data';
 export { DroppedFieldsEvent } from '@objectstack/spec/data';
-import { GetMetaItemLayeredResponse, RuntimeAuthoringIssue } from '@objectstack/spec/api';
+import { ListViewGroupHeaderRow } from '@objectstack/spec/ui';
+import { GetMetaItemResponse, GetMetaItemLayeredResponse, ListDraftsResponse, RuntimeAuthoringIssue, GetMetaItemsResponse, PublishPackageDraftsResponse, ValidateDataIssue } 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 { DataSource, ConnectionState, QueryParams, QueryResult, GlobalSearchResult, DataSourceMutationEvent, BatchTransactionOperation, ImportRequestOptions, ImportRecordsResult, CreateImportJobResult, ImportJobProgressInfo, ImportJobResultsInfo, ListImportJobsOptions, ImportJobSummaryInfo, ImportJobUndoResult, ExportDownloadRequest, DeleteViewResult, FileUploadResult } from '@object-ui/types';
+export { ConnectionState, DeleteViewResult, FileUploadResult, ViewHomeDeleteOutcome } from '@object-ui/types';
 import { DatasetDrillRange } from '@object-ui/core';
 
 /**
- * ObjectUI
- * Copyright (c) 2024-present ObjectStack Inc.
+ * Take the body out of a served draft envelope (`{ type, name, item }`) and
+ * remove the framework's own READ DECORATIONS from it — or answer `null` when
+ * there is nothing pending.
  *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
+ * ## Why this function exists at all (objectui#8181)
+ *
+ * It was implemented three separate times — once in `ResourceEditPage`, once in
+ * `StudioDesignSurface`, once in `PackageOwdOverviewPanel` — plus a fourth
+ * hand-rolled copy in `ObjectHooksPanel` under a different name. objectui#7603
+ * taught exactly ONE of those copies to strip. That is the defect this file
+ * closes, and it is a different defect from "N consumers forgot": four
+ * byte-identical copies of a rule mean the next copy is free to omit it again,
+ * so the cure is one function rather than four strips.
+ *
+ * ## Why it lives HERE and not in `app-shell`
+ *
+ * Next to the {@link MetadataClient.getDraft} that produces the envelope this
+ * decodes. `getDraft` deliberately hands back the wire envelope rather than the
+ * body (objectui#4271), so the unwrap is part of that method's contract, not a
+ * detail of any one view. `app-shell` already depends on this package, and the
+ * one non-app-shell consumer (`updateView`, in this package) is a caller too.
+ *
+ * ## The verdict runs BEFORE the strip, never after
+ *
+ * What counts as a pending draft is `getDraft`'s answer. A draft whose only
+ * keys are decorations is still a served draft, so the emptiness verdict is
+ * taken on the body as it arrived; the strip may return an EMPTY object, but it
+ * may never turn a served draft into "no draft". Pinned in
+ * `draft-envelope.test.ts`.
+ *
+ * ## Which keys, and which keys deliberately survive
+ *
+ * The list is the SPEC'S (`METADATA_READ_DECORATIONS`), reached through its own
+ * exported helper — the same one `MetadataService.saveFields` uses on the write
+ * side. Never a second hand-maintained `['_diagnostics', '_draft']` in this
+ * repo: a local copy goes stale the next time the framework adds a decoration,
+ * and a decoration this code does not know to remove is precisely the defect.
+ *
+ * The ADR-0010 protection envelope (`_lock`, `_provenance`, `_packageId`,
+ * `_packageVersion`, ...) shares the underscore spelling and is deliberately
+ * NOT on that list: those keys are declared by the closed schemas so provenance
+ * survives a re-parse. This strip leaves them alone, and doing otherwise would
+ * be the same "drop whatever looks internal" pass AGENTS.md #0.1 bans.
+ *
+ * ## Not a lenient fallback
+ *
+ * It removes exactly the two keys the framework ADDS AT READ TIME and never
+ * stores. A genuinely unrecognized key still fails loudly at whichever gate
+ * sees it next.
+ *
+ * @param resp the value `MetadataClient.getDraft()` resolved to.
+ * @returns the decoration-free draft body, or `null` for "nothing pending".
+ */
+declare function extractDraftBody(resp: unknown): Record<string, unknown> | null;
+/**
+ * One entry of a pending draft's per-key provenance (objectui#12725): which
+ * authoring surface last changed one key path of the draft body, under which
+ * actor, and when. DERIVED from `@objectstack/spec`'s
+ * `GetMetaItemResponseSchema.draftChanges` (objectstack#24298), never
+ * restated: `path` is the key path inside `item` (an array value is one leaf,
+ * `[]` the whole body), `by` is `copilot | studio | api`, `at` an ISO instant.
  */
+type DraftChange = NonNullable<GetMetaItemResponse['draftChanges']>[number];
 /**
- * MetadataClient
+ * The `draftChanges` of a served draft envelope — the value
+ * {@link MetadataClient.getDraft} resolved to — or `null` when the read
+ * recorded none.
  *
- * 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).
+ * The strict draft read (`?state=draft`) serves the key beside `item`, and
+ * leaves it ABSENT, never `[]`, when nothing was recorded (a draft row saved
+ * before the framework's writer, objectstack#24395). So `null` here means
+ * "not recorded", and it is never folded into an empty list a caller would read
+ * as "nothing changed".
+ *
+ * @param resp the value `MetadataClient.getDraft()` resolved to.
+ */
+declare function readDraftChanges(resp: unknown): DraftChange[] | null;
+/**
+ * The entry that answers for the key at `path`: of the entries whose path is
+ * `path` or one of its ancestors, the LONGEST — the framework's own rule, since
+ * a draft save replaces every entry at or under each path it changes, so the
+ * deepest recorded ancestor is the last write that changed this key. `[]` (the
+ * whole body) is everyone's ancestor. `null` when no entry is an ancestor, and
+ * when `changes` is `null` ("not recorded").
  *
- * 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
+ * Paths compare segment by segment, never as a joined string: a segment may
+ * itself contain a dot (a permission set's `fields` map is keyed
+ * `object.field`).
+ */
+declare function governingDraftChange(changes: readonly DraftChange[] | null | undefined, path: readonly string[]): DraftChange | null;
+/**
+ * The entries strictly UNDER `path`: changes to keys inside the value at
+ * `path` (`["fields", "x", "label"]` under `["fields", "x"]`). The governing
+ * entry ({@link governingDraftChange}) answers for the value as a whole; these
+ * answer for its parts, which a later write may have changed through another
+ * surface.
+ */
+declare function draftChangesUnder(changes: readonly DraftChange[] | null | undefined, path: readonly string[]): DraftChange[];
+
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
  *
- * 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.
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
  */
 
 /**
- * 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.
+ * Emitted after a metadata WRITE whose response carried a non-empty
+ * `advisories` array. The write 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
+ * (objectstack-ai/objectstack#3431 / objectstack-ai/objectstack#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.
+ * is record CRUD, these are the metadata write doors.
+ *
+ * ## Both write doors report (#5026)
+ *
+ * The objectstack-ai/objectstack#4463 runtime authoring gate runs on BOTH metadata write doors by its D1
+ * ruling — a draft→active promotion is gated exactly as a direct active save —
+ * and its non-blocking findings ride the 2xx of whichever door earned them.
+ * `SaveMetaItemResponseSchema` has carried the key since objectstack-ai/objectstack#4717 and
+ * `PublishMetaItemResponseSchema` since objectstack#9176; both declare it at
+ * the response's TOP level, under the same name and with the same
+ * `RuntimeAuthoringIssueSchema` element type, which is what lets one reader and
+ * one event serve both. Measured against the installed `@objectstack/spec`
+ * rather than assumed — see the PR for the probe.
+ *
+ * ## And the BATCH publish door (`ce986aafc`)
+ *
+ * `PublishPackageDraftsResponseSchema` declares the same key with the same
+ * element type, riding EACH `published[]` element rather than a parallel
+ * top-level map (objectstack#9343's ruled shape). So the reader is still one
+ * reader — the object it is handed is one `published[]` element instead of a
+ * whole response — and the event is still one event per promoted item.
+ *
+ * The name keeps its `Save` prefix because it is public API of this package and
+ * renaming it would break consumers for no behavioural gain; {@link door} is
+ * what says which write produced the event.
  */
 interface MetadataSaveAdvisoryEvent {
     /** Metadata type saved (e.g. `'flow'`). */
     type: string;
     /** Item name saved. */
     name: string;
+    /**
+     * The bundle member the write named (objectui#12413), when it named one:
+     * set by {@link MetadataClient.publishDraft} from its `options.member`, so
+     * an advisory raised on one language's publish of an `email_template` is
+     * attributed to that member and not to the whole template. Absent for every
+     * write that names no member. Typed from {@link MetadataDraftHeader}'s
+     * `member`, the value the caller read off the draft row.
+     */
+    member?: MetadataDraftHeader['member'];
     /**
      * The save mode the call used. `'draft'` writes are **never gated** — the
      * framework returns at `runtime-authoring-gate.ts`'s D1 early-return
@@ -65,15 +174,65 @@ interface MetadataSaveAdvisoryEvent {
      * consumer reading the event can tell which door it came through.
      */
     mode: 'draft' | 'publish';
+    /**
+     * Which write door produced this event (#5026).
+     *
+     * - `'save'` — `PUT /meta/:type/:name` ({@link MetadataClient.save}, and the
+     *   SDK's `meta.saveItem` behind `ObjectStackAdapter`).
+     * - `'publish'` — the promotion doors: `POST /meta/:type/:name/publish`
+     *   ({@link MetadataClient.publish} and {@link MetadataClient.publishDraft}),
+     *   and the batch `POST /packages/:id/publish-drafts`
+     *   ({@link MetadataClient.publishPackageDrafts}), which emits ONE event per
+     *   `published[]` element carrying that element's own `type` / `name`.
+     *
+     * ## Why the batch route is not a third value (`ce986aafc`)
+     *
+     * The batch door promotes drafts to active — the author pressed Publish, and
+     * every item this event names really was published. What `door` decides is
+     * the frame's VERB, and "Published" is the true one for all three routes; a
+     * third value would have to render the same word. The per-item identity the
+     * author needs to act on is already carried by {@link type} / {@link name},
+     * one event per item, so nothing about the batch is lost by sharing the
+     * value. ⛔ It is NOT a claim that "one call = one event": the batch emits as
+     * many events as it has advised items, which is why each one names its own.
+     *
+     * Distinct from {@link mode}, which cannot answer this: a direct active save
+     * and a draft promotion both report `mode: 'publish'` because both land the
+     * body in the active overlay. The renderer needs the DOOR, because the author
+     * pressed either Save or Publish and a toast that says "Saved" after a
+     * Publish tells them their change is still a draft — the opposite of what
+     * happened, and in this product Save and Publish are two different buttons
+     * with two different meanings.
+     *
+     * REQUIRED rather than optional-with-a-default so a future third door cannot
+     * be wired without stating which one it is: an omitted discriminator would
+     * silently render the save wording.
+     */
+    door: 'save' | '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;
 /**
- * Read the `advisories` array off a save response, defensively.
+ * Read the `advisories` array off a metadata write response, defensively.
  *
- * The server omits the key entirely on a clean save, so `undefined` is the
+ * Serves EVERY write door unchanged (#5026, `ce986aafc`):
+ * `SaveMetaItemResponseSchema` and `PublishMetaItemResponseSchema` declare the
+ * key at the same top level, and `PublishPackageDraftsResponseSchema` declares
+ * it on each `published[]` element — under the same name, with the same element
+ * schema. So there is one reader, not a per-door copy that could drift; the
+ * batch caller hands it one element, which is the object that carries the key
+ * there.
+ *
+ * ⛔ It reads the `advisories` key of the object it is GIVEN and never
+ * traverses. Choosing the object — a response body at the single-item doors,
+ * one `published[]` element at the batch door — is the caller's job precisely
+ * because the place is declared per route: a reader that went hunting for
+ * findings wherever they might be would be inventing a contract the server
+ * never stated.
+ *
+ * The server omits the key entirely on a clean write, 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
@@ -105,9 +264,13 @@ interface MetadataClientConfig {
     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.
+     * non-empty `advisories` array (objectstack#7435). Since #5026 the SAME sink
+     * also receives the publish door's findings (objectstack#9176), and since
+     * `ce986aafc` the batch publish door's too, one event per advised
+     * `published[]` element (objectstack#9343) — read `event.door` to tell a
+     * save from a promotion, and `event.type` / `event.name` for which item. The
+     * write 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`,
@@ -124,18 +287,92 @@ interface MetadataListOptions {
     /** Filter by source package id (matches the `package` query param). */
     packageId?: string;
 }
+/**
+ * A list read as {@link MetadataClient.listResponse} returns it: the items, and
+ * what the server serves BESIDE them, typed by the spec's
+ * `GetMetaItemsResponse` rather than restated (its `type` key is not kept).
+ *
+ * `registrations` is the automation engine's verdict on each listed flow,
+ * keyed by the item's `name` (`FlowRegistrationSchema`, objectstack#23316):
+ * `registered`, `refused` with the engine's `reason` verbatim, or
+ * `unregistered`. It is absent when the server sent none — a type other than
+ * `flow`, a server with no automation service, or one that predates the key —
+ * and absence means no engine judged the flow, ⛔ never `registered`. A name
+ * the map has no entry for is unjudged in the same way.
+ */
+type MetadataListAnswer<T = unknown> = {
+    items: T[];
+} & Pick<GetMetaItemsResponse, 'registrations'>;
 /**
  * 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.
+ *
+ * DERIVED from the spec's row, `ListDraftsResponseSchema.drafts[]`, rather than
+ * re-spelled (objectui#12413): the key names and their types come from the
+ * spec symbol, so a key the spec renames or retypes fails the type-check here
+ * instead of drifting past it.
+ *
+ * - `member` — the bundle member this draft is (objectstack#23073): present on
+ *   every draft of a type whose identity is a pair (today only
+ *   `email_template`, `(name, locale)`), absent for a type identified by its
+ *   name alone. It is the value the by-name doors take back as `?member=`
+ *   ({@link MetadataClient.publishDraft}'s `options.member`).
+ *
+ * ⛔ The pick is deliberate: the five keys this interface declared before keep
+ * their exact types, and `member` is the one key added. The spec row's `label`
+ * is not picked here: it is declared REQUIRED there, and this client talks to
+ * runtimes of several vintages, so claiming it would be this client asserting
+ * a server version it cannot check.
  */
-interface MetadataDraftHeader {
-    type: string;
-    name: string;
-    packageId: string | null;
-    updatedAt: string | null;
-    updatedBy: string | null;
+interface MetadataDraftHeader extends Pick<ListDraftsRow, 'type' | 'name' | 'packageId' | 'updatedAt' | 'updatedBy'> {
+    /** The bundle member, typed by the spec row's own `member` (see above). */
+    member?: ListDraftsRow['member'];
 }
+/** One element of `ListDraftsResponseSchema.drafts`, the spec row `MetadataDraftHeader` derives from. */
+type ListDraftsRow = ListDraftsResponse['drafts'][number];
+/**
+ * What {@link MetadataClient.publishPackageDrafts} resolves with — the "publish
+ * whole app" body, DERIVED from `PublishPackageDraftsResponseSchema` rather
+ * than re-spelled (`ce986aafc`).
+ *
+ * Derived, and then widened in exactly two ways, each for a measured reason:
+ *
+ * - `Partial<…>` because this client talks to runtimes of several vintages and
+ *   the spec's six required keys are what TODAY's producer sets. Declaring them
+ *   required would be this client asserting a server version it cannot check —
+ *   and an older runtime that omits one would be a type lie, not a compile
+ *   error. Every consumer here already reads these keys defensively.
+ * - The index signature because the REST door adds keys on the way out
+ *   (ADR-0045 visibility receipts, the `metadata:reloaded` announce receipt),
+ *   and because a body this client hands back must stay readable by a caller
+ *   that knows about a key this package has never heard of.
+ *
+ * ⛔ What it is NOT is a second definition of the batch response: the key names
+ * and element shapes come from the spec symbol, so a key the spec adds, renames
+ * or retypes arrives here with no edit.
+ */
+type MetadataPublishPackageDraftsResult = Partial<PublishPackageDraftsResponse> & Record<string, unknown>;
+/**
+ * What {@link MetadataClient.publishPackageDrafts} may ask of the batch door
+ * beyond the package id (objectui#12929): today the protocol's opt-in
+ * `backfill` (objectstack#24253), and nothing else.
+ *
+ * Picked off `@objectstack/client`'s own `packages.publishDrafts` signature
+ * rather than re-spelled, so the element shape (`{ object, field }`) is the
+ * client's declaration. The request has no spec schema of its own; the
+ * client's signature is where the protocol declares it. `actor` is not
+ * picked: the door writes as the signed-in caller, and no console surface
+ * names another.
+ *
+ * `backfill` names fields this publish ADDS whose literal `defaultValue` the
+ * server writes into the object's existing rows, as the caller, after the
+ * batch goes live; the receipt comes back as `backfillApplied`. A field that
+ * is not new, or declares no literal default, refuses the WHOLE request with a
+ * 400 before anything is published, so a caller offers only fields it has
+ * judged by the same rule.
+ */
+type MetadataPublishPackageDraftsOptions = Pick<NonNullable<Parameters<ObjectStackClient['packages']['publishDrafts']>[1]>, 'backfill'>;
 /**
  * Options for {@link MetadataClient.save} — a WRITE OVER HTTP to
  * `/api/v1/meta/:type/:name`.
@@ -146,17 +383,41 @@ interface MetadataDraftHeader {
  * metadata item to a FILE — `format: json|yaml|ts`, `path`, `indent`,
  * `prettify`, `sortKeys`, `backup`, `atomic`, `loader`. Not one of those keys
  * exists here, and not one of these exists there: this is the REST client's
- * request envelope — optimistic concurrency (`ifMatch` → `If-Match`), the
- * destructive-change override, the ADR-0033 draft/publish mode, and the
- * owning package. Same words, different layer.
+ * request envelope — optimistic concurrency (`ifMatch` → `If-Match`,
+ * `ifNoneMatch` → `If-None-Match`), the destructive-change override, the
+ * ADR-0033 draft/publish mode, and the owning package. Same words, different
+ * layer.
  */
 interface MetadataClientSaveOptions {
     /**
-     * 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.
+     * Optimistic concurrency (ADR-0008): the `version` token of the stored row
+     * this write was built on, sent as the `If-Match` header, so a write over a
+     * row that has moved since is refused `409 METADATA_CONFLICT` instead of
+     * overwriting it.
+     *
+     * The `/meta` doors serve that token in three places, each naming the row a
+     * save to the SAME address (type, name, `?package=`, lifecycle) compares
+     * against: the item read's `version` (`?state=draft` for the draft row,
+     * declared on `GetMetaItemResponseSchema`), a save receipt's `version`, and
+     * a version conflict's `currentVersion` (`MetadataConflictErrorSchema`). A
+     * served `null` means no such row: pin with {@link ifNoneMatch} instead.
+     *
+     * ⛔ Never together with {@link ifNoneMatch}: {@link MetadataClient.save}
+     * throws before sending a request that carries both.
      */
     ifMatch?: string;
+    /**
+     * The first-write pin, sent as `If-None-Match: *`: write only where no row of
+     * this write's lifecycle exists at its address (the draft row, for
+     * `mode: 'draft'`). A create sends it, and so does the first draft save of an
+     * item with no pending draft; the door refuses it `409 METADATA_CONFLICT`,
+     * carrying the existing row's `currentVersion`, when such a row is there.
+     *
+     * `'*'` alone: the door reads no other value. ⛔ Never together with
+     * {@link ifMatch} — the door refuses that pair `400`, and
+     * {@link MetadataClient.save} throws before sending it.
+     */
+    ifNoneMatch?: '*';
     /**
      * Bypass destructive-change protection (Phase 3a). The server returns
      * `409 destructive_change` with `issues[]` if a write would drop or
@@ -177,6 +438,19 @@ interface MetadataClientSaveOptions {
      * Studio package workspace. Omit for an env-local overlay.
      */
     packageId?: string;
+    /**
+     * The authoring surface this save is made through (objectui#12725), sent as
+     * `?surface=`. A draft save stamps it as `by` on every key path it changes,
+     * the entries the strict draft read serves as `draftChanges`; absent, the
+     * framework stamps `api`. Studio's own saves send `'studio'`, so a person's
+     * edit there is told apart from the AI copilot's (objectstack#24395).
+     *
+     * DERIVED from the spec's authoring-surface set (the one `draftChanges[].by`
+     * reports, `MetadataAuthoringSurface`), minus `'copilot'`: the HTTP doors
+     * refuse `?surface=copilot` `400` (only an in-process tool may state it), so
+     * this client cannot send it. Omit for any other caller.
+     */
+    surface?: Exclude<DraftChange['by'], 'copilot'>;
 }
 interface MetadataGetOptions {
     /**
@@ -193,7 +467,7 @@ interface MetadataGetOptions {
      */
     packageId?: string;
 }
-interface MetadataDeleteOptions extends MetadataClientSaveOptions {
+interface MetadataDeleteOptions extends Omit<MetadataClientSaveOptions, 'surface'> {
     /**
      * Target state. `'draft'` discards the pending draft (keeps the
      * published overlay intact). Omit to reset the active overlay back
@@ -202,12 +476,13 @@ interface MetadataDeleteOptions extends MetadataClientSaveOptions {
     state?: 'active' | 'draft';
 }
 /**
- * Which layer an overlay was saved at — `'org'` for a tenant overlay, `'env'`
- * for an environment-level one, `null` exactly when `overlay` is null.
+ * Which layer an overlay was saved at — `'env'` for an environment-level one,
+ * `null` exactly when `overlay` is null. Every metadata read is environment →
+ * code since objectstack#15206 S5, which retired the `'org'` tenant scope.
  *
  * DERIVED from `@objectstack/spec`, not restated: the vocabulary lives once, in
  * `GetMetaItemLayeredResponseSchema`'s `overlayScope`
- * (`z.enum(['org', 'env']).nullable()`), and this alias indexes the published
+ * (`z.enum(['env']).nullable()`), and this alias indexes the published
  * response type so a scope the spec adds arrives here with no edit. Restating
  * the union locally is the fork `scripts/check-spec-symbol-derivation.mjs`
  * exists to reject, and the mirror-image mistake — a consumer re-spelling a
@@ -246,9 +521,13 @@ type MetadataOverlayScope = GetMetaItemLayeredResponse['overlayScope'];
  * the cross-repo half of the drift, not just the in-repo half.
  *
  * ⚠️ This types what this repo may WRITE. It does NOT constrain what a server
- * may SEND: {@link MetadataClient.layered} casts the wire value through
- * unchecked, so every reader must still handle a value outside these four. The
- * lock banner in `ResourceEditPage` is the worked example.
+ * may SEND, and it never will — {@link MetadataClient.layered} forwards the
+ * wire value rather than dropping it, so every reader must still handle a value
+ * outside these four. What changed in objectui#5676 is that the value is no
+ * longer forwarded *silently*: the boundary validates it against the producer's
+ * own schema and names the field in {@link MetadataLayered._unrecognized} when
+ * it does not match. The lock banner in `ResourceEditPage` is the worked
+ * example of a reader that labels such a value instead of rendering it blank.
  */
 type MetadataLockState = GetMetaItemLayeredResponse['lock'];
 /**
@@ -299,6 +578,21 @@ interface MetadataLayered<T = unknown> {
     deletable?: boolean;
     /** True when "Reset to package default" applies (has overlay + artifact). */
     resettable?: boolean;
+    /**
+     * Protection-envelope keys whose wire value did NOT match `packages/spec`'s
+     * schema for them (objectui#5676). Computed HERE, at the boundary — the
+     * server never sends this key, and {@link MetadataClient.layered} builds the
+     * returned object field by field, so a server that tried could not smuggle
+     * one in.
+     *
+     * Absent when everything the server sent parsed, so its presence is the
+     * signal. The offending values are still forwarded on the fields themselves:
+     * this is "pass through and label", the treatment objectui#5672 chose for
+     * `lock` alone, applied to the whole ADR-0010 envelope. Dropping them would
+     * be the reject semantics that card refused — turning a wrong render into no
+     * render is a behaviour change for every consumer of this client.
+     */
+    _unrecognized?: readonly string[];
 }
 /**
  * One row in the metadata protection-audit trail
@@ -443,7 +737,7 @@ declare class MetadataClient {
     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. */
+    /** #4133 / #5026 — sink for every write door's advisory findings; see the config field. */
     private readonly onSaveAdvisory;
     constructor(config: MetadataClientConfig);
     /** Update the client's environment scope at runtime. */
@@ -454,10 +748,51 @@ declare class MetadataClient {
      * renderer tree into ADR-0037 preview mode off one URL flag.
      */
     withPreviewDrafts(previewDrafts: boolean): MetadataClient;
+    /**
+     * Share one in-flight GET among the callers asking the same method for the
+     * same URL with the same headers through the same transport (objectui#11797).
+     *
+     * Opening a Studio package mounts several readers that ask the same
+     * question at once, and each one sent its own request. The first call for a
+     * key sends `read()`; a call that arrives while it is pending waits for that
+     * request instead of sending another.
+     *
+     * ⛔ Not a response cache, deliberately — the rules `findOne` keeps on the
+     * data adapter (objectui#11699):
+     *  - the entry goes the moment the read settles, so a call made after an
+     *    answer always reaches the network (there is no reuse window: a client
+     *    cannot see every write that changes metadata, an agent's server-side
+     *    edits among them, and a window would answer the read after such a write
+     *    with the state from before it);
+     *  - a rejection reaches every caller already waiting and is not remembered;
+     *  - a write sent through the same transport drops every pending read when
+     *    it lands (see {@link sendWrite}), so a read asked after a save or a
+     *    publish is never answered by a request sent before it;
+     *  - every caller, the first one included, gets an answer no other caller
+     *    holds (see {@link handOut}).
+     */
+    private shareRead;
+    /**
+     * Send a write, then drop every read still pending on this transport
+     * (objectui#11797): a read on the wire when the write lands was asked before
+     * it, so a caller asking after the write must not join it. Dropped however
+     * the write ends — a refused or interrupted write may still have changed
+     * something. The callers already holding a pending read keep its answer.
+     */
+    private sendWrite;
     /** 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[]>;
+    /**
+     * The same list read as {@link list}, with what the server serves beside
+     * the items (objectui#12349): today that is the automation engine's
+     * `registrations` on a `flow` list — see {@link MetadataListAnswer}.
+     *
+     * One request for both methods: `list` is this read with the items picked
+     * out, so a caller asking both at once shares one in-flight GET.
+     */
+    listResponse<T = unknown>(type: string, options?: MetadataListOptions): Promise<MetadataListAnswer<T>>;
     /**
      * List pending DRAFT items (ADR-0033) — what an AI authored but nobody
      * published yet. `list()` only sees published/active metadata, so a
@@ -517,12 +852,71 @@ declare class MetadataClient {
      * {@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.
+     * `get()`'s unwrap.
+     *
+     * ⛔ Do NOT hand `.item` to a gate or a write yourself: the body this serves
+     * is DECORATED (`_draft`, then `_diagnostics` from `decorateMetadataItem`),
+     * and the spec says a served body is not a valid input to the schema that
+     * produced it until those come off. {@link extractDraftBody} is the one
+     * reader for this method's answer — it takes the presence verdict and then
+     * the strip, in that order. That function used to be copy-pasted into four
+     * views and only one copy knew the rule (objectui#8181).
+     *
+     * Its tolerant siblings exist for the OTHER client method: `unwrapDraftBody`
+     * (app-shell) and `unwrapViewDraft` (this package) read a draft that arrived
+     * through {@link get}, which already unwrapped the envelope. They split on
+     * which method feeds them, not on what they mean — all three strip.
+     *
+     * objectui#11799 — whether a draft exists is answered by the pending-drafts
+     * ledger first (see {@link draftLedgerMayHold}), and `?state=draft` is sent
+     * only when the ledger lists the name. The item read answers 404 when there
+     * is no draft, so opening every item in Studio used to log one error per
+     * item for an answer the ledger gives with a 200.
      */
     getDraft<T = unknown>(type: string, name: string, options?: {
         packageId?: string;
     }): Promise<T | null>;
+    /**
+     * Whether the pending-drafts ledger (`GET /meta/_drafts`) may hold a draft
+     * named `name` (objectui#11799).
+     *
+     * Read through {@link listDrafts}, the shared read objectui#11797 made: a
+     * question asked while a ledger read is pending waits for it, and a write
+     * through this transport drops it when the write lands ({@link sendWrite}),
+     * so a draft saved a moment ago is never reported absent by a read sent
+     * before the save.
+     *
+     * The WHOLE ledger, matched by name. The `?state=draft` read finds a row
+     * under either spelling of the type, and, when it names a package, that
+     * package's row or the package-less one. The ledger's `type` and `packageId`
+     * filters are exact, so a filtered ledger could miss a draft the item read
+     * would serve, and the editor would open the published body over a pending
+     * draft. Unfiltered, every miss here is a real absence; a same-name row of
+     * another type or package only costs the item read that was always sent.
+     *
+     * A ledger that cannot be read (403 without an authoring capability, 501 on
+     * a kernel without drafts, a network fault) is UNKNOWN, not empty: the item
+     * read is sent, as before.
+     */
+    private draftLedgerMayHold;
+    /**
+     * Report the runtime authoring gate's advisory findings for a write the
+     * server has ALREADY committed (#4133 for the save door, #5026 for the
+     * publish door).
+     *
+     * Everything here is best-effort by construction, and that is the whole
+     * contract: the row is committed server-side before this runs, so neither a
+     * malformed body, nor a missing key, nor a throwing sink may change what the
+     * calling method returns or whether it throws. The server emits `advisories`
+     * ONLY when non-empty, so a clean write costs one absent-key check.
+     *
+     * One helper rather than a copy per door: every door's response declares the
+     * key identically, so a second inline copy could only ever drift. The batch
+     * door (`ce986aafc`) calls it once per `published[]` element, handing it
+     * the element — the object that carries the key there — and the same
+     * best-effort contract covers that loop unchanged.
+     */
+    private emitAdvisories;
     /**
      * Save (PUT) a metadata item. The framework accepts both the bare
      * item payload and the `{ item: ... }` / `{ metadata: ... }`
@@ -541,8 +935,77 @@ declare class MetadataClient {
      * 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.
+     *
+     * Same door as {@link publish} (`POST /meta/:type/:name/publish`), so it
+     * reports the gate's advisories the same way (#5026).
+     *
+     * The BATCH door (`POST /packages/:id/publish-drafts`) is a different route
+     * with a method of its own — {@link publishPackageDrafts} — and it reports
+     * too. It did not when this paragraph was first written: it discarded
+     * per-draft advisories server-side, which was objectstack#9343, and that card
+     * has since landed with a ruling that each `published[]` element carries
+     * them (`ce986aafc` is the client half).
+     *
+     * What survives that change is the READING RULE, which is about this method
+     * rather than about the other route: it reads the top level of the
+     * single-item body and nothing else. A batch-shaped body arriving HERE still
+     * reports nothing, because `PublishMetaItemResponse` declares no
+     * `published[]` and a client that went looking for findings wherever they
+     * might be would be inventing a contract instead of reading one.
+     *
+     * ## Why there is no `{ success, data }` unwrapping here (`7b433197d`)
+     *
+     * This method used to unwrap a dispatcher-shaped envelope before returning,
+     * while {@link publish} — the same route, a couple of hundred lines down —
+     * did not. Two spellings of one wire contract, and nothing said which was
+     * right. The tolerance is gone because the route was MEASURED, at the
+     * producer rather than inferred from the response schema:
+     *
+     *  - The only mount of `POST /api/v1/meta/:type/:name/publish` is the REST
+     *    server's own route-manager registration, which answers
+     *    `res.json(await protocol.publishMetaItem(...))` — the protocol's object
+     *    verbatim, with no envelope branch. The project-scoped mirror
+     *    (`/api/v1/environments/:environmentId/...`) re-mounts that same handler.
+     *  - The `{ success, data }` envelope has exactly one producer, the runtime
+     *    `HttpDispatcher`, and it does not serve this route: its `/meta` domain
+     *    has no publish branch, the dispatcher's own route ledger has no row for
+     *    it, and a three-segment `/meta` path that is not `/published` terminates
+     *    in a located `routeNotFound`. So no composition — REST server, the
+     *    dispatcher-only Hono adapter, or both — puts an envelope on this body.
+     *  - `packages/spec` states the same split in the two docstrings side by
+     *    side: `PublishMetaItemResponseSchema` describes "the FULL body" this
+     *    route returns and records that the REST route hands the producer's
+     *    object to `res.json()` verbatim, while its batch sibling
+     *    `PublishPackageDraftsResponseSchema` describes a body answered
+     *    explicitly "inside the dispatcher's `{ success, data }` envelope".
+     *
+     * ⛔ So an enveloped body on THIS route is not a shape the platform emits,
+     * and unwrapping one is not a kindness: it is Commandment #0.1's lenient
+     * fallback, a second de-facto contract for a route that declares one. It
+     * also fails in the direction that hides the problem — a body that arrived
+     * enveloped is one this door did not actually serve, and unwrapping it
+     * would present that as a successful promotion.
+     *
+     * ⚠️ Sibling tolerances in this file are NOT this defect and must stay:
+     * {@link listDrafts} reads `data?.data?.drafts` because `GET /meta/_drafts`
+     * IS a dispatcher route, and `publishHealthFromResponse` unwraps because the
+     * batch door really is enveloped. The rule is per-route, not per-file.
+     *
+     * ## The bundle member (objectui#12402)
+     *
+     * Pass `member` to publish one member of a type whose identity is a pair
+     * (today only `email_template`, `(name, locale)`), sent as `?member=` — the
+     * selector the by-name doors read since objectstack `038d4c958`, and the
+     * value a `GET /meta/_drafts` row carries as `member`. A publish that names
+     * none promotes the CANONICAL member's draft, so two languages of one
+     * template drafted outside a package cannot both be published by name
+     * without it. The parameter is OMITTED, never sent empty, when the caller
+     * has no member: the door refuses a blank selector, and refuses any
+     * selector on a type with no members.
      */
-    publishDraft(type: string, name: string): Promise<{
+    publishDraft(type: string, name: string, options?: {
+        member?: string;
+    }): Promise<{
         success?: boolean;
         seedApplied?: {
             success: boolean;
@@ -552,6 +1015,63 @@ declare class MetadataClient {
             errors?: unknown[];
         };
     } & Record<string, unknown>>;
+    /**
+     * Publish EVERY pending draft bound to one package — Studio's "publish whole
+     * app" door, `POST /api/v1/packages/:id/publish-drafts` (ADR-0033; the route
+     * that orders structure-before-seeds server-side and runs the ADR-0038 L3
+     * runtime probes).
+     *
+     * ## Why it is expressed here at all (`ce986aafc`)
+     *
+     * It was not, and that was the defect. Two app-shell call sites fired this
+     * route with a bare `fetch` / a page-private `apiJson`, outside the seam that
+     * covers every other metadata write — so when objectstack#9343 landed and the
+     * server began sending per-draft advisories, the author publishing a whole
+     * app was told nothing, while the SAME button's client-side capability lint
+     * still raised a toast. A door that cannot report is not a door the gate can
+     * reach, however loudly the server speaks.
+     *
+     * ## What it reports, and what it refuses to invent
+     *
+     * `PublishPackageDraftsResponseSchema` declares `advisories` on EACH
+     * `published[]` element — objectstack#9343's ruled shape, the same element
+     * type and the same omitted-when-empty discipline as the single-item door,
+     * and explicitly not a parallel top-level map. So this method emits one
+     * {@link MetadataSaveAdvisoryEvent} per advised element, each naming that
+     * element's own `type` / `name`, through the same sink, event and renderer
+     * the save and single-item publish doors use.
+     *
+     * ⛔ It renders only what the server sent where the schema says it sits:
+     *
+     * - `advisories` is read off the element, by the one shared reader, which
+     *   drops anything that is not a complete finding.
+     * - An element that does not carry the `type` and `name` the schema states as
+     *   REQUIRED is skipped rather than reported under invented identity — the
+     *   event names the item the author has to go fix, and an event that cannot
+     *   name it truthfully is worse than silence.
+     * - Nothing is derived, counted or summarised from the batch: no advisory
+     *   exists here that the server did not put in the body.
+     *
+     * ## The failure shapes stay the callers'
+     *
+     * Non-2xx throws {@link MetadataError}, like every other method. A 2xx is
+     * RETURNED unexamined — `success: false` is not a failure on this route
+     * (`outcome: 'nothing_to_publish'` answers it too, and the spec's own text
+     * says to read `outcome`, not the boolean), and the two callers have their
+     * own, different rules for the refusal and rolled-back cases. Deciding that
+     * here would change behaviour this card is not about.
+     *
+     * ## The opt-in backfill (objectui#12929)
+     *
+     * `options.backfill` is sent as the body's `backfill` key, as given, and only
+     * when the caller passes one ({@link MetadataPublishPackageDraftsOptions}).
+     * Without it the body is `{}`, byte for byte what every caller sent before,
+     * so a caller that names nothing writes nothing into existing rows. The
+     * receipt is `backfillApplied` on the returned body, unexamined like the rest
+     * of a 2xx: one element per named field with the rows written, and `error`
+     * on a field that stopped short (the publish itself stands).
+     */
+    publishPackageDrafts(packageId: string, options?: MetadataPublishPackageDraftsOptions): Promise<MetadataPublishPackageDraftsResult>;
     /**
      * Get the 3-state layered view of a metadata item: `code` (the packaged
      * artifact baseline), `overlay` (the tenant customisation row alone) and
@@ -607,6 +1127,12 @@ declare class MetadataClient {
      * 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.
+     *
+     * Pass `packageId` to name the package whose row the delete removes, sent
+     * as `?package=`. A delete that names none addresses the one package that
+     * holds the item; when two or more packages hold it the door refuses it
+     * `409 RESOURCE_CONFLICT`, deletes nothing, and names `?package=` as the
+     * remedy. That refusal is thrown like any other {@link MetadataError}.
      */
     reset<T = unknown>(type: string, name: string, options?: MetadataDeleteOptions): Promise<T>;
     /**
@@ -615,9 +1141,16 @@ declare class MetadataClient {
      * `{ 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.
+     *
+     * Reports the runtime authoring gate's advisory findings through
+     * {@link MetadataClientConfig.onSaveAdvisory} when the response carries them
+     * (#5026 / objectstack#9176), with `door: 'publish'`. This is the door the
+     * Studio designer takes on every edit, so it is the one whose findings an
+     * author actually sees.
      */
     publish<T = unknown>(type: string, name: string, options?: {
         message?: string;
+        packageId?: string;
     }): Promise<T>;
     /**
      * Restore an item to a previous version (POST `/meta/:type/:name/rollback`).
@@ -877,6 +1410,35 @@ interface MetadataCacheStats {
  * As soon as the backend supports `sys_user_preference`, persistence
  * "lights up" with no code change.
  *
+ * ## One read per load (objectui#12187)
+ *
+ * The console builds one adapter per slot (favorites, recent items, flow
+ * palette recents) over the same data source and user, and their providers
+ * call `load()` in the same effects pass. Those loads share ONE request: the
+ * first `load()` opens a read for its (data source, resource, user), every
+ * `load()` of that scope issued before the next microtask adds its key to it,
+ * and the read is then sent once and each adapter takes its own row from the
+ * answer. A read that collected one key sends the per-key query this adapter
+ * always sent; several keys go as one `key in (...)` query.
+ *
+ * Nothing is kept past that: the read closes the moment it is sent, so a later
+ * `load()` (a new adapter after a language or account switch) asks the server
+ * again, and a different user or data source never joins another's read.
+ * `save()` does not use it: a write still finds and writes its own row.
+ *
+ * ## A family of keys in the same read (objectui#12418)
+ *
+ * Some state is one row per subject the console cannot name at load time: the
+ * list state of every object a user has opened is a row per object,
+ * `ui.list.<object>`, and which objects those are is only known from the rows
+ * themselves. {@link createObjectStackUserPreferenceFamily} loads such a family
+ * by its key PREFIX, and joins the same shared read: the read then asks for its
+ * keys OR any key starting with the prefix, still one request. A prefix bounds
+ * nothing the way the unique index bounds a key, so the read asks for at most
+ * {@link PREFERENCE_FAMILY_ROW_LIMIT} family rows on top of its keys; an
+ * answer that fills that limit may have left a key's row out, and such a key
+ * asks for its own row instead (the same fallback an untagged row takes).
+ *
  * @module
  */
 
@@ -899,10 +1461,31 @@ interface ObjectStackUserStateAdapterOptions {
      */
     onError?: (where: 'load' | 'save', error: unknown) => void;
 }
+/**
+ * Generic persistence adapter for a user-scoped list.
+ *
+ * Implementations must be safe to call concurrently and should *never*
+ * throw — failures should be swallowed so the hosting provider can degrade
+ * to localStorage-only mode without crashing the UI.
+ *
+ * This is the one declaration of the name: `@object-ui/app-shell`'s
+ * `UserStateAdaptersProvider` injects adapters of this type and re-exports it
+ * (objectui#6349, batch 9).
+ */
 interface UserDataAdapter<T> {
+    /** Load the persisted list for the current user. Resolve to [] when absent. */
     load(): Promise<T[]>;
+    /** Persist the full list (debounced upstream). Errors are silently ignored. */
     save(items: T[]): Promise<void>;
 }
+/**
+ * How many rows of one key family a shared read asks for (objectui#12418).
+ * The unique index bounds a KEY to one row; nothing bounds a prefix, so the
+ * read's `$top` is its key count plus this many rows per family. An answer
+ * that reaches its `$top` is read as possibly cut short: see
+ * {@link SharedAnswer.saturated}.
+ */
+declare const PREFERENCE_FAMILY_ROW_LIMIT = 200;
 /**
  * Build a `UserDataAdapter<T>` backed by ObjectStack.
  *
@@ -910,6 +1493,290 @@ interface UserDataAdapter<T> {
  * one per slot you want to persist.
  */
 declare function createObjectStackUserStateAdapter<T = unknown>(options: ObjectStackUserStateAdapterOptions): UserDataAdapter<T>;
+interface ObjectStackUserPreferenceFamilyOptions {
+    /** Connected data source (usually the one provided by `<AdapterProvider>`). */
+    dataSource: DataSource<any>;
+    /** Authenticated user id. */
+    userId: string;
+    /**
+     * The family's key prefix, dotted and ending in a dot, e.g. `ui.list.`: the
+     * family is every key that starts with it, one row per subject
+     * (`ui.list.account`, `ui.list.contact`, …).
+     */
+    prefix: string;
+    /** Override the storage object name. Defaults to `"sys_user_preference"`. */
+    resource?: string;
+    /** Optional diagnostics hook; defaults to noop. */
+    onError?: (where: 'load' | 'save', error: unknown) => void;
+}
+/**
+ * A user's rows of one key family: every `sys_user_preference` row whose key
+ * starts with the family's prefix, each holding one JSON object.
+ *
+ * Same contract as {@link UserDataAdapter}: never throws; a failed read loads
+ * as no rows and a failed write is reported to `onError` and swallowed, so
+ * the hosting provider keeps its localStorage state.
+ */
+interface UserPreferenceFamily<T> {
+    /** The key prefix this family covers. */
+    readonly prefix: string;
+    /**
+     * Load every row of the family, joining the shared read of the load
+     * (one request with the slots' keys). Resolves to `{ [key]: value }`, with
+     * only the rows whose value is a JSON object; `{}` when there are none.
+     */
+    load(): Promise<Record<string, T>>;
+    /**
+     * Upsert one key's row. A key outside the family is refused (reported to
+     * `onError`, nothing written). Writes to one key run in order.
+     */
+    save(key: string, value: T): Promise<void>;
+}
+/**
+ * Build a {@link UserPreferenceFamily} backed by ObjectStack: one row per key,
+ * loaded together by prefix in the shared read (see the module header), each
+ * written with the same upsert a single-key adapter uses.
+ */
+declare function createObjectStackUserPreferenceFamily<T extends object = Record<string, unknown>>(options: ObjectStackUserPreferenceFamilyOptions): UserPreferenceFamily<T>;
+
+/**
+ * The served form of a picklist-bound field, turned back into the authored
+ * form before a writer that seeded its body from a served read PUTs it
+ * (objectui#10202, objectui#11692).
+ *
+ * ## Why the writer has to do this
+ *
+ * A select field may name a shared list instead of carrying its own options:
+ * `picklist: 'industry'` (`FieldSchema.picklist`, `@objectstack/spec`
+ * `data/picklist.zod.ts`). The runtime serves such a field with BOTH keys:
+ * `picklist`, still naming the list, and `options`, RESOLVED from that list and
+ * from every `picklistExtensions` entry other packages add to it
+ * (`PicklistServedFieldSchema`). Every object read carries that served form —
+ * the object list `GET /meta/object`, `GET /meta/object/NAME`, and the
+ * `effective` layer of `GET /meta/object/NAME/layers` alike, because the
+ * runtime resolves the binding in the one fold all three share.
+ *
+ * The authoring door refuses the two keys together: `FieldSchema` adds an issue
+ * at `fields.FIELD.options` whose prescription is "Keep `picklist` and delete
+ * `options`". So a writer that sends its seed back unchanged gets
+ * `422 INVALID_METADATA` for the whole object, whatever the author edited —
+ * an OWD batch edit, a relabel, a field reorder, anything.
+ * The resolved list belongs to the picklist, not to the field: the producer of
+ * the PUT drops it (objectstack's producer obligation, pinned server-side in
+ * `protocol-picklist-served-roundtrip.test.ts`).
+ *
+ * ## What this changes, and what it never touches
+ *
+ * EVERY field that names a picklist leaves without `options` — not only the one
+ * the author edited, because the whole document is re-sent and any bound field
+ * in it is refused. A field that names no picklist is not touched at all: its
+ * inline `options` stay byte-identical. No other key of any field, and no key of
+ * the document, is touched.
+ *
+ * "Names a picklist" is the spec's own test, `picklist !== undefined` (the
+ * `FieldSchema` refinement), so this drops `options` on exactly the fields the
+ * door would refuse for carrying both.
+ *
+ * Both `fields` shapes a document can carry are handled: the spec's record keyed
+ * by field name, and the array `readFields` / `writeFields` round-trip for a
+ * document that arrived that way.
+ *
+ * ⛔ Not at the transport. `MetadataClient.save` and the other metadata-write
+ * doors cannot tell a served copy from an author who wrote both keys, and the
+ * second must stay a loud refusal with its prescription. The writer can tell:
+ * it seeded its body from the served read. So this is exported for WRITERS —
+ * the opposite of `assertObjectMetadataWritable`, which is exported for doors —
+ * and the rule each writer applies is one sentence: a body seeded from a served
+ * object read goes through this function on its way to the PUT; a body built
+ * from the author's own input does not.
+ *
+ * ## Why it lives in this package (objectui#11692)
+ *
+ * The writers that seed from a served read are not all in one package: the
+ * Studio and metadata-admin surfaces live in `@object-ui/app-shell`, and the
+ * Setup fields and objects pages in `@object-ui/plugin-designer`, which does
+ * not depend on `app-shell`. Both depend on this package, which also owns the
+ * client that serves the read and carries the write — the same reason
+ * `extractDraftBody` lives here. One function, not one copy per package: a
+ * second copy is free to drift from the spec's served shape on its own.
+ *
+ * Pure: the input is never mutated, and a document with nothing to drop comes
+ * back BY REFERENCE, so a caller can tell "unchanged" by identity.
+ */
+declare function dropServedPicklistOptions<T extends Record<string, unknown>>(body: T): T;
+
+/**
+ * One issue → a single field-anchored line: `• fields.amount.type — Required`.
+ *
+ * Exported so a caller that formats a LIST of failures — `app-shell`'s publish
+ * formatter, whose `failed[]` entries carry their own `issues` — writes each
+ * issue in this same grammar instead of keeping a second copy of it.
+ */
+declare function formatMetadataIssue(i: MetadataValidationIssue): string;
+/**
+ * Format a caught save/publish error for a banner/toast. When the error carries
+ * spec-validation issues, list them (one field per line) so the user sees the
+ * offending fields and what to do about them; otherwise fall back to the plain
+ * message.
+ */
+declare function formatMetadataError(e: unknown): string;
+
+/**
+ * The object-metadata write invariant, placed at the DOOR rather than at the
+ * writers (objectui#8676).
+ *
+ * ## Why this module exists — the enumeration, not the count
+ *
+ * objectui#7714 ruled one client behaviour: *a half-filled relationship stays
+ * client-side and the PUT body never carries a `lookup` without a non-empty
+ * `reference`*. Its PR implemented that ruling by naming the writers it knew
+ * about — two of them — and putting the assertion inside each one's array-to-map
+ * conversion (`toFieldsMap`). The very failure the ruling was written against
+ * was then reproduced on a THIRD writer neither conversion covers, in that
+ * card's own required dogfood (fixed in `9073cf018`). objectui#8676 swept and
+ * found nine more.
+ *
+ * The durable half of that card is a sentence about method, not a number:
+ *
+ * > a ruling that enumerates writers is only as good as the enumeration.
+ *
+ * A hand list of writers is stale the next time somebody adds one, and nothing
+ * says so. So this invariant is not attached to writers at all. It is attached
+ * to the DOORS — the places that put bytes on the wire — because the doors are a
+ * CLOSED set that this repository owns, while the writers are an OPEN set it
+ * does not. Three in-repo transports can PUT `/meta/:type/:name`, and
+ * `scripts/check-object-metadata-write-doors.mjs` derives that set on every run
+ * rather than restating it:
+ *
+ *   1. `MetadataClient.save`           `packages/data-objectstack/src/metadata-client.ts`
+ *   2. `importObjectDraft`             `packages/app-shell/src/views/metadata-admin/external/api.ts`
+ *   3. the `@objectstack/client` SDK's `meta.saveItem`, reached in this repo
+ *      through `MetadataService`'s one seam
+ *
+ * Every writer in the repo reaches the server through one of those three. Guard
+ * them and the writer count stops mattering; add a fourth transport and the gate
+ * turns red naming it. That is the whole design: ⛔ do not re-open this by
+ * adding a writer list anywhere.
+ *
+ * ## What it asserts, and the two things it deliberately does NOT
+ *
+ * It asserts two field-level invariants, and nothing else:
+ *
+ *   - objectui#7714's: a relationship (`lookup` / `master_detail`) carries a
+ *     usable `reference`;
+ *   - objectui#11253's: a choice (`select` / `radio`) carries an option source,
+ *     a non-empty `options` list or a shared `picklist`. This is the objectui
+ *     branch of the maintainer's ruling A on objectstack#20827, whose door
+ *     refuses "a `select` / `radio` with neither `options` nor `picklist`".
+ *
+ * ⛔ **NOT a client-side revalidation of the document.** Parsing the whole body
+ * through `ObjectSchema` before the PUT would refuse plugin-registered keys the
+ * SERVER accepts, and it would promote a client PREDICTION into a block — which
+ * is exactly what objectui#4306 / objectui#6980 ruled against for the designer's
+ * live Zod pass, on the stated ground that a schema issue on a draft the server
+ * ACCEPTS would dead-bolt Save with no on-screen editor able to clear it.
+ *
+ * Neither invariant forecloses anything the server would have taken, and that
+ * is the whole of the dead-bolt argument for both:
+ *
+ *   - The relationship refusal: the same body is refused one layer down with a
+ *     422 on `fields.NAME.reference`, so the guard only moves an identical
+ *     refusal earlier, where it can name the field while it is still on screen.
+ *   - The choice refusal: the same body is refused one layer down at
+ *     `fields.NAME.options`, an empty list included, since `@objectstack/spec`
+ *     17.7.0 shipped the door (objectstack#21390, the ruling's own door). Until
+ *     that release the installed spec still accepted a choice with no option
+ *     source and this refusal was deliberately AHEAD of the server, by the
+ *     ruling's execution parameter (2): "if Studio saves a `select` before its
+ *     options exist, the objectui side changes its order first (a card in that
+ *     lane) and the door closes after". The door has closed, the order changed
+ *     first, and the refusal collapsed into the relationship form at
+ *     objectui#11717's bump. The editors still clear it on screen: the Studio
+ *     data page and the metadata-admin object editor carry an options editor in
+ *     that field's inspector (both pinned by their
+ *     `*.choiceWithoutOptions-11253` suites); plugin-designer's drawer has no
+ *     options editor, so it stops offering the choice types, a stored `select`
+ *     keeps its type there and can be retyped or removed, and a stored `radio`
+ *     is among the types that page carries through unedited and sends to
+ *     metadata-admin, as it already does for a target-less `master_detail`.
+ *     `object-metadata-write-guard.derivation.test.ts` re-measures "refused one
+ *     layer down" for both invariants on every run.
+ *
+ * ⛔ **NOT strip-and-report-saved.** Dropping the offending field and reporting
+ * success would trade a visible refusal for an invisible deletion —
+ * objectstack#4001's shape, ruled out for this family in objectui#7714 and again
+ * in `9073cf018`. It throws; the caller surfaces the message.
+ *
+ * ## The type lists are pinned to the contract, not to memory
+ *
+ * {@link RELATIONSHIP_TYPES_REQUIRING_REFERENCE} and
+ * {@link CHOICE_TYPES_REQUIRING_OPTIONS} are the two lists this module keeps,
+ * and they are the same class of hazard the module exists to close, so neither
+ * gets to be a remembered list either.
+ * `object-metadata-write-guard.derivation.test.ts` DERIVES both from the
+ * installed `@objectstack/spec`:
+ *
+ *   - the relationship set from every member of `FieldType`, parsed as
+ *     `{ type, label }` through `FieldSchema`, keeping those refused at path
+ *     `reference`;
+ *   - the choice set from the same members run through `checkFieldCompleteness`
+ *     (ADR-0078's author-time rule, which the ruling's door adopts), keeping
+ *     those it reports as `field/choice-without-options` at `error` severity.
+ *     The door itself shipped in 17.7.0, and the pin holds the two answers equal.
+ *
+ * A spec release that changes either set turns that pin red instead of leaving
+ * a guard that quietly stopped covering the contract.
+ *
+ * The derivation is a TEST and not a runtime probe on purpose: parsing 50
+ * field-type documents on the way to every save is a cost paid on the hot path
+ * to re-learn something that changes at most once per spec release, and a probe
+ * that throws at runtime has to choose between blocking writes and failing open.
+ * A pin has neither problem — it fails at CI time, loudly, with nothing at stake.
+ */
+/**
+ * Field types whose `reference` — the target object a relationship links to —
+ * `@objectstack/spec` requires to be present and non-empty.
+ *
+ * Derived from the installed artifact by the pin named above, never recalled.
+ */
+declare const RELATIONSHIP_TYPES_REQUIRING_REFERENCE: readonly string[];
+/**
+ * Field types that offer nothing to choose without an option source — a
+ * non-empty `options` list or a shared `picklist` (objectui#11253, the objectui
+ * branch of the maintainer's ruling A on objectstack#20827).
+ *
+ * Derived from the installed artifact by the pin named above, never recalled.
+ */
+declare const CHOICE_TYPES_REQUIRING_OPTIONS: readonly string[];
+/** The metadata type whose documents carry the `fields` map this guard reads. */
+declare const OBJECT_METADATA_TYPE = "object";
+/**
+ * Refuse an object-metadata write whose body carries a relationship field with
+ * no usable target, or a choice field with no option source.
+ *
+ * A no-op for every other metadata type and for any body with no readable
+ * `fields` member — this door serves `view`, `app`, `flow`, `permission`,
+ * `hook` and `dashboard` writes too, and has no opinion about them.
+ *
+ * ## The message is the same at every door, and names no code (objectui#11785)
+ *
+ * The thrown text reaches authors: Studio keeps it under a refusal's Details,
+ * and the other surfaces that save through a door show it as their banner. So
+ * it names the field, its type and the remedy, and ⛔ no class, package or
+ * tracker id. The rationale for each rule lives in this module's docblock, not
+ * in the runtime string. The door's label is not printed either, which makes the
+ * text a function of the body alone: a caller that kept the body it sent can
+ * re-run this guard on it and get the identical message, which is how Studio
+ * tells this refusal apart from any other failure without parsing the prose.
+ *
+ * @param type    the metadata type segment of the write (`'object'`, `'view'`, …)
+ * @param item    the body about to be serialised onto the wire
+ * @param _writer the door's label. Every door still names itself at the call,
+ *                and the stack trace says where the write stopped; the message
+ *                does not print it (see above)
+ * @throws Error naming the offending field, before any request is issued
+ */
+declare function assertObjectMetadataWritable(type: unknown, item: unknown, _writer: string): void;
 
 /**
  * Map human-readable filter operator names produced by SDUI view configs
@@ -947,6 +1814,156 @@ declare class MalformedFilterError extends Error {
 }
 /** Detect the malformed-filter refusal, whether raised here or by the server. */
 declare function isMalformedFilterError(error: unknown): boolean;
+/**
+ * A `where` that reached `aggregate()`'s SPEC-SHAPE branch as an array the spec
+ * cannot read as a filter — an unlowered `ViewFilterRule[]` above all.
+ *
+ * WHY THIS IS A REFUSAL AND NOT A LOWERING (objectui#6825, maintainer ruling
+ * 2026-08-30, option A). The two branches of `aggregate()` take a filter by
+ * different names: the analytics branch takes `filter` and lowers it through
+ * `translateFilterArray` (objectui#6302), the spec-shape branch takes `where`
+ * and posts it to `POST /data/:object/query` verbatim. Lowering here too was
+ * option B and was REFUSED: it is the tolerant-consumer direction AGENTS.md
+ * #0.1 exists to stop, and it would bless as supported a params shape
+ * `AggregateParams` does not even declare. Retiring the branch was option D and
+ * was refused as the riskier move — this repo has no producer that can reach it
+ * (`ObjectChart`'s gate requires a non-array `aggregate.groupBy`, and all three
+ * in-tree constructors pass a string), but `ObjectChart`'s props are `any` and
+ * an out-of-repo host may already send this shape. So the branch stays, and it
+ * says no out loud.
+ *
+ * What that buys is the FAILURE MODE, not a failure count. The receiving engine
+ * already refuses these arrays ("is not a filter" — objectstack's
+ * `engine-filter-array-lowering.test.ts`), so nothing that reaches this point
+ * could have produced a correct number; the pre-existing behaviour was to find
+ * that out on the wire, or worse, to have the predicate quietly dropped while
+ * the chart rendered confident, wrong figures with no signal to their author.
+ * This moves the same refusal to the producer, where the author can act on it.
+ *
+ * Carries the `INVALID_FILTER` / 400 pair its sibling {@link MalformedFilterError}
+ * carries, so `isMalformedFilterError()` recognises it and a failed widget renders
+ * "this filter is malformed" rather than "check your connection" (objectui#3066).
+ */
+declare class UnloweredAggregateWhereError extends Error {
+    readonly code = "INVALID_FILTER";
+    readonly httpStatus = 400;
+    /** The value as received, so a caller can log what its producer actually built. */
+    readonly where: unknown;
+    /** The object `aggregate()` was called for. */
+    readonly resource: string;
+    constructor(where: unknown, resource: string);
+}
+/**
+ * The keys `aggregate()`'s ANALYTICS branch reads and its SPEC-SHAPE branch does
+ * not: `filter`, `field`, `function`.
+ *
+ * Written out once, and read by both the refusal below and its message, so the
+ * set a caller is told about cannot drift from the set that is checked.
+ *
+ * ⛔ Deliberately NOT "every key the spec-shape branch does not read". A refusal
+ * scoped that widely would reject `orderBy`, a future spec key, or any harmless
+ * extra a host happens to carry, and it would satisfy a naive "the spec-shape
+ * branch refuses `filter`" test while breaking traffic nobody complained about.
+ * These three are named one by one because they are the OTHER branch's own
+ * parameters: their presence says the params were built for the analytics wire
+ * and arrived on the spec-shape one, which is a producer defect with a name.
+ */
+declare const ANALYTICS_ONLY_AGGREGATE_KEYS: readonly ["filter", "field", "function"];
+type AnalyticsOnlyAggregateKey = (typeof ANALYTICS_ONLY_AGGREGATE_KEYS)[number];
+/**
+ * Analytics-branch params — `filter`, `field`, `function` — that reached
+ * `aggregate()`'s SPEC-SHAPE branch, which reads none of them.
+ *
+ * WHY A REFUSAL AND NOT A DROP (`503cd8b89`). This applies the maintainer
+ * ruling of 2026-08-30 on objectui#6825 — option A, REFUSE at the producer — to
+ * the rest of the same branch. That ruling's reason was that a shape the spec's
+ * own gate would reject is off-contract at the PRODUCER, so the adapter says no
+ * instead of degrading leniently; the reason lands harder here, because a
+ * silent drop is precisely the disposition it refused for `where`. Leaving one
+ * key on this branch refusing while three others vanish without a word would be
+ * harder to explain than the old behaviour.
+ *
+ * ⭐ AND THE DROP HERE IS WORSE THAN THE `where` HALF. `filter` is not the only
+ * casualty: `field` and `function` are the analytics branch's whole measure, and
+ * the spec-shape branch copies a measure only out of `aggregations`. So the
+ * legacy shape `{ field, function, groupBy, filter }` whose `groupBy` happens to
+ * be an ARRAY produced a `queryAst` carrying a `groupBy` and NO `aggregations`
+ * at all — a grouping with no measure — with the author's predicate gone too.
+ * The chart still rendered, the numbers were wrong, and there was nothing to
+ * look at.
+ *
+ * HOW A LEGACY CALLER GETS HERE, measured in this repo on 2026-09-08.
+ * `Array.isArray(params.groupBy)` is one of `looksLikeSpecShape`'s three
+ * disjuncts, and `ObjectChart`'s `runAggregate` gates only on the STRUCTURED
+ * node shape (`gb && typeof gb === 'object' && !Array.isArray(gb)`), so an
+ * ARRAY `aggregate.groupBy` falls through to its legacy call — `{ field,
+ * function, groupBy, filter }` — and that call lands here.
+ * `ObjectMetricWidget.computeOne` forwards `aggregate.groupBy` the same way.
+ * Both take the value from authored widget metadata across an `any` seam
+ * (`isObjectProvider`'s `aggregate?: any`, `ds: any`), so the type system
+ * cannot refuse it and this runtime refusal is what an author gets instead.
+ *
+ * ⛔ WHAT THIS DELIBERATELY DOES NOT DO. It does not ROUTE the legacy shape back
+ * to the analytics branch: that is the tolerant-consumer direction AGENTS.md
+ * §0.1 exists to stop, it is the option #6825 refused for `where`, and it could
+ * not work anyway — the analytics branch posts `dimensions: [params.groupBy]`,
+ * so an array `groupBy` would go out nested. It does not widen `AggregateParams`
+ * (`@object-ui/types`), which is a separate contract question. And it does not
+ * refuse a key that is present but nullish: `undefined`/`null` carries nothing
+ * for the branch to drop, and both `ObjectChart` and `ObjectMetricWidget` build
+ * their params by spreading possibly-absent authored values.
+ *
+ * Carries the `INVALID_FILTER` / 400 pair its siblings {@link MalformedFilterError}
+ * and {@link UnloweredAggregateWhereError} carry, so `isMalformedFilterError()`
+ * recognises it and a failed widget renders "this filter is malformed" rather
+ * than "check your connection" (objectui#3066). One branch, one envelope: a
+ * caller can catch `aggregate()`'s producer-side refusals with one predicate.
+ */
+declare class AnalyticsKeysOnSpecShapeError extends Error {
+    readonly code = "INVALID_FILTER";
+    readonly httpStatus = 400;
+    /** The offending keys, in the order {@link ANALYTICS_ONLY_AGGREGATE_KEYS} lists them. */
+    readonly keys: readonly AnalyticsOnlyAggregateKey[];
+    /** What each offending key carried, so a producer is identifiable from a log. */
+    readonly received: Record<string, unknown>;
+    /** The object `aggregate()` was called for. */
+    readonly resource: string;
+    constructor(keys: readonly AnalyticsOnlyAggregateKey[], params: any, resource: string);
+}
+/**
+ * An ARRAY `filter` that reached `aggregate()`'s ANALYTICS branch and that the
+ * protocol's lowering sink cannot turn into a `FilterCondition` — an infix join
+ * (`[condA, 'or', condB]`) above all.
+ *
+ * WHY A REFUSAL AND NOT A DROP (objectui#7752; maintainer ruling of 2026-09-05
+ * on objectstack#15828, which reads that card as a frontend defect: the
+ * protocol is right and the adapter was wrong). `parseFilterAST` answers
+ * `undefined` for an array it cannot read, and `undefined` here would post a
+ * body with NO `where` at all: the aggregate would then be computed over every
+ * row and returned as a confident number, with the author's predicate gone and
+ * nothing on the wire to say it went. That is the same silent over-fetch
+ * {@link MalformedFilterError} exists to stop, one door further along.
+ *
+ * Deliberately NOT {@link UnloweredAggregateWhereError}, whose meaning is not
+ * widened to cover this: that one guards the SPEC-SHAPE branch, whose `where`
+ * is posted verbatim and must therefore have been lowered by its PRODUCER
+ * (objectui#6825, ruling 2026-08-30 option A — refuse, never lower). This
+ * branch's `filter` is authoring input and IS lowered here, at the door the
+ * protocol names; this error covers only the input that sink cannot lower.
+ *
+ * Carries the `INVALID_FILTER` / 400 pair both siblings carry, so
+ * `isMalformedFilterError()` recognises it and a failed widget renders "this
+ * filter is malformed" rather than "check your connection" (objectui#3066).
+ */
+declare class UnlowerableAnalyticsFilterError extends Error {
+    readonly code = "INVALID_FILTER";
+    readonly httpStatus = 400;
+    /** The filter as received, so a caller can log what its producer actually built. */
+    readonly filter: unknown;
+    /** The object `aggregate()` was called for. */
+    readonly resource: string;
+    constructor(filter: unknown, resource: string, detail?: string);
+}
 /**
  * Serialize a `$orderby` to the server's `sort` shorthand
  * (`field,-other_field`), for every shape `QueryParams['$orderby']` declares.
@@ -979,7 +1996,7 @@ declare function getSharedDiscovery(baseUrl: string, fetcher: () => Promise<unkn
 declare function clearSharedDiscoveryCache(): void;
 /**
  * Read the cross-object atomic-batch capability from a `discovery` document
- * (framework #3298 / objectui #2693). The server advertises it hierarchically
+ * (objectstack-ai/objectstack#3298 / objectui #2693). The server advertises it hierarchically
  * under `capabilities.transactionalBatch.enabled`; the published
  * `@objectstack/client` also accepts the flat `capabilities.transactionalBatch:
  * boolean` form and normalizes the two — mirror that here so the adapter reads
@@ -992,7 +2009,7 @@ declare function clearSharedDiscoveryCache(): void;
  *     real error.
  *   - `false` — the backend explicitly does NOT (route absent, or a runtime that
  *     can't open a transaction).
- *   - `undefined` — the capability is absent, i.e. the backend predates #3298;
+ *   - `undefined` — the capability is absent, i.e. the backend predates objectstack-ai/objectstack#3298;
  *     the caller must keep the legacy runtime-probe fallback (we can't tell
  *     whether `/batch` exists without trying it).
  */
@@ -1045,22 +2062,52 @@ declare const API_ACCESS_DENIED_CODES: readonly ["OBJECT_API_DISABLED", "OBJECT_
 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).
+ * (objectui#4252 / objectstack#8013, widened by objectui#9262).
  *
- *  - `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.
+ *  - `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.
+ *  - `not_found`   — the route answered, and what it answered is that it has no
+ *    app at this name for this session. WHICH absence it is — never created, a
+ *    typo, an unpublished draft, an app gated by an absent optional service —
+ *    is deliberately NOT distinguished: the control plane answers the same way
+ *    for every app the caller may not see, and the 2026-08-12 ruling keeps it
+ *    that way. A caller may say the app cannot be opened; it may never say why.
+ *  - `unreachable` — the probe could not obtain an answer at all: the transport
+ *    failed, the server erred, the request timed out. Says nothing about the
+ *    app.
+ *  - `unknown`     — nothing was measured, because nothing could be asked: a
+ *    host DataSource that does not implement this probe (the console is
+ *    protocol-agnostic — AGENTS #1), or no app name to ask about.
  *
- * 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.
+ * ## Why `not_found` and `unreachable` are separate members (objectui#9262)
+ *
+ * They were one `unknown` before, and the screen above them therefore asserted
+ * a transient publish state over both. The distinction is not new information
+ * to obtain — it is already on the wire, and folding it away was the defect.
+ * The maintainer ruling (2026-09-13) named the two members; this type is the
+ * two-member widening that ruling declared.
+ *
+ * ⚠️ `unknown` no longer means "absent". A consumer that treats `unknown` as a
+ * positive absence is reading a verdict that now means the opposite: that the
+ * question was never put.
+ */
+type AppAccessVerdict = 'granted' | 'denied' | 'not_found' | 'unreachable' | 'unknown';
+/**
+ * What {@link ObjectStackAdapter.probeMetaItemAccess} obtained about one item
+ * of any type the by-name meta route gates per caller (objectui#12112). The
+ * verdicts mean what they mean for an app ({@link AppAccessVerdict}).
  */
-type AppAccessVerdict = 'granted' | 'denied' | 'unknown';
+interface MetaItemAccess {
+    readonly verdict: AppAccessVerdict;
+    /**
+     * The refusal's own `message`, as the server wrote it — for a dashboard,
+     * `You do not have permission to open the 'NAME' dashboard.` Only on
+     * `denied`, and absent when the server wrote none.
+     */
+    readonly message?: string;
+}
 /**
  * The ADR-0112 standard catalog code the by-name meta app route answers with
  * when an app exists and the session lacks its `requiredPermissions`
@@ -1084,9 +2131,32 @@ declare const APP_PERMISSION_DENIED_CODE = "PERMISSION_DENIED";
  * are errors.
  */
 declare function isAppPermissionDeniedError(error: unknown): boolean;
+/**
+ * The ADR-0112 standard catalog code the metadata routes answer with when the
+ * named item is not there for this caller (`sendError(res, 404,
+ * 'RESOURCE_NOT_FOUND', …)` in `packages/rest/src/rest-server.ts`).
+ *
+ * One code covers every absence on purpose: a nonexistent name, an unpublished
+ * app (ADR-0045 §3 keeps it externally unobservable), and an app gated by an
+ * absent optional service (ADR-0057 D10 — nothing was denied to the CALLER) are
+ * one answer by the 2026-08-12 ruling's design, not three that happen to
+ * collide. Consumers may report the absence; they may not report a reason.
+ */
+declare const META_ITEM_ABSENT_CODE = "RESOURCE_NOT_FOUND";
+/**
+ * True when `error` is a metadata route's "not here for you" answer.
+ *
+ * Discriminates on the ADR-0112 `code`, never on the status, for the same
+ * reason {@link isAppPermissionDeniedError} does (objectui#4408): a 404 is a
+ * transport fact many conditions share — a mis-typed route, a proxy, an
+ * appliance in front of the server — while the code is the contract. A 404 that
+ * carries no declared code is NOT an absence: nobody said the item was missing,
+ * so the honest reading is that no answer was obtained.
+ */
+declare function isMetaItemAbsentError(error: unknown): boolean;
 /**
  * Thrown when the deployment has no analytics capability installed
- * (framework#3891 / #4019).
+ * (framework#3891 / objectstack-ai/objectstack#4019).
  *
  * The framework retired its degraded in-kernel analytics fallback — it dropped
  * the caller's RLS/tenant scope and ignored the contract filter, so it answered
@@ -1194,6 +2264,41 @@ declare class AnalyticsUnauthenticatedError extends Error {
         serverMessage?: string;
     });
 }
+/**
+ * Thrown when the dataset query was refused because this user may not READ an
+ * object the dataset queries — `403` + ADR-0112 `PERMISSION_DENIED`, which
+ * `@objectstack/service-analytics`' read admission (`readAdmissionDeniedError`)
+ * answers with the same code and status the data API gives the same user for
+ * the same object (objectui#10899).
+ *
+ * The FOURTH branch. It used to fall through to the generic
+ * `Dataset query failed: 403 Forbidden — [Analytics] Access denied: …` string,
+ * which a dashboard tile then rendered verbatim: a raw English exception where
+ * the list view over the same object shows its localized "no access" state.
+ * That generic string names a transport status where a person needs a fact
+ * ("you can't see this data"), and it is the one case a renderer must be able
+ * to tell apart — so it is typed, and it carries `httpStatus` + a `code` the
+ * shared `classifyLoadError` reads as `forbidden` without any string matching.
+ *
+ * `serverMessage` is kept for diagnostics only. The producer deliberately
+ * names the object and nothing else, but it is still platform prose, not text
+ * addressed to the end user.
+ */
+declare class AnalyticsForbiddenError extends Error {
+    readonly code = "PERMISSION_DENIED";
+    readonly httpStatus = 403;
+    /** The server's own ADR-0112 code — the field this branch was chosen BY. */
+    readonly serverCode?: string;
+    /** The server's own message, verbatim (diagnostics only). */
+    readonly serverMessage?: string;
+    /** The dataset the refused query asked for, when it named one. */
+    readonly datasetName?: string;
+    constructor(opts?: {
+        serverCode?: string;
+        serverMessage?: string;
+        datasetName?: string;
+    });
+}
 /**
  * Thrown when the server REJECTED the analytics query body (HTTP 400 —
  * `VALIDATION_FAILED` since framework#4010 validates `/analytics/query` at the
@@ -1210,6 +2315,49 @@ declare class AnalyticsQueryRejectedError extends Error {
     readonly serverCode?: string;
     constructor(detail?: string, serverCode?: string);
 }
+/**
+ * Thrown by `aggregate()` when `client.analytics.query` resolves to anything
+ * other than the post-unwrap `AnalyticsResult` — concretely, when the value it
+ * hands back has no `rows` array (objectui#7028).
+ *
+ * ONE SPELLING, BY RULING. `@objectstack/client` 17.3.0 converged
+ * `analytics.query` on `unwrapResponse` (objectstack#13079, maintainer ruling
+ * 2026-08-31, option A): the method resolves to the payload, and the caller
+ * reads `result.rows`. The same ruling ordered this adapter's tolerant row
+ * ladder tightened in the same wave, so that defensive code is not read as a
+ * contract. The ladder also read a bare array, `data` as an array,
+ * `data.data.rows` and `results`; `rows` is now the only spelling read, and
+ * everything else lands here.
+ *
+ * WHY A THROW AND NOT `[]`. The ladder answered every shape it did not
+ * recognise with an empty array, and an empty array is a RESULT: a KPI renders
+ * a confident zero and a chart reads "no data" over a populated table — the
+ * lie objectui#5954 removed on the failure side. The envelope arriving here
+ * means the SDK in front of this call predates the convergence (it is older
+ * than 17.3.0), or something between it and `POST /analytics/query` wraps the
+ * payload a second time. Either way the adapter is handed a contract it no
+ * longer reads, and saying so is the only answer that names the repair.
+ *
+ * WHY NOT THE CLIENT-SIDE FALLBACK. Analytics answered; this is not a
+ * transport failure. Degrading would put plausible numbers from a different
+ * code path over a contract violation — the misdirection
+ * {@link AnalyticsQueryRejectedError} refuses for the same reason
+ * (framework#3878) — so `aggregate()`'s catch rethrows this before it
+ * classifies anything.
+ */
+declare class AnalyticsResultShapeError extends Error {
+    readonly code = "ANALYTICS_RESULT_SHAPE_INVALID";
+    /** The object `aggregate()` was called for. */
+    readonly resource: string;
+    /**
+     * True when the value is the envelope the client stopped handing back at
+     * 17.3.0 — `{ success, data: { rows } }`, or its `{ data: { rows } }` core.
+     */
+    readonly envelope: boolean;
+    /** What the value was, so the producer is identifiable from a log. */
+    readonly received: string;
+    constructor(resource: string, result: unknown);
+}
 /**
  * Classify a FAILED analytics call so the caller knows whether to degrade or
  * to surface the failure.
@@ -1257,11 +2405,18 @@ declare class AnalyticsQueryRejectedError extends Error {
  *     `ROUTE_NOT_FOUND` (framework#4019 stops mounting the routes at all).
  *     A client-side aggregate over a scoped `find()` answers the chart
  *     correctly, and the operator is told once that the semantic layer is off.
- *   - **`rejected`** — *THROW*. The server refused OUR body (400
- *     `VALIDATION_FAILED`; framework#4010 validates `/analytics/query` at the
- *     entry). Degrading would answer our own contract violation with plausible
- *     numbers from a different code path and bury it — the misdirection
- *     framework#3878 documented.
+ *   - **`rejected`** — *THROW*. The server refused OUR body: 400
+ *     `VALIDATION_FAILED` (framework#4010 validates `/analytics/query` at the
+ *     entry) OR any other coded 400 (objectui#7755 — e.g. `service-analytics`
+ *     ships its own 400 `INVALID_FILTER` on a filter shape it refuses). The
+ *     status alone is decisive once it is 400: a producer that refuses the
+ *     body and ships a code this consumer does not enumerate is refusing it
+ *     exactly as hard as one that ships `VALIDATION_FAILED` — the refusal is
+ *     in the transport fact, not in which code spells it. Degrading would
+ *     answer our own contract violation with plausible numbers from a
+ *     different code path (`find()`'s `$filter` accepts array shapes the
+ *     analytics body does not) and bury it — the misdirection framework#3878
+ *     documented.
  *   - **`unauthenticated`** — *THROW*. 401 `UNAUTHENTICATED`: the request was
  *     refused before it ran, so it is evidence about the SESSION and none at
  *     all about the capability. Degrading is not merely misleading here, it is
@@ -1309,16 +2464,46 @@ declare class ConcurrentUpdateError extends Error {
     readonly httpStatus = 409;
     readonly currentVersion: string | null;
     readonly currentRecord: unknown;
+    /**
+     * The refusal text the PRODUCER marked as addressed to the end user
+     * (`ApiErrorSchema.userMessage`, objectstack `79c46da90`), or `null` when the
+     * refusal carried no marking.
+     *
+     * Declared on the class because this error has no `details` bag: the shared
+     * reader (`declaredUserMessage` in `@object-ui/react`) looks at the
+     * top-level field first, so parking it here is what makes the marking
+     * readable at the surface. The contract is status-agnostic — a 409 carries
+     * it exactly like a 400 or a 403 does.
+     */
+    readonly userMessage: string | null;
     constructor(opts: {
         currentVersion: string | null;
         currentRecord: unknown;
         message?: string;
+        userMessage?: string | null;
     });
 }
 /**
  * Detect "concurrent update" errors raised by the platform. The wire
  * shape is `409` + `code: 'CONCURRENT_UPDATE'`. The client surfaces
  * extra details on `error.details` (full response body).
+ *
+ * Accepts EITHER that wire `code` OR `name === 'ConcurrentUpdateError'`, and
+ * reads `httpStatus` for neither. This paragraph exists because the doc used
+ * to name only the wire shape, which left the `name` limb reading as drift
+ * (objectui#6375). It is not drift: it is the deliberate cross-realm
+ * duck-check — a host that bundles this package twice (or re-throws across a
+ * worker boundary) ends up holding two copies of the class, `instanceof`
+ * fails, and the `name` string is the only discriminator left. That host is out of tree by construction, so an in-repo
+ * consumer census cannot see the case the limb was written for and is not
+ * evidence against it; `@object-ui/plugin-form` and `@object-ui/plugin-detail`
+ * each carry their own copy of the same two-limb check for adapters they must
+ * not depend on.
+ *
+ * Deliberately WIDER than {@link normaliseClientError}'s re-wrap, which keys
+ * on the wire `code` alone: an error carrying only the class name is
+ * recognised here and passed through there. Both accepted sets are pinned in
+ * `occ.test.ts`.
  */
 declare function isConcurrentUpdateError(error: unknown): error is ConcurrentUpdateError;
 /**
@@ -1331,6 +2516,12 @@ declare function isConcurrentUpdateError(error: unknown): error is ConcurrentUpd
  *   - `400` + `VALIDATION_FAILED` → {@link DataApiValidationError}, carrying the
  *     server's per-field entries so a form can mark the offending inputs
  *     instead of showing one undirected toast.
+ *
+ * Both re-wraps preserve the producer's `userMessage` marking (see
+ * {@link liftUserMessage}). Re-wrapping used to drop it, which made the
+ * marking unreadable at every surface downstream of this boundary — nothing
+ * threw, the typed error was otherwise correct, and the user simply got a
+ * generic string.
  */
 declare function normaliseClientError(error: unknown): unknown;
 /**
@@ -1377,10 +2568,7 @@ declare function formatHttpFailureMessage(message: string, meta?: Record<string,
  * own `ObjectStackClient` gets the same identified failures.
  */
 declare function createQuietHttpLogger(): any;
-/**
- * Connection state for monitoring
- */
-type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
+
 /**
  * Connection state change event
  */
@@ -1408,20 +2596,306 @@ type ConnectionStateListener = (event: ConnectionStateEvent) => void;
  */
 type BatchProgressListener = (event: BatchProgressEvent) => void;
 
+/**
+ * The `reason` of a write-strip this bundle's spec pin cannot name
+ * (objectui#4934).
+ *
+ * Deliberately NOT a spec spelling: it is namespaced so it can never collide
+ * with an arm `@objectstack/spec` adds later (a collision would merge real
+ * reasons into the skew bucket — the failure this whole card is about, one level
+ * up). `droppedFieldsReason.boundary.test.ts` pins that the installed spec does
+ * not declare it.
+ */
+declare const UNRECOGNIZED_DROP_REASON = "objectui:unrecognized-drop-reason";
+/**
+ * The skew arm: one server-reported write-strip whose `reason` is outside the
+ * enum this bundle's `@objectstack/spec` pin declares (objectui#4934).
+ *
+ * A deployed client normally runs BEHIND the server it talks to, so a reason
+ * from the future is the expected skew direction, not a corrupt payload. The
+ * boundary used to assert such an entry into {@link DroppedFieldsEvent} on shape
+ * alone — `reason` was never read — so the interior was typed to trust a union
+ * nothing had checked, and the next consumer to write an exhaustive-looking
+ * table over `DroppedFieldsEvent['reason']` would have been handed a value that
+ * type says is impossible.
+ *
+ * Three properties of this shape are load-bearing:
+ *
+ * - The entry is **kept**. Dropping it would tell the user nothing about fields
+ *   the server really did strip — precisely the silence objectui#3484 removed.
+ * - The wire value is **preserved verbatim** in {@link unrecognizedReason},
+ *   never coerced or normalised onto a known arm: claiming `readonly` for a
+ *   reason we cannot name is a false statement about the user's data, and it is
+ *   also unfalsifiable once the original value is gone.
+ * - `reason` carries {@link UNRECOGNIZED_DROP_REASON}, which is not assignable
+ *   to `DroppedFieldsEvent['reason']`. That is what makes the skew case visible
+ *   to `tsc` at every consumer instead of resting on N per-consumer
+ *   disciplines — and it keeps the spec type as the canonical arm rather than
+ *   widening the whole surface to `string` (objectui#3160).
+ */
+interface UnrecognizedDropReasonEvent {
+    object?: string;
+    fields: string[];
+    reason: typeof UNRECOGNIZED_DROP_REASON;
+    /** Whatever the server sent, untouched — including a non-string or nothing at all. */
+    unrecognizedReason: unknown;
+}
+/**
+ * One entry of a write-warning: either the spec type (canonical arm) or the
+ * named skew arm above. Narrow with `entry.reason === UNRECOGNIZED_DROP_REASON`.
+ */
+type DroppedFieldsNotice = DroppedFieldsEvent | UnrecognizedDropReasonEvent;
 /**
  * Emitted after a create/update whose response carried `droppedFields`
- * (framework #3431/#3455). The write SUCCEEDED — this is a warning that some
- * supplied fields never landed, so the UI can tell the user rather than let it
- * pass silently. Subscribe via {@link ObjectStackAdapter.onWriteWarning}.
+ * (objectstack-ai/objectstack#3431 / objectstack-ai/objectstack#3455) or
+ * `warnings` (objectui#12107). The write SUCCEEDED — this is a warning that
+ * some supplied fields never landed, or that an advisory validation rule hit,
+ * so the UI can tell the user rather than let it pass silently. Subscribe via
+ * {@link ObjectStackAdapter.onWriteWarning}.
+ *
+ * `droppedFields` is the two-arm {@link DroppedFieldsNotice} and not
+ * `DroppedFieldsEvent[]`: the wire is parsed here, and an entry whose `reason`
+ * this bundle's spec pin cannot name arrives on the explicit skew arm rather
+ * than being asserted into the union (objectui#4934). It stays REQUIRED and is
+ * an empty array when the event exists only for `warnings`.
+ *
+ * `warnings` is the write answer's own key, typed by the spec's
+ * `ValidateDataIssueSchema` (the element of `CreateDataResponseSchema` /
+ * `UpdateDataResponseSchema`'s `warnings`) and parsed through it here. It is
+ * present only when at least one entry parsed: an answer without the key —
+ * including one from a runtime that predates it — leaves the event exactly as
+ * it was.
  */
 interface WriteWarningEvent {
     operation: 'create' | 'update';
     resource: string;
     id?: string | number;
-    droppedFields: DroppedFieldsEvent[];
+    droppedFields: DroppedFieldsNotice[];
+    warnings?: ValidateDataIssue[];
 }
 /** Event listener type for write-warning (dropped-fields) events. */
 type WriteWarningListener = (event: WriteWarningEvent) => void;
+/**
+ * What a FAILED `listImportMappings` read actually was (objectui#7741).
+ *
+ *  - `not-served` — this deployment does not serve the `mapping` kind, or has
+ *    no `/meta` door at all. QUIET: a real, supported deployment shape, and the
+ *    empty list plus a hidden selector is the correct rendering of it.
+ *  - `refused` — the server answered and declined THIS caller: anonymous,
+ *    lapsed token, missing permission, method withheld. LOUD, and the remedy
+ *    names a person: sign in again, or ask for the grant.
+ *  - `unreadable` — the read could not be completed for any other reason: a
+ *    5xx, a network failure, a code this consumer cannot name. LOUD, and the
+ *    remedy is to retry or report.
+ *
+ * The last two are the same verdict for the user — *we could not find out* —
+ * and they are separated because the sentence that helps differs. What they
+ * share is what matters: neither is evidence that no mapping is registered.
+ *
+ * ⚠️ The three NAMES are shared by every classifier feeding
+ * {@link MetadataReadWarningEvent}; the POPULATION each name covers is not, and
+ * is decided per read door. `not-served` in particular is a strictly smaller
+ * set on `view` than on `mapping` — see {@link classifyViewsFailure}.
+ */
+type MetadataReadFailureKind = 'not-served' | 'refused' | 'unreadable';
+/**
+ * The published spelling of {@link MetadataReadFailureKind}, kept as the name
+ * objectui#7741 shipped (`@object-ui/data-objectstack@17.2.0`).
+ *
+ * An ALIAS, not a second declaration: identical members, so every existing
+ * consumer's assignability is unchanged in both directions. It was renamed
+ * because the channel gained a second emitter (objectui#8151) and a type called
+ * `ImportMappingsFailureKind` describing a `view` read would be a name that
+ * lies; the old name stays because retiring a published one is not this card's
+ * business.
+ */
+type ImportMappingsFailureKind = MetadataReadFailureKind;
+/**
+ * Classify a FAILED `meta.getItems('mapping')` call so the caller knows whether
+ * to stay quiet or to say something (objectui#7741).
+ *
+ * ## Why this function exists
+ *
+ * `listImportMappings` degrades every failure to `[]`, and the wizard hides its
+ * saved-mapping selector on an empty list. So "the server served zero mappings"
+ * and "the server never answered" rendered identically — the same UI, on every
+ * deployment, with a `console.warn` as the only discriminator. That silence did
+ * not merely hide a fault: it produced a confident WRONG diagnosis in a careful
+ * reporter (objectstack#14026 was filed, routed and worked by two seats against
+ * a repo whose wizard had been correct since `@object-ui/data-objectstack`
+ * 17.1.0), and the misdiagnosis travelled further than the fault would have.
+ *
+ * This is the discrimination framework objectstack#13906 decision 1 option A already
+ * adopted at the tenancy-posture seam — *a thing that could not be READ is not
+ * a thing that is ABSENT* — applied here. It is not a new principle.
+ *
+ * ## It reads the ERROR, never the result
+ *
+ * The one thing this must never do is decide from "is the result an empty
+ * array". An empty array is what BOTH conditions produce, so a test on it can
+ * never fail and can never separate *served zero* from *did not serve* — a
+ * reading that cannot fail is indistinguishable from a reading that passed.
+ * Every branch below reads `err` itself: the ADR-0112 `code` first (the
+ * contract), the status only where no code was declared (a transport fact many
+ * conditions share). Same rule, same order, and for the same reasons as
+ * {@link classifyAnalyticsFailure} (objectui#5663 / objectui#5721).
+ *
+ * `@objectstack/client`'s fetch wrapper hands both envelope families here
+ * already flattened — `errorBody?.code ?? errorBody?.error?.code` onto
+ * `error.code`, plus `error.httpStatus = res.status` — so no envelope reading
+ * belongs in this function. Comparisons go through `errorCodeIs`/
+ * `errorCodeIsAnyOf` so the pre- and post-ADR-0112 spellings both match.
+ */
+declare function classifyImportMappingsFailure(error: unknown): {
+    kind: ImportMappingsFailureKind;
+    code?: string;
+    status?: number;
+    message?: string;
+};
+/**
+ * Classify a FAILED `view` metadata list read so {@link ObjectStackAdapter.listViews}
+ * knows whether to stay quiet or to say something (objectui#8151).
+ *
+ * ## Why this is a SEPARATE reading and not a second caller of
+ * {@link classifyImportMappingsFailure}
+ *
+ * The two methods share a defect and a remedy, not a population. The quiet arm
+ * `listImportMappings` is built around — *an older server that does not serve
+ * this kind* — has no members on `view`, and carrying it over would put a fresh
+ * swallow into the method this card exists to un-swallow. Measured, on the
+ * framework tree, three ways:
+ *
+ *  1. **`view` is in the platform's static spelling contract**, so the metadata
+ *     LIST door's unknown-kind refusal is unreachable for it.
+ *     `RestServer.refuseUnknownMetaListType` (framework#9488,
+ *     `packages/rest/src/rest-server.ts`) returns without writing a refusal
+ *     whenever `unrecognisedMetaTypeRefusal(urlType)` is `null`, and that
+ *     predicate answers `null` for every spelling in the contract.
+ *     `packages/spec/src/meta-spelling/meta-url-data.generated.ts` carries both
+ *     `"views": "view"` and the canonical singular `view`. So a `400`
+ *     `INVALID_REQUEST` on `GET /meta/view` is NEVER that door saying "this
+ *     deployment carries no such kind" — it is some other refusal of the
+ *     request, and reading it as kind-absence would silence a real one.
+ *  2. **There is no "before" for `view` to be older than.** `mapping`'s quiet
+ *     arm exists because `mapping` was PROMOTED into the declared set
+ *     (framework#2611), so servers predating the promotion are a real, shipped
+ *     population. `view` is the kind the metadata surface is built around — the
+ *     compound-arity door `/meta/<object>/views/<name>`, the ADR-0017
+ *     `ViewItem` discriminant this very method filters on.
+ *  3. **A deployment that cannot serve `view` cannot render the caller.**
+ *     `listViews` is reached only from `ObjectView`, whose `objectDef` came from
+ *     `MetadataProvider`, which reads the SAME door and lists `view` among its
+ *     `EAGER_TYPES` at mount (`packages/app-shell/src/providers/MetadataProvider.tsx`).
+ *     A server that does not answer `/meta/view` has already failed that read
+ *     before any object page exists.
+ *
+ * ## So the quiet set here is strictly SMALLER — it is the DOORLESS one only
+ *
+ * What survives as quiet is not about `view` at all: it is *this host mounted no
+ * metadata door*. That stays silent for the reason objectui#7741 gave — a real,
+ * supported deployment shape must not be turned into a visible fault — and it
+ * costs nothing to keep silent here, because such a host has already failed
+ * `MetadataProvider`'s eager `app`/`object`/`view` reads; a per-object toast
+ * would be a fourth voice on one deployment fact, not a new one.
+ *
+ * Everything else is LOUD. In particular a `refused` (401/403/405,
+ * `UNAUTHENTICATED`, `PERMISSION_DENIED`) is the condition this card was filed
+ * for: a token that lapsed mid-session renders the object's view switcher as
+ * though the user's own saved views did not exist.
+ *
+ * ## It reads the ERROR, never the result — and from BOTH of this method's doors
+ *
+ * `listViews` is fed by two transports, unlike its sibling's one, and they
+ * decorate differently:
+ *
+ *   published  `client.meta.getItems('view')` -> `@objectstack/client`'s fetch
+ *              wrapper: `error.code` (flattened from either envelope family)
+ *              plus `error.httpStatus`.
+ *   drafts     `MetadataClient.withPreviewDrafts(true).list('view')` (ADR-0037,
+ *              `?preview=draft`) -> this package's own `parseError`:
+ *              `err.code` plus **`err.status`**, with no `httpStatus` at all.
+ *
+ * The status ladder below therefore reads `httpStatus`, then `status`, then
+ * `statusCode`, and is the reason a preview-mode failure classifies the same as
+ * a published-mode one instead of falling through to the code-less residual.
+ * What it must never read is "is the result an empty array": that is what BOTH
+ * a served-zero and a refusal produce, so a test on it can never fail for the
+ * condition it is supposed to be about. This is framework objectstack#13906 decision 1
+ * option A — *a thing that could not be READ is not a thing that is ABSENT*.
+ */
+declare function classifyViewsFailure(error: unknown): {
+    kind: MetadataReadFailureKind;
+    code?: string;
+    status?: number;
+    message?: string;
+};
+/**
+ * Emitted when a metadata READ was answered by the server with a failure that
+ * is NOT the supported "this deployment does not serve that kind" shape, and
+ * the adapter degraded it to an empty result anyway (objectui#7741).
+ *
+ * The degrade is deliberate and unchanged — the caller still receives `[]`, and
+ * `listImportMappings`' published return type has not moved. This event is the
+ * channel ALONGSIDE it: the fact that the empty result is an artefact of a
+ * failed read, carried in a form a consumer can act on, instead of a
+ * `console.warn` nothing in the UI points at.
+ *
+ * Subscribe via {@link ObjectStackAdapter.onMetadataReadWarning}. A sibling of
+ * {@link WriteWarningEvent} and `MetadataSaveAdvisoryEvent` in SHAPE — one
+ * long-lived instance, `subscribe → unsubscribe`, `AdapterProvider` wires it
+ * once — and deliberately not a payload pushed down either of those: both of
+ * them describe a write that SUCCEEDED, so carrying a failed read on one would
+ * make the event lie about what happened.
+ *
+ * `operation` and `kind` are CLOSED unions on purpose. Every emitter is named
+ * in them, so widening is an additive, reviewed change rather than something a
+ * consumer's exhaustive switch discovers at runtime. (The same trade
+ * `WriteWarningEvent`'s required `operation` documents, taken deliberately
+ * here.)
+ *
+ * ## The widening this design was built for happened (objectui#8151)
+ *
+ * objectui#7741 shipped both fields as SINGLE-member unions and said in as many
+ * words that a second emitter should arrive as a reviewed widening. It has:
+ * `listViews` is the second, for the same defect one method over, and the
+ * mechanism worked as designed — the consumer that renders these events
+ * (`app-shell`'s `metadataReadWarningToast`) had a `switch` that named the one
+ * operation, so adding the member turned "a views failure is toasted as an
+ * import-mapping failure" into a COMPILE error instead of a runtime lie.
+ *
+ * ⚠️ The pair is the emitter's invariant, not the type's: `operation` and
+ * `kind` are two independent unions, so nothing in the type stops
+ * `{ operation: 'listViews', kind: 'mapping' }` being constructed. Each emitter
+ * writes its own pair, one line apart, and every consumer branches on
+ * `operation` — the adapter METHOD, which is what names the list the user is
+ * actually looking at. Tightening this to a discriminated union would mean
+ * turning a published `interface` into a type alias; that is a reviewable
+ * change on its own terms and is deliberately not smuggled in here.
+ */
+interface MetadataReadWarningEvent {
+    /** The adapter method whose read failed. */
+    operation: 'listImportMappings' | 'listViews';
+    /** The metadata kind it asked for. */
+    kind: 'mapping' | 'view';
+    /** The object the read was scoped to. */
+    objectName: string;
+    /**
+     * Which loud verdict this is — see {@link MetadataReadFailureKind}. Never
+     * `'not-served'`: that arm is the supported deployment shape and is not
+     * emitted at all, so a subscriber never has to filter it out. ⚠️ WHICH
+     * failures fall in that un-emitted arm differs per `operation` — it is a
+     * strictly smaller set on `listViews` (see {@link classifyViewsFailure}).
+     */
+    reason: Exclude<MetadataReadFailureKind, 'not-served'>;
+    /** The server's own ADR-0112 code, when it declared one. */
+    code?: string;
+    /** The HTTP status, when the failure carried one. */
+    status?: number;
+    /** The server's own message, when it sent one. Rendered verbatim, not translated. */
+    message?: string;
+}
+/** Event listener type for metadata read-warning events. */
+type MetadataReadWarningListener = (event: MetadataReadWarningEvent) => void;
 
 /**
  * Resolve which object a `type='view'` metadata item belongs to.
@@ -1441,8 +2915,17 @@ type WriteWarningListener = (event: WriteWarningEvent) => void;
  *
  * `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.
+ * objectstack#2555); `data.object` is the config's data-provider target.
+ *
+ * ⛔ No `objectName` leg (objectui#11013, ruling 甲 on objectstack#20051:
+ * objectui reads a stored view row by the spec's declared spellings). The
+ * spec declares `object` on every `view` member — required on the ViewItem
+ * record and on both flattened overlays — and declares `objectName` on none,
+ * so the metadata write door refuses a row that carries only `objectName`
+ * (`viewItemObjectName.declaredSpelling-11013.test.ts` pins that door beside
+ * this reader). Every write path in this package stamps `object` as well, so a
+ * row the console wrote carries it; a row that carries ONLY the undeclared
+ * spelling no longer matches any object here.
  *
  * **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
@@ -1456,13 +2939,18 @@ declare function viewItemObjectName(item: any): string | undefined;
  * The keys a personalization overlay row legitimately OWNS (objectui#5233).
  *
  * One per `persistViewPatch` call site in app-shell's `ObjectView` — the ONLY
- * production writer of these rows — read off the tree rather than recalled:
+ * production writer of these rows, read off the tree when it was written:
  * `rowHeight` (the density toggle, spec-canonical since #2890), `sort`,
- * `hiddenFields`, `columnState` and `inlineEdit`. Nothing else in such a row
- * is an opinion the user expressed; anything else it carries is a COPY of the
- * source view as it stood at write time, because `persistViewPatch` USED TO
- * send `{ ...baseViewDef, ...patch }` and this adapter persists what it is
- * given.
+ * `hiddenFields` and `columnState`. Plus `inlineEdit`, which no console call
+ * site wrote after objectui#5144 (triage's ruling E: the inline-edit toggle
+ * is session-only). That writer is retired (objectui#12504): no toolbar
+ * control writes an overlay, and every key here is kept so an overlay an
+ * earlier console wrote is still read; the rulings keep that data rather than
+ * migrating it. Nothing else in
+ * such a row is an opinion the user expressed; anything else it carries is a
+ * COPY of the source view as it stood at write time, because
+ * `persistViewPatch` USED TO send `{ ...baseViewDef, ...patch }` and this
+ * adapter persists what it is given.
  *
  * That copy was the defect the maintainer ruled on (objectstack#7494, comment
  * 5261754173): an overlay written by a mere column drag froze the view's
@@ -1472,20 +2960,19 @@ declare function viewItemObjectName(item: any): string | undefined;
  * view's filter and every user who once resized a column kept the old one,
  * with nothing anywhere reporting it.
  *
- * Both halves of that ruling have now landed, and this adapter's behaviour is
- * unchanged by either — it still persists what it is given:
+ * Both halves of that ruling landed, and this adapter's behaviour was
+ * unchanged by either — it persisted what it was given:
  *
  * - **read** (PR #5272, {@link narrowPersonalizationOverlay}): the consumer
  *   that MERGES an overlay over a source view contributes only these keys, so
- *   every already-stored fat row stops shadowing its source.
- * - **write** (objectui#5233, `buildPersistedViewBody` in app-shell's
- *   `ObjectView`, unblocked by `columnState`'s admission to the view-metadata
- *   surface as a runtime-only overlay key — objectstack#9933, released in
- *   `@objectstack/spec` 17.1.0): a *system view's* overlay is now written as
- *   the patch alone, so no new row freezes anything, and because the write is
- *   a whole-document PUT the next toggle also strips an old fat row. A *saved
- *   view's* own row is deliberately still written whole — for it the body IS
- *   the view, not a copy of one.
+ *   every already-stored fat row that carries the marker stops shadowing its
+ *   source. A fat row written before the marker is no longer narrowed
+ *   (objectui#10210, ruling B — see {@link isPersonalizationOverlayRow}).
+ * - **write** (objectui#5233, unblocked by `columnState`'s admission to the
+ *   view-metadata surface as a runtime-only overlay key — objectstack
+ *   `d5552ca13`, released in `@objectstack/spec` 17.1.0): a *system view's*
+ *   overlay was written as the patch alone from then on, and the whole write
+ *   is retired since objectui#12504.
  *
  * A fat row is therefore a legacy shape, not a shape this product still
  * produces; the list below is still what a reader is allowed to trust from one.
@@ -1493,9 +2980,10 @@ declare function viewItemObjectName(item: any): string | undefined;
  * ⛔ Do not grow this list to make some other key "stick" through an overlay.
  * A key that belongs to the view belongs in the view; the overlay is a patch,
  * and a patch that carries the whole document is what this list exists to
- * stop. Adding a sixth entry is only correct alongside a sixth
- * `persistViewPatch` call site — {@link narrowPersonalizationOverlay} is what
- * a reader checks that against.
+ * stop. No writer of these rows is left (objectui#12504), so there is no new
+ * key for an entry to answer; each entry is kept for reading the rows already
+ * at rest — `inlineEdit` for rows written before objectui#5144, the other four
+ * for rows written before objectui#12474 / objectui#12418.
  */
 declare const VIEW_OVERLAY_OWNED_KEYS: readonly ["rowHeight", "sort", "hiddenFields", "columnState", "inlineEdit"];
 /**
@@ -1506,8 +2994,8 @@ declare const VIEW_OVERLAY_OWNED_KEYS: readonly ["rowHeight", "sort", "hiddenFie
  * {@link VIEW_OVERLAY_OWNED_KEYS}). Of the three dispositions the issue names
  * for them — strip on next write, migrate, tolerate on read — this is the
  * third, chosen deliberately and stated here rather than left implicit,
- * because it is the only one that is already true for every existing row the
- * moment it ships: strip-on-next-write heals a row only when its user happens
+ * because it is the only one that is already true for every existing marked
+ * row the moment it ships: strip-on-next-write heals a row only when its user happens
  * to touch that view again (and leaves the frozen filter live until then),
  * and a migration needs a runner this product does not have for `sys_metadata`
  * rows an operator may not even know exist. What the issue forbids is SILENT
@@ -1528,7 +3016,9 @@ declare const VIEW_OVERLAY_OWNED_KEYS: readonly ["rowHeight", "sort", "hiddenFie
  * IS the view, and every key on it is an opinion its author expressed.
  * Classification is {@link isPersonalizationOverlayRow}, the same predicate
  * {@link ObjectStackAdapter.listViews} excludes rows by, so a row cannot be a
- * saved view for one reader and an overlay for the other.
+ * saved view for one reader and an overlay for the other. It reads the marker
+ * only (objectui#10210, ruling B): an unmarked row is returned by reference
+ * whatever its shape, including a fat row written before the marker existed.
  */
 declare function narrowPersonalizationOverlay<T>(row: T): T;
 
@@ -1579,12 +3069,14 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     private analyticsCapabilityWarned;
     private fetchImpl;
     private inflightFinds;
+    private inflightFindOnes;
     private missingResources;
     private batchUnsupported;
     private atomicBatchCapability;
     private mutationListeners;
     private writeWarningListeners;
     private saveAdvisoryListeners;
+    private metadataReadWarningListeners;
     constructor(config: {
         baseUrl: string;
         token?: string;
@@ -1600,8 +3092,18 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     /**
      * Ensure the client is connected to the server.
      * Call this before making requests or it will auto-connect on first request.
+     *
+     * With `autoReconnect`, a failed discovery read is retried up to
+     * `maxReconnectAttempts` times with exponential backoff. The promise resolves
+     * once discovery answers and rejects with the last `ConnectionError` once the
+     * retries are spent (objectui#12318).
      */
     connect(): Promise<void>;
+    /**
+     * One discovery attempt, and the retry that follows it when it fails with
+     * budget left. Runs inside the promise {@link connect} hands every caller.
+     */
+    private attemptConnect;
     /**
      * Attempt to reconnect to the server with exponential backoff
      */
@@ -1626,6 +3128,34 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * Set connection state and notify listeners
      */
     private setConnectionState;
+    /**
+     * Run one request through the adapter's fetch and let its outcome move the
+     * connection state (objectui#12295). Before the first successful
+     * {@link connect} this records nothing: `connect()` owns the state until
+     * then, and its own discovery read passes through here too.
+     *
+     * - **Answered** — the fetch resolved with a Response, whatever its status.
+     *   A 4xx or 5xx is an answer: the server is reachable, so it counts the
+     *   same as a 200 and ends any outage.
+     * - **Not answered** — the fetch rejected: no HTTP answer at all (refused,
+     *   reset, DNS, an offline browser). A rejection the caller asked for by
+     *   aborting is not evidence about the server and records nothing.
+     *
+     * The rejection or the Response reaches the caller unchanged.
+     */
+    private observeServerAnswer;
+    /** An answered request after the first connect: the server is reachable. */
+    private noteServerAnswered;
+    /**
+     * An unanswered request after the first connect. It spends the adapter's own
+     * retry window — the `autoReconnect` / `maxReconnectAttempts` budget that
+     * {@link connect} grants a failed discovery — counted in the requests the
+     * host already makes rather than in timed probes: while the budget lasts the
+     * state is `reconnecting`, and the first unanswered request past it moves the
+     * state to `error`. No timer and no request of the adapter's own is involved;
+     * the next answered request, whenever it comes, restores `connected`.
+     */
+    private noteServerUnanswered;
     /**
      * Emit batch progress event to listeners
      */
@@ -1635,6 +3165,16 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * Converts OData-style params to ObjectStack query options.
      */
     find(resource: string, params?: QueryParams): Promise<QueryResult<T>>;
+    /**
+     * Share one in-flight read among concurrent callers asking the same
+     * question: the first call for `key` issues `read()`, every call that
+     * arrives while it is still pending gets that same promise, and the entry is
+     * dropped the moment it settles — so nothing is cached past the round trip,
+     * a rejection reaches every caller that shared it and is not remembered, and
+     * the next call after settle issues a fresh read. Used by `find` and
+     * `findOne` (objectui#11699).
+     */
+    private shareInFlight;
     /**
      * Full-text search across every searchable object in a single round-trip.
      *
@@ -1644,7 +3184,7 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * — a per-object metadata-driven search (ADR-0061) — this consults the search
      * index and ranks hits across objects, so it surfaces records the per-object
      * fanout misses. Global affordances (⌘K command palette, search page) prefer
-     * this path (framework #3371).
+     * this path (objectstack-ai/objectstack#3371).
      *
      * Returns `{ query, hits }`. A backend without the search plugin installed
      * answers `404`; we treat that as "no global search here" and return an empty
@@ -1657,8 +3197,13 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     }): Promise<GlobalSearchResult>;
     /**
      * Find a single record by ID.
+     *
+     * Concurrent calls for the same resource, id and params share one request,
+     * exactly as `find` does (objectui#11699); see {@link shareInFlight}.
      */
     findOne(resource: string, id: string | number, params?: QueryParams): Promise<T | null>;
+    /** The one round trip behind {@link findOne}, unshared. */
+    private readOne;
     /**
      * Create a new record.
      */
@@ -1680,14 +3225,24 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      */
     private emitWriteWarning;
     /**
-     * Read `droppedFields` off a create/update response (framework #3431/#3455)
+     * Read `droppedFields` off a create/update response (objectstack-ai/objectstack#3431 / objectstack-ai/objectstack#3455)
      * and, when present, notify write-warning subscribers. Tolerant of a client
      * whose response type predates `droppedFields`: the field is read structurally
      * and validated, so an older client (or a backend that never drops) is a no-op.
+     *
+     * SHAPE decides whether an entry is an event at all (it must name at least one
+     * field); `object`, `fields` and `reason` are then PARSED — an unrecognized
+     * reason routed to the skew arm, a non-string field element refused, a missing
+     * `object` healed from `resource` — never asserted into the union, and the
+     * entry itself never dropped for them (objectui#4934, `f75810e7c`).
+     *
+     * The same answer's `warnings` (objectui#12107) rides this one event: it is
+     * emitted when either list is non-empty, so a write whose only news is an
+     * advisory rule hit still reaches the subscriber, with `droppedFields: []`.
      */
     private notifyDroppedFields;
     /**
-     * Same, for the cross-object transactional batch (framework #3794). Its
+     * Same, for the cross-object transactional batch (objectstack-ai/objectstack#3794). Its
      * response hangs the events off a top-level `droppedFields` list, each tagged
      * with the `index` of the operation it came from — `results` entries are bare
      * record echoes with nowhere to hang a per-row list.
@@ -1701,7 +3256,7 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     private notifyBatchDroppedFields;
     /**
      * Subscribe to write-warning events (a create/update dropped caller-supplied
-     * fields — #3431/#3455). Returns an unsubscribe function. The app shell uses
+     * fields — objectstack-ai/objectstack#3431 / objectstack-ai/objectstack#3455). Returns an unsubscribe function. The app shell uses
      * this to toast the user; the write itself already succeeded.
      */
     onWriteWarning(callback: WriteWarningListener): () => void;
@@ -1710,7 +3265,7 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * 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
+     * Deliberately the same seam as {@link onWriteWarning} (objectstack-ai/objectstack#3431 / objectstack-ai/objectstack#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
@@ -1734,6 +3289,32 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * nor starve the others.
      */
     private emitSaveAdvisory;
+    /**
+     * Subscribe to metadata read-warning events — a metadata READ that could not
+     * be answered and was degraded to an empty result anyway (objectui#7741).
+     * Returns an unsubscribe function. The app shell uses this to toast the user;
+     * the caller has already been handed the empty result.
+     *
+     * Deliberately the same seam as {@link onWriteWarning} and
+     * {@link onSaveAdvisory}, and a SIBLING of them rather than a payload pushed
+     * down either: both of those announce a write that SUCCEEDED, and an event
+     * saying "this read did not happen" carried on one of them would make it lie
+     * about what occurred. What is reused is the seam's SHAPE — one long-lived
+     * instance with a `subscribe -> unsubscribe` registration that
+     * `AdapterProvider` wires once — not its event type.
+     *
+     * ⛔ Nothing here changes what a caller RECEIVES. `listImportMappings` still
+     * answers `[]` on every failure, including the loud ones; this channel is
+     * added ALONGSIDE that return, which is why it is not a change to a surface
+     * published since `@object-ui/data-objectstack@17.1.0`.
+     */
+    onMetadataReadWarning(callback: MetadataReadWarningListener): () => void;
+    /**
+     * Notify all metadata read-warning subscribers. Isolated exactly like
+     * {@link emitWriteWarning}: a throwing listener must neither break the caller
+     * nor starve the others.
+     */
+    private emitMetadataReadWarning;
     /**
      * Install the ONE emitter for the metadata save door (#4237).
      *
@@ -1741,8 +3322,8 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      *
      * `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
+     * it through an adapter this class constructed — the three inside this file
+     * (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
@@ -1771,16 +3352,60 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      *
      * 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.
+     * draft save produces no findings to withhold. `mode` on the emitted event is
+     * derived from the response's own `state`, not from the caller's options:
+     * `'draft'` when the server says the row landed as a draft, `'publish'`
+     * otherwise. The server's answer is the one that says which door the write
+     * took, so the event cannot claim a door the request only asked for.
+     *
+     * ## Every argument is forwarded (objectui#12300)
+     *
+     * The SDK's `saveItem(type, name, item, options?)` carries the write's scope
+     * in its fourth argument, `SaveMetaItemOptions`: `packageId` (`?package=`),
+     * `force`, `mode` and `ifMatch`. This wrapper used to name three parameters
+     * and call the original with three, so that bag was dropped before the SDK
+     * saw it. Every caller reaching the SDK through {@link getClient} got a bare
+     * `PUT` whatever it passed, while the declared signature still accepted the
+     * bag, so nothing at the call site could tell. The wrapper now takes and
+     * passes the original's own parameter list, so it forwards whatever the SDK
+     * declares, today's bag and any later member, without naming one.
      */
     private installSaveAdvisoryInterceptor;
+    /**
+     * Route this adapter's client's published view-list read through the one
+     * {@link VIEW_LIST_KEY} (objectui#13044).
+     *
+     * The app-shell `MetadataProvider` reads `client.meta.getItems('view')`
+     * through {@link getClient}; {@link listViews} and {@link listViewOverrides}
+     * read the same `GET /api/v1/meta/view`. Each used to put its own request on
+     * the wire, so one list-page open asked the server three times for one URL.
+     *
+     * A caller of the client keeps its contract, "ask the server": it is never
+     * answered from a settled entry. It joins a request already in flight for
+     * the same URL instead of sending a second one, and its answer is stored
+     * under {@link VIEW_LIST_KEY} (see {@link MetadataCache.share}), which is
+     * what {@link readViewList} answers this adapter's own readers from
+     * (objectui#13057). Only the bare call is routed: any argument after the
+     * type changes the URL, so such a call goes straight to the SDK.
+     *
+     * Every caller gets its own copy of the answer. Before this, every reader
+     * got its own parsed response, so a reader that changed what it was handed
+     * changed nothing anyone else read; a shared answer must not change that.
+     *
+     * Same wrap shape and the same bound as `installSaveAdvisoryInterceptor`:
+     * `meta` is an own property of a client this adapter built and never shares.
+     */
+    private installViewListShare;
+    /**
+     * The published view list for this adapter's own readers
+     * ({@link listViews}, {@link listViewOverrides}): the answer stored under
+     * {@link VIEW_LIST_KEY} while it holds one (objectui#13057), else the
+     * client's read, which joins the request in flight for that key or starts
+     * one, and stores its answer (objectui#13044). Always a copy the caller may
+     * keep. Every path that should see a fresh list drops the key first; the
+     * list is in {@link VIEW_LIST_KEY}'s doc.
+     */
+    private readViewList;
     create(resource: string, data: Partial<T>): Promise<T>;
     /**
      * Update an existing record.
@@ -1840,25 +3465,25 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * @returns Promise resolving to array of results
      */
     /**
-     * Cross-object transactional batch (ObjectStack #1604 / ADR-0034 item 4).
+     * Cross-object transactional batch (objectstack-ai/objectstack#1604 / ADR-0034 item 4).
      * Runs the operations in ONE server transaction — commit all or roll back
      * all. A field value of `{ $ref: <earlier op index> }` resolves to that op's
      * created id, so a child can reference its parent created earlier in the same
      * batch (master-detail).
      *
      * Transport: the published `@objectstack/client` SDK method
-     * `data.batchTransaction` (framework #3271; shipped since client v16, our
+     * `data.batchTransaction` (objectstack-ai/objectstack#3271; shipped since client v16, our
      * dependency floor). Per AGENTS.md §7 data always flows through the client —
      * never a hand-rolled `fetch('/api/v1/batch')`.
      *
-     * Fallback decision — declarative capability negotiation (framework #3298 /
+     * Fallback decision — declarative capability negotiation (objectstack-ai/objectstack#3298 /
      * objectui #2693). At connect() we read `capabilities.transactionalBatch`
      * from discovery:
      *   - Declared `true` → the backend GUARANTEES atomicity (declared ===
      *     enforced). We TRUST it: any batch failure — including 404/405/501 —
      *     surfaces as a real error. No non-atomic client-side compensation. This
      *     is the path modern backends take.
-     *   - Declared `false`, or ABSENT (backend predates #3298) → we can't rely on
+     *   - Declared `false`, or ABSENT (backend predates objectstack-ai/objectstack#3298) → we can't rely on
      *     server atomicity, so we keep the legacy behaviour: on 404/405 (no
      *     endpoint) or 501 (runtime without transactions) degrade to the
      *     client-side, NON-atomic {@link emulateBatchTransaction} so a save is
@@ -1951,6 +3576,30 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * the caller triggers the browser download.
      */
     exportDownload(resource: string, request?: ExportDownloadRequest): Promise<Blob>;
+    /**
+     * Download the server's import template:
+     * `GET /api/v1/data/:object/export?template=true` (objectui#9600).
+     *
+     * Same route as {@link exportDownload}, with the server's template switch. It
+     * sends only `template=true`: the server refuses the export's row parameters
+     * on a template request, and its answer is always an xlsx workbook.
+     *
+     * The server writes the template's labels in the request's locale, and the
+     * import accepts a translated label only in its own request's locale. The
+     * import request goes through `@objectstack/client`, which stamps
+     * `Accept-Language` with the client's locale when one is set (and the host's
+     * `fetch` stamps its own otherwise). This request bypasses the client, so it
+     * stamps the client's locale the same way. Both requests then carry the same
+     * locale.
+     */
+    downloadImportTemplate(resource: string): Promise<Blob>;
+    /**
+     * GET `/api/v1/data/:object/export` with the given query and answer the body
+     * as a Blob. A failure throws an `Error` that carries the server's `status`
+     * and its ADR-0112 `code`. The one request path {@link exportDownload} and
+     * {@link downloadImportTemplate} share.
+     */
+    private fetchExportBlob;
     /**
      * Convert ObjectUI QueryParams to ObjectStack QueryOptions.
      * Maps OData-style conventions to ObjectStack conventions.
@@ -1964,15 +3613,6 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * @returns Promise resolving to the object schema
      */
     getObjectSchema(objectName: string): Promise<unknown>;
-    /**
-     * ADR-0056 P2 (epic #2398) — stamp structured-widget hints onto platform
-     * fields whose framework type is a storage primitive (e.g. `textarea`) but
-     * whose authoring UX should be a structured editor. Only the render `widget`
-     * is added; the field's `type` (the storage contract) is untouched. Applied
-     * idempotently to the cached schema so form + detail both honor it. Widget
-     * components are registered as `field:<widget>` in `@object-ui/fields`.
-     */
-    private applyFieldWidgetOverrides;
     /**
      * Fetch a single object's schema while always revalidating the browser cache.
      *
@@ -2002,6 +3642,27 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         name: string;
         label?: string;
     }>>;
+    /**
+     * List the items one metadata registry type declares —
+     * `GET /api/v1/meta/:type`, through the client's `meta.getItems` — as
+     * `{ name, label }` headers for the `position-ref` / `permission-ref` field
+     * widgets (objectui#7611).
+     *
+     * Unlike {@link getObjects}, a failure REJECTS (the `DataSource` contract):
+     * the transport's own error propagates, and an answer without the spec's
+     * `items` list is refused rather than read as an empty registry, so a
+     * failed load can never reach the widget as "this registry declares
+     * nothing". Uncached, like `getObjects`: an item authored in Studio is
+     * listed on the next form that opens.
+     *
+     * An item without a string `name` is not listed (the widget stores the
+     * name, so there is nothing to store); a `label` that is not a string is
+     * left off rather than coerced.
+     */
+    listMetadataItems(type: string): Promise<Array<{
+        name: string;
+        label?: string;
+    }>>;
     /**
      * Get access to the underlying ObjectStack client for advanced operations.
      */
@@ -2061,9 +3722,10 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * Batch-fetch all persisted view overrides for an object.
      *
      * 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
+     * columns, inlineEdit …) live in the SAME metadata namespace the view
+     * writes use: `type='view'`, `name=<viewId>` (see {@link createView} /
+     * {@link updateView}; the toolbar's `updateViewConfig` wrote overlays there
+     * until objectui#12504 retired it). 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
@@ -2087,9 +3749,9 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      *
      * 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
+     * {@link invalidateViewKeys}. For a long time only `updateViewConfig` (since
+     * retired, objectui#12504) 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
@@ -2113,55 +3775,6 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * @returns Promise resolving to the view definition or null
      */
     getView(objectName: string, viewId: string): Promise<unknown | null>;
-    /**
-     * Persist a toolbar-driven view config patch — density, column widths,
-     * sort, hidden columns, inline edit. Symmetric counterpart to
-     * {@link getView}: writes the row to the server metadata store via
-     * `client.meta.saveItem`, then invalidates the matching cache entry so the
-     * next {@link getView} reflects the new payload. Returns the persisted item
-     * when the server echoes it, otherwise undefined.
-     *
-     * Called from exactly ONE production site — `ObjectView`'s
-     * `persistViewPatch`, for the toolbar toggle — but that ONE call site
-     * fires for BOTH kinds of active tab: a code-defined **system** view (no
-     * row of its own yet) and a genuinely user-created **saved** view (already
-     * has a row — the toggle is editing ITS OWN definition, not laying an
-     * overlay on top of it). Which one a given call means is NOT re-derived
-     * here from the write's shape (objectui#4227's own lesson: shape inference
-     * on this namespace is exactly what let a system view masquerade as
-     * saved) — the caller already knows, via the same `isSavedViewId`
-     * classification that gates the switcher's readonly flag and its five
-     * mutating handlers, and passes it as {@link opts.isSavedView}.
-     *
-     * - `isSavedView` false/omitted (system-view target, the common case and
-     *   the default for backward compatibility): stamps
-     *   {@link VIEW_OVERLAY_MARKER} so {@link listViews} excludes the row —
-     *   the original objectui#4227 fix.
-     * - `isSavedView` true: the marker is withheld. Stamping it here would
-     *   flag the saved view's OWN row as a personalization overlay, and
-     *   `listViews()` would exclude it on the very next read — the user's own
-     *   view would vanish from the switcher the moment they toggled its
-     *   density (objectui#4227 follow-up, PM review on PR #4713, measured:
-     *   `persistViewPatch` has no gate on which kind of tab is active, and
-     *   this method writes to the exact same `(type='view', name=viewId)` key
-     *   {@link createView}/the ADR-0034 `viewEnvelope` seam already used for
-     *   that view, so the write is an upsert onto the saved view's row, not a
-     *   new one).
-     *
-     * Per objectstack#7494's ruling, the overlay this writes (system-view
-     * case) is ORG-WIDE shared view settings, not a per-user preference — a
-     * true per-user scope is a parked v18 direction on the platform side.
-     *
-     * @param objectName - Object name (e.g. 'lead')
-     * @param viewId - View identifier (e.g. 'all_leads')
-     * @param config - Full view definition to persist
-     * @param opts.isSavedView - Whether `viewId` already names a saved view
-     *   (vs. a system view being personalized for the first time). Omit /
-     *   `false` for the default overlay-marking behavior.
-     */
-    updateViewConfig(objectName: string, viewId: string, config: Record<string, any>, opts?: {
-        isSavedView?: boolean;
-    }): Promise<Record<string, any> | void>;
     /**
      * List user-created views for a given object via the metadata overlay
      * API (ADR-0005). Replaces the legacy `find('sys_view', {...})` path
@@ -2173,6 +3786,42 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * 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.
+     *
+     * ## Every failure still degrades to an empty list — and now says which kind
+     * ## of failure it was (objectui#8151)
+     *
+     * The degrade is unchanged and deliberate, exactly as it is one method over
+     * in {@link listImportMappings}: a host with no metadata door keeps answering
+     * `[]` rather than breaking the page. What changed is that the OTHER failures
+     * no longer render as that one.
+     *
+     * This method's empty list is read as *this object has no saved views*, and
+     * that reading reaches the user in two places measured on this tree: the list
+     * view switcher simply shows fewer tabs, and `@object-ui/core`'s
+     * `elementDataSourceViewNotFoundMessage` states it outright. So a session
+     * whose token lapsed mid-read was shown an object that appears to have no
+     * saved views AT ALL — including ones the user created — with a
+     * `console.warn` as the only discriminator, in a console nothing in the UI
+     * points at. That is the silence objectui#7741 removed from the sibling after
+     * it produced a confident wrong diagnosis in objectstack#14026.
+     *
+     * The `catch` now asks {@link classifyViewsFailure} what the failure WAS,
+     * reading the error's own ADR-0112 `code` and status — never "is the result
+     * empty", which is what both conditions produce and so can never tell them
+     * apart — and anything that is not the doorless shape is announced on
+     * {@link onMetadataReadWarning}.
+     *
+     * ⛔ That classifier is a SEPARATE reading, not a second caller of the
+     * sibling's: `view`'s quiet set is strictly smaller, because the arm
+     * `listImportMappings` is built around (*an older server without this kind*)
+     * has no members here. See {@link classifyViewsFailure} for the measurement.
+     *
+     * ⛔ The RETURN is untouched. This method has answered `Promise<any[]>`, never
+     * throwing, since `@object-ui/data-objectstack@17.1.0`; a consumer that reads
+     * nothing new sees exactly what it saw before, including on the loud arms.
+     * Applying framework objectstack#13906 decision 1 option A — *a thing that could not be
+     * READ is not a thing that is ABSENT* — is done by ADDING a channel, not by
+     * moving that contract.
      */
     listViews(objectName: string, options?: {
         previewDrafts?: boolean;
@@ -2186,11 +3835,36 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     private metadataClient;
     /**
      * List registered import `mapping` artifacts targeting a given object
-     * (framework #2611). Reads the `mapping` metadata kind via the overlay API
+     * (objectstack-ai/objectstack#2611). Reads the `mapping` metadata kind via the overlay API
      * and filters by `targetObject` client-side (the metadata index is
-     * name-only). Feeds the import wizard's "saved mapping" selector; a failure
-     * (older server without the `mapping` kind) degrades to an empty list, so
-     * the selector simply doesn't appear.
+     * name-only). Feeds the import wizard's "saved mapping" selector.
+     *
+     * ## Every failure still degrades to an empty list — and now says which kind
+     * ## of failure it was (objectui#7741)
+     *
+     * The degrade is unchanged and deliberate: an older server without the
+     * `mapping` kind must not break the wizard, so it keeps answering `[]` and
+     * the selector simply doesn't appear. That is a real, supported deployment
+     * shape and it stays quiet.
+     *
+     * What changed is that the OTHER failures no longer render as that one. A
+     * refused door and a broken one used to be indistinguishable, in the UI, from
+     * "no mapping is registered" — both were an empty list behind a
+     * `console.warn` nothing pointed at — and that silence produced a confident
+     * wrong diagnosis in a careful reporter (objectstack#14026 was filed, routed
+     * and worked by two seats against a wizard that had been correct since
+     * 17.1.0). So the `catch` now asks {@link classifyImportMappingsFailure} what
+     * the failure WAS, reading the error's own ADR-0112 `code` and status —
+     * never "is the result empty", which is what both conditions produce and so
+     * can never tell them apart — and anything that is not the supported
+     * kind-absent shape is announced on {@link onMetadataReadWarning}.
+     *
+     * ⛔ The RETURN is untouched. This method has answered `Promise<any[]>`, never
+     * throwing, since `@object-ui/data-objectstack@17.1.0`; a consumer that reads
+     * nothing new sees exactly what it saw before, including on the loud arms.
+     * Applying framework objectstack#13906 decision 1 option A — *a thing that could not be
+     * READ is not a thing that is ABSENT* — is done by ADDING a channel, not by
+     * moving that contract.
      */
     listImportMappings(objectName: string): Promise<any[]>;
     /**
@@ -2311,6 +3985,10 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      *   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.
+     *   Its message is the adapter's "NOT fully removed" sentence followed, on
+     *   the next line, by the server's own reason (objectui#12416), so
+     *   `formatMetadataError(err)` shows the remedy a refusal names; the
+     *   original error stays on `cause`.
      *
      * Invalidates through {@link invalidateViewKeys}: the deleted row leaves the
      * batch override map too, and a ghost entry there is what the object page
@@ -2351,11 +4029,17 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      *
      * 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
+     * a by-name probe already implies (objectstack#8013 / PR objectstack-ai/objectstack#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`.
+     * name, an unpublished app, an app gated by an absent optional service — is
+     * one undifferentiated answer.
+     *
+     * ⚠️ That absence is NOT uniformly a `404`, which this docstring asserted
+     * until objectui#9262 measured it: the 404 covers an app that EXISTS and is
+     * withheld for a non-permission reason, while a name that resolves to nothing
+     * answers `200` with an envelope carrying no `item`. Both are absence and both
+     * read as `not_found`; see {@link metaEnvelopeCarriesItem} for the measurement.
      *
      * ## Why this is a separate method and not a flavour of {@link getApp}
      *
@@ -2366,13 +4050,55 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      *    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).
+     * Nothing here throws: every outcome is a verdict the caller renders a screen
+     * from, never a catch block. Only the measured `code` produces `denied` —
+     * never a status, never a message (objectui#4408).
+     *
+     * ## objectui#9262 — what this method stopped folding away
+     *
+     * It used to answer `granted` whenever the call did not throw, and `unknown`
+     * for everything that did. Both halves were wrong in the same direction, and
+     * the first was measured on a real server before this change landed:
+     *
+     *  - **an app that does not exist answers `200` with the envelope minus its
+     *    `item`**, so "did not throw" reported `granted` for a name with nothing
+     *    behind it — the shape issue objectui#9262 listed as cause 8 and expected
+     *    to be structural. It is the ordinary case: every typo, every never-created
+     *    app and every unpublished draft took it. See
+     *    {@link metaEnvelopeCarriesItem} for the measurement and the server-side
+     *    mechanism.
+     *  - a 404 absence and an unreachable server were one `unknown`, though the
+     *    transport had already told them apart.
+     *
+     * The verdicts now say only what was obtained: a served document, a refusal
+     * naming permission, an answer that there is no such app here, or no answer
+     * at all. `unknown` is left for the one case where nothing was asked.
      *
      * @param appName - the app name as it appears in the URL segment
      */
     probeAppAccess(appName: string): Promise<AppAccessVerdict>;
+    /**
+     * {@link probeAppAccess} for any metadata type whose by-name read refuses a
+     * caller (objectui#12112): why `name` is not in this session's list of
+     * `type`, plus the server's own sentence when it refused.
+     *
+     * Since objectstack#22731 a dashboard and a list view carry the app's gate:
+     * `GET /api/v1/meta/dashboard` and `/meta/view` list only what the caller may
+     * open, so a withheld item and a missing one are the same absence there, and
+     * the by-name read of one the caller does not hold answers `403`
+     * `PERMISSION_DENIED`, "the app arm's whole refusal (same emitter, same
+     * envelope)". The verdicts are therefore read exactly as for an app.
+     *
+     * `message` is the refusal's `message`, as the server wrote it: the one
+     * sentence that names the item and says it was refused. Only on `denied`.
+     *
+     * Nothing here throws, and nothing is cached: a verdict about the CALLER
+     * must not outlive a grant.
+     *
+     * @param type - the singular metadata type (`app`, `dashboard`, `view`)
+     * @param name - the item's name, as the by-name route addresses it
+     */
+    probeMetaItemAccess(type: string, name: string): Promise<MetaItemAccess>;
     /**
      * Get a page definition from ObjectStack.
      * Uses the metadata API to fetch page layouts.
@@ -2397,9 +4123,28 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * Uses `this.client.analytics.query()` from @objectstack/client to leverage
      * the SDK's built-in auth, headers, and fetch configuration.
      * Falls back to client-side aggregation via find() if the analytics endpoint
-     * is not available.
+     * is not available. Throws {@link AnalyticsResultShapeError} when it answers
+     * with anything but an `AnalyticsResult` carrying `rows`.
      */
     aggregate(resource: string, params: any): Promise<any[]>;
+    /**
+     * Answer a grouped list view's GROUP HEADER query (objectui#7189) — see
+     * `DataSource.queryGroupHeaders` in `@object-ui/types` for the contract.
+     *
+     * The compiled query rides the platform's EXISTING data door verbatim:
+     * `client.data.query()` posts it to `POST /data/:object/query`, whose
+     * `findData` routes a body carrying `groupBy` / `aggregations` to
+     * `engine.aggregate` and answers the header rows as `records` (the door the
+     * spec half of objectstack#14556 names, pinned platform-side by
+     * objectstack#15330). No new route, no new wire shape.
+     *
+     * ⛔ No fallback, deliberately — unlike {@link aggregate}. A header query that
+     * degraded to bucketing a fetched page would answer page slices under a name
+     * that promises the query's own numbers, which is the defect this member
+     * exists to end. A failure is thrown to the caller, and a body without a
+     * `records` array is refused rather than read as "no groups".
+     */
+    queryGroupHeaders(resource: string, query: EngineAggregateOptions): Promise<ListViewGroupHeaderRow[]>;
     /**
      * Client-side aggregation over a server-scoped `find()` — the fallback used
      * whenever the analytics endpoint cannot answer (capability absent, network
@@ -2585,6 +4330,21 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
 /**
  * Factory function to create an ObjectStack data source.
  *
+ * The declared return is `ObjectStackAdapter<T>`, not the shared
+ * `DataSource<T>` interface: the object this hands back is an
+ * `ObjectStackAdapter`, and the adapter-only members the package README
+ * documents — `getClient`, the metadata-cache controls, the connection-state
+ * and batch-progress subscriptions — live on the class, not on `DataSource`.
+ * Declaring the interface here narrowed all of them
+ * away from the factory while leaving them on the value (objectui#7323), so
+ * `createObjectStackAdapter(...)` and `new ObjectStackAdapter(...)` — the two
+ * documented ways to obtain the same object — handed back different type
+ * surfaces. ⛔ Do not narrow this back to `DataSource<T>`: a caller who wants
+ * the narrow surface writes `const ds: DataSource = createObjectStackAdapter(…)`
+ * and gets it, because a wider return is assignable to the narrower annotation;
+ * the reverse is not recoverable at the call site without a cast.
+ * `adapterFactoryReturn.types.test.ts` pins both directions.
+ *
  * @example
  * ```typescript
  * const dataSource = createObjectStackAdapter({
@@ -2607,6 +4367,6 @@ declare function createObjectStackAdapter<T = unknown>(config: {
     autoReconnect?: boolean;
     maxReconnectAttempts?: number;
     reconnectDelay?: number;
-}): DataSource<T>;
+}): ObjectStackAdapter<T>;
 
-export { API_ACCESS_DENIED_CODES, APP_PERMISSION_DENIED_CODE, AnalyticsDatasetNotFoundError, AnalyticsNotInstalledError, AnalyticsQueryRejectedError, AnalyticsUnauthenticatedError, type AppAccessVerdict, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, ConcurrentUpdateError, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, DataApiValidationError, FILTER_OPERATOR_ALIASES, MalformedFilterError, type MetadataAuditEntry, type MetadataAuditResponse, type MetadataCacheStats, MetadataClient, type MetadataClientConfig, type MetadataClientSaveOptions, type MetadataDeleteOptions, type MetadataDiagnostics, type MetadataDiagnosticsEntry, type MetadataDiagnosticsOptions, type MetadataDiagnosticsSummary, type MetadataDraftHeader, type MetadataError, type MetadataGetOptions, type MetadataHistoryOptions, type MetadataLayered, type MetadataListOptions, type MetadataLockState, MetadataNotFoundError, type MetadataOverlayScope, type MetadataReference, type MetadataSaveAdvisoryEvent, type MetadataSaveAdvisoryListener, type MetadataValidationIssue, ObjectStackAdapter, ObjectStackError, type ObjectStackUserStateAdapterOptions, type UserDataAdapter, VIEW_OVERLAY_OWNED_KEYS, type WriteWarningEvent, type WriteWarningListener, classifyAnalyticsFailure, clearSharedDiscoveryCache, createErrorFromResponse, createObjectStackAdapter, createObjectStackUserStateAdapter, createQuietHttpLogger, formatHttpFailureMessage, getSharedDiscovery, is404Error, isAnalyticsNotInstalledError, isApiAccessDeniedError, isAppPermissionDeniedError, isConcurrentUpdateError, isErrorType, isMalformedFilterError, isObjectStackError, narrowPersonalizationOverlay, normaliseClientError, readSaveAdvisories, readTransactionalBatchCapability, serializeOrderBy, viewItemObjectName };
+export { API_ACCESS_DENIED_CODES, APP_PERMISSION_DENIED_CODE, AnalyticsDatasetNotFoundError, AnalyticsForbiddenError, AnalyticsKeysOnSpecShapeError, AnalyticsNotInstalledError, AnalyticsQueryRejectedError, AnalyticsResultShapeError, AnalyticsUnauthenticatedError, type AppAccessVerdict, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, CHOICE_TYPES_REQUIRING_OPTIONS, ConcurrentUpdateError, ConnectionError, type ConnectionStateEvent, type ConnectionStateListener, DataApiValidationError, type DraftChange, type DroppedFieldsNotice, FILTER_OPERATOR_ALIASES, type ImportMappingsFailureKind, META_ITEM_ABSENT_CODE, MalformedFilterError, type MetaItemAccess, 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 MetadataListAnswer, type MetadataListOptions, type MetadataLockState, MetadataNotFoundError, type MetadataOverlayScope, type MetadataReadFailureKind, type MetadataReadWarningEvent, type MetadataReadWarningListener, type MetadataReference, type MetadataSaveAdvisoryEvent, type MetadataSaveAdvisoryListener, type MetadataValidationIssue, OBJECT_METADATA_TYPE, ObjectStackAdapter, ObjectStackError, type ObjectStackUserPreferenceFamilyOptions, type ObjectStackUserStateAdapterOptions, PREFERENCE_FAMILY_ROW_LIMIT, RELATIONSHIP_TYPES_REQUIRING_REFERENCE, UNRECOGNIZED_DROP_REASON, UnlowerableAnalyticsFilterError, UnloweredAggregateWhereError, type UnrecognizedDropReasonEvent, type UserDataAdapter, type UserPreferenceFamily, VIEW_OVERLAY_OWNED_KEYS, type WriteWarningEvent, type WriteWarningListener, assertObjectMetadataWritable, classifyAnalyticsFailure, classifyImportMappingsFailure, classifyViewsFailure, clearSharedDiscoveryCache, createErrorFromResponse, createObjectStackAdapter, createObjectStackUserPreferenceFamily, createObjectStackUserStateAdapter, createQuietHttpLogger, draftChangesUnder, dropServedPicklistOptions, extractDraftBody, formatHttpFailureMessage, formatMetadataError, formatMetadataIssue, getSharedDiscovery, governingDraftChange, is404Error, isAnalyticsNotInstalledError, isApiAccessDeniedError, isAppPermissionDeniedError, isConcurrentUpdateError, isErrorType, isMalformedFilterError, isMetaItemAbsentError, isObjectStackError, narrowPersonalizationOverlay, normaliseClientError, readDraftChanges, readSaveAdvisories, readTransactionalBatchCapability, serializeOrderBy, viewItemObjectName };