@object-ui/data-objectstack 17.7.0 → 18.0.0

package/dist/index.d.ts

@@ -2,13 +2,113 @@ import { ObjectStackClient } from '@objectstack/client';
 import { DroppedFieldsEvent, EngineAggregateOptions } from '@objectstack/spec/data';
 export { DroppedFieldsEvent } from '@objectstack/spec/data';
 import { ListViewGroupHeaderRow } from '@objectstack/spec/ui';
-import { GetMetaItemLayeredResponse, RuntimeAuthoringIssue, PublishPackageDraftsResponse } from '@objectstack/spec/api';
+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';
 
+/**
+ * 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.
+ *
+ * ## 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];
+/**
+ * The `draftChanges` of a served draft envelope — the value
+ * {@link MetadataClient.getDraft} resolved to — or `null` when the read
+ * recorded none.
+ *
+ * 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").
+ *
+ * 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.
@@ -57,6 +157,15 @@ interface MetadataSaveAdvisoryEvent {
     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
@@ -178,18 +287,50 @@ 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
@@ -212,6 +353,26 @@ interface MetadataDraftHeader {
  * 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`.
@@ -222,17 +383,41 @@ type MetadataPublishPackageDraftsResult = Partial<PublishPackageDraftsResponse>
  * 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
@@ -253,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 {
     /**
@@ -269,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
@@ -278,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
@@ -549,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
@@ -626,10 +866,39 @@ declare class MetadataClient {
      * (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
@@ -721,8 +990,22 @@ declare class MetadataClient {
      * {@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;
@@ -777,8 +1060,18 @@ declare class MetadataClient {
      * 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): Promise<MetadataPublishPackageDraftsResult>;
+    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
@@ -834,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>;
     /**
@@ -1111,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
  */
 
@@ -1133,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.
  *
@@ -1144,62 +1493,117 @@ 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;
+}
 /**
- * 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.
- *
- * ## 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
+ * 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.
  *
- * 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".
+ * 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.
  */
-declare function extractDraftBody(resp: unknown): Record<string, unknown> | null;
+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`.
@@ -1272,36 +1676,31 @@ declare function formatMetadataError(e: unknown): string;
  * 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.
  *
- * The two invariants stand in different relations to the server, and the
- * dead-bolt argument is made separately for each:
- *
- *   - The relationship refusal forecloses nothing the server would have taken:
- *     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 is deliberately AHEAD of the server. The installed
- *     `@objectstack/spec` still accepts a choice with no option source, and the
- *     ruling closes the client order first on purpose — its execution parameter
- *     (2) reads "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". So this refusal does hold a body the server would store
- *     today. It is not a dead-bolt, for the reason the ruling gives and the
- *     reason the editors give: the ruling makes the same body a server refusal
- *     once the door closes (a stored row is named and every later save of that
- *     object is refused until it gains options), and the message names the
- *     field on every surface that holds one. The Studio data page and the
- *     metadata-admin object editor carry an options editor in that field's
- *     inspector, so the hold clears on screen, including for an object that
- *     already stores such a field (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`
+ * 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 "still
- *     accepted by the installed server" on every run; when the door ships and
- *     the pin moves, that reading turns red, and this paragraph collapses into
- *     the relationship one above.
+ *     `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 —
@@ -1323,7 +1722,7 @@ declare function formatMetadataError(e: unknown): string;
  *   - 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.
- *     `FieldSchema` cannot answer this one yet, because the door has not shipped.
+ *     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.
@@ -1359,12 +1758,25 @@ declare const OBJECT_METADATA_TYPE = "object";
  * `fields` member — this door serves `view`, `app`, `flow`, `permission`,
  * `hook` and `dashboard` writes too, and has no opinion about them.
  *
- * @param type   the metadata type segment of the write (`'object'`, `'view'`, …)
- * @param item   the body about to be serialised onto the wire
- * @param writer a short label for the door, so the message names where it fired
+ * ## 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;
+declare function assertObjectMetadataWritable(type: unknown, item: unknown, _writer: string): void;
 
 /**
  * Map human-readable filter operator names produced by SDUI view configs
@@ -1682,6 +2094,20 @@ declare function isApiAccessDeniedError(error: unknown): boolean;
  * 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}).
+ */
+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`
@@ -1728,61 +2154,6 @@ declare const META_ITEM_ABSENT_CODE = "RESOURCE_NOT_FOUND";
  * so the honest reading is that no answer was obtained.
  */
 declare function isMetaItemAbsentError(error: unknown): boolean;
-/**
- * [ADR-0066] The system capability a view-configuration write requires.
- *
- * objectstack#7494's ruling (maintainer, 2026-08-12) settled what this store
- * IS: the `sort` / `hiddenFields` / `columnState` / `rowHeight` persisted by
- * {@link ObjectStackAdapter.updateViewConfig} are ORG-WIDE view configuration
- * — shared by every user of the view — not a per-user preference. A per-user
- * scope is parked (objectstack#7611, v18) and deliberately NOT built here, so
- * there is no second, narrower store for an ungated write to fall back to:
- * the only thing this write can do is change the view for everyone.
- *
- * That makes a toolbar toggle a metadata-authoring act, so it gates on the
- * capability this repo ALREADY uses for metadata authoring rather than a newly
- * minted name. `manage_metadata` is what `HomePage`'s `AUTHORING_CAPABILITY`
- * gates the builder CTAs on, what the server itself refuses metadata writes
- * without (`PackageFormDialog` reads that 403), and what
- * `capability.label.manage_metadata` is already translated as in all ten
- * locale packs. Decisively: the write gated here goes through
- * `client.meta.saveItem` — the very same ADR-0005 metadata door — so this is
- * the same authority the server is already applying, not an analogous one.
- */
-declare const VIEW_CONFIG_CAPABILITY = "manage_metadata";
-/**
- * Thrown by {@link ObjectStackAdapter.updateViewConfig} when the session's
- * REPORTED capability set does not contain {@link VIEW_CONFIG_CAPABILITY}.
- *
- * Raised BEFORE `connect()` and before `saveItem`, so a refused call issues no
- * request at all — the org-wide row is not touched, not even optimistically.
- *
- * Deliberately an ERROR and not a silent `return`. The production caller is a
- * debounced toolbar toggle whose UI has ALREADY moved by the time this runs, so
- * a quiet no-op would leave the operator looking at a density they did not get,
- * with nothing to explain it and a reload to discover it. The message names the
- * SCOPE first and the capability second, in that order, because the scope is
- * the part the operator cannot otherwise see — and it is written to be shown
- * as-is, the same contract {@link AnalyticsNotInstalledError} states.
- */
-declare class ViewConfigPermissionDeniedError extends Error {
-    readonly code = "VIEW_CONFIG_PERMISSION_DENIED";
-    /** The capability that was required and not held. */
-    readonly capability = "manage_metadata";
-    /** The object whose view configuration the refused write targeted. */
-    readonly objectName: string;
-    /** The view id the refused write targeted. */
-    readonly viewId: string;
-    constructor(objectName: string, viewId: string);
-}
-/**
- * True when `error` is a {@link ViewConfigPermissionDeniedError}.
- *
- * Duck-checks `code`/`name` rather than using `instanceof`, matching
- * {@link isConcurrentUpdateError}: a host that bundles this package twice
- * (or re-throws across a worker boundary) still gets the right verdict.
- */
-declare function isViewConfigPermissionDeniedError(error: unknown): error is ViewConfigPermissionDeniedError;
 /**
  * Thrown when the deployment has no analytics capability installed
  * (framework#3891 / objectstack-ai/objectstack#4019).
@@ -2121,11 +2492,9 @@ declare class ConcurrentUpdateError extends Error {
  * 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 that {@link isViewConfigPermissionDeniedError} documents and
- * cites *this* function as its precedent for — 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
+ * 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
@@ -2199,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
  */
@@ -2281,20 +2647,31 @@ interface UnrecognizedDropReasonEvent {
 type DroppedFieldsNotice = DroppedFieldsEvent | UnrecognizedDropReasonEvent;
 /**
  * Emitted after a create/update whose response carried `droppedFields`
- * (objectstack-ai/objectstack#3431 / objectstack-ai/objectstack#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).
+ * 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: DroppedFieldsNotice[];
+    warnings?: ValidateDataIssue[];
 }
 /** Event listener type for write-warning (dropped-fields) events. */
 type WriteWarningListener = (event: WriteWarningEvent) => void;
@@ -2562,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
@@ -2578,22 +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 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, `buildPersistedViewBody` in app-shell's
- *   `ObjectView`, 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 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.
+ * - **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.
@@ -2601,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"];
 /**
@@ -2689,6 +3069,7 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     private analyticsCapabilityWarned;
     private fetchImpl;
     private inflightFinds;
+    private inflightFindOnes;
     private missingResources;
     private batchUnsupported;
     private atomicBatchCapability;
@@ -2696,7 +3077,6 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     private writeWarningListeners;
     private saveAdvisoryListeners;
     private metadataReadWarningListeners;
-    private systemCapabilities;
     constructor(config: {
         baseUrl: string;
         token?: string;
@@ -2708,19 +3088,22 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         autoReconnect?: boolean;
         maxReconnectAttempts?: number;
         reconnectDelay?: number;
-        /**
-         * [ADR-0066] The session's system capabilities, when the host already has
-         * them at construction time. Most hosts do NOT — `/me/permissions`
-         * resolves after the adapter exists — and push them in later via
-         * {@link ObjectStackAdapter.setSystemCapabilities}. Omit for "unreported".
-         */
-        systemCapabilities?: string[];
     });
     /**
      * 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
      */
@@ -2745,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
      */
@@ -2754,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.
      *
@@ -2776,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.
      */
@@ -2809,6 +3235,10 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * 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;
     /**
@@ -2892,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
@@ -2922,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.
@@ -3139,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.
      *
@@ -3177,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.
      */
@@ -3236,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
@@ -3262,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
@@ -3288,82 +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.
-     */
-    /**
-     * [ADR-0066] Tell this adapter which system capabilities the session holds.
-     *
-     * Pass `undefined` for "no answer was reported" (a backend predating
-     * ADR-0066, or no permission provider mounted). Pass `[]` for a real,
-     * reported, empty grant — {@link maySetViewConfig} treats those two
-     * differently and callers must not collapse them, which is the same
-     * distinction `MePermissionsProvider` preserves natively (objectui#4656).
-     */
-    setSystemCapabilities(capabilities: string[] | undefined): void;
-    /**
-     * May this session write ORG-WIDE view configuration?
-     *
-     * **Unknown fails OPEN**, deliberately, and this is the one judgement in the
-     * gate worth reading twice. It is the doctrine `PermissionContextValue`
-     * .`hasCapabilities` states for every ADR-0066 gate in this repo
-     * (objectui#4656, framework#3923): the server enforces `manage_metadata` on
-     * the metadata door regardless of what the client believes, so a client-side
-     * denial on MISSING DATA cannot protect anything the server was not already
-     * protecting — it can only break a permitted user. Failing closed here would
-     * have refused the write on every deployment predating ADR-0066 and every
-     * host with no permission provider, which is "break the write for everyone"
-     * wearing the costume of a security fix.
-     *
-     * A REPORTED empty array gates strictly: "holds nothing" is a real answer.
-     */
-    private maySetViewConfig;
-    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
@@ -3574,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
@@ -3662,6 +4077,28 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * @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.
@@ -3897,8 +4334,8 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
  * `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, and `setSystemCapabilities` — live on the
- * class, not on `DataSource`. Declaring the interface here narrowed all of them
+ * 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
@@ -3930,8 +4367,6 @@ declare function createObjectStackAdapter<T = unknown>(config: {
     autoReconnect?: boolean;
     maxReconnectAttempts?: number;
     reconnectDelay?: number;
-    /** [ADR-0066] See {@link ObjectStackAdapter.setSystemCapabilities}. */
-    systemCapabilities?: string[];
 }): ObjectStackAdapter<T>;
 
-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 ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, DataApiValidationError, type DroppedFieldsNotice, FILTER_OPERATOR_ALIASES, type ImportMappingsFailureKind, META_ITEM_ABSENT_CODE, 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 MetadataReadFailureKind, type MetadataReadWarningEvent, type MetadataReadWarningListener, type MetadataReference, type MetadataSaveAdvisoryEvent, type MetadataSaveAdvisoryListener, type MetadataValidationIssue, OBJECT_METADATA_TYPE, ObjectStackAdapter, ObjectStackError, type ObjectStackUserStateAdapterOptions, RELATIONSHIP_TYPES_REQUIRING_REFERENCE, UNRECOGNIZED_DROP_REASON, UnlowerableAnalyticsFilterError, UnloweredAggregateWhereError, type UnrecognizedDropReasonEvent, type UserDataAdapter, VIEW_CONFIG_CAPABILITY, VIEW_OVERLAY_OWNED_KEYS, ViewConfigPermissionDeniedError, type WriteWarningEvent, type WriteWarningListener, assertObjectMetadataWritable, classifyAnalyticsFailure, classifyImportMappingsFailure, classifyViewsFailure, clearSharedDiscoveryCache, createErrorFromResponse, createObjectStackAdapter, createObjectStackUserStateAdapter, createQuietHttpLogger, extractDraftBody, formatHttpFailureMessage, formatMetadataError, formatMetadataIssue, getSharedDiscovery, is404Error, isAnalyticsNotInstalledError, isApiAccessDeniedError, isAppPermissionDeniedError, isConcurrentUpdateError, isErrorType, isMalformedFilterError, isMetaItemAbsentError, isObjectStackError, isViewConfigPermissionDeniedError, 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 };