@object-ui/data-objectstack 17.6.0 → 17.7.0

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 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 { GetMetaItemLayeredResponse, RuntimeAuthoringIssue, PublishPackageDraftsResponse } 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';
@@ -15,42 +16,41 @@ import { DatasetDrillRange } from '@object-ui/core';
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/**
- * MetadataClient
- *
- * Thin, framework-agnostic HTTP client for the ObjectStack metadata
- * API (`/api/v1/meta/*`). Used by the platform Setup app surfaces in
- * `@object-ui/plugin-designer` (Object Manager, Field Designer, etc.)
- * so they can read and write protocol metadata without depending on
- * `ObjectStackAdapter` (which is a generic data-source binding and
- * carries a lot of view/dashboard-specific behaviour we don't need
- * here).
- *
- * Endpoints (see `packages/rest/src/rest-server.ts`):
- *   GET    /api/v1/meta                  — list all metadata types
- *   GET    /api/v1/meta/:type            — list items of a type
- *   GET    /api/v1/meta/:type/:name      — get one item (returns the
- *                                          unwrapped item content)
- *   PUT    /api/v1/meta/:type/:name      — save (overlay) one item
- *                                          honours `If-Match` for OCC
- *   DELETE /api/v1/meta/:type/:name      — reset overlay to artifact
- *   GET    /api/v1/meta/:type/:name/history — durable change log
- *
- * The client deliberately keeps the response shape opaque (typed as
- * `unknown`/generic `T`) so callers explicitly narrow per-metadata-
- * type, mirroring the framework's "single Zod source per type" rule.
- */
 
 /**
- * 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'`). */
@@ -65,15 +65,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.
- *
- * The server omits the key entirely on a clean save, so `undefined` is the
+ * Read the `advisories` array off a metadata write response, defensively.
+ *
+ * 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 +155,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`,
@@ -136,6 +190,28 @@ interface MetadataDraftHeader {
     updatedAt: string | null;
     updatedBy: string | null;
 }
+/**
+ * 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>;
 /**
  * Options for {@link MetadataClient.save} — a WRITE OVER HTTP to
  * `/api/v1/meta/:type/:name`.
@@ -246,9 +322,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 +379,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 +538,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. */
@@ -517,12 +612,42 @@ 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.
      */
     getDraft<T = unknown>(type: string, name: string, options?: {
         packageId?: string;
     }): Promise<T | null>;
+    /**
+     * 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,6 +666,61 @@ 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.
      */
     publishDraft(type: string, name: string): Promise<{
         success?: boolean;
@@ -552,6 +732,53 @@ 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.
+     */
+    publishPackageDrafts(packageId: string): Promise<MetadataPublishPackageDraftsResult>;
     /**
      * Get the 3-state layered view of a metadata item: `code` (the packaged
      * artifact baseline), `overlay` (the tenant customisation row alone) and
@@ -615,9 +842,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`).
@@ -911,6 +1145,227 @@ interface UserDataAdapter<T> {
  */
 declare function createObjectStackUserStateAdapter<T = unknown>(options: ObjectStackUserStateAdapterOptions): UserDataAdapter<T>;
 
+/**
+ * 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 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.
+ *
+ * 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`
+ *     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.
+ *
+ * ⛔ **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.
+ *     `FieldSchema` cannot answer this one yet, because the door has not shipped.
+ *
+ * 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.
+ *
+ * @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
+ * @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
  * (e.g. `lead.view.ts`) to the canonical operator symbols expected by the
@@ -947,6 +1402,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 +1584,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 +1597,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 +1650,38 @@ 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).
- *
- *  - `granted` — the route served the app document.
- *  - `denied`  — the app EXISTS and the session lacks its `requiredPermissions`.
- *    The only verdict a caller may render as an authorization refusal.
- *  - `unknown` — anything else: an absent app, an unpublished one, an app
- *    withheld by an absent optional service, an unreachable server, an adapter
- *    that cannot ask. All of these are cases where the server declined to say
- *    that a permission of the caller's is missing, so no caller may claim it.
- *
- * Three values rather than a boolean because the third is not a shade of the
- * other two: "the app is missing" and "I could not find out" both have to leave
- * the caller's existing copy alone, and collapsing them into `false` invites a
- * consumer to read a failed probe as a positive absence.
+ * (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.
+ *  - `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.
+ *
+ * ## 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' | 'unknown';
+type AppAccessVerdict = 'granted' | 'denied' | 'not_found' | 'unreachable' | 'unknown';
 /**
  * The ADR-0112 standard catalog code the by-name meta app route answers with
  * when an app exists and the session lacks its `requiredPermissions`
@@ -1084,9 +1705,87 @@ 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;
+/**
+ * [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 / #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 +1893,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 +1944,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 +2034,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 +2093,48 @@ 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 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
+ * 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 +2147,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;
 /**
@@ -1408,20 +2230,295 @@ 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
+ * (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}.
+ *
+ * `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).
  */
 interface WriteWarningEvent {
     operation: 'create' | 'update';
     resource: string;
     id?: string | number;
-    droppedFields: DroppedFieldsEvent[];
+    droppedFields: DroppedFieldsNotice[];
 }
 /** 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 +2538,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
@@ -1477,10 +2583,12 @@ declare function viewItemObjectName(item: any): string | undefined;
  *
  * - **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.
+ *   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#9933, released in
+ *   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
@@ -1506,8 +2614,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 +2636,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;
 
@@ -1585,6 +2695,8 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     private mutationListeners;
     private writeWarningListeners;
     private saveAdvisoryListeners;
+    private metadataReadWarningListeners;
+    private systemCapabilities;
     constructor(config: {
         baseUrl: string;
         token?: string;
@@ -1596,6 +2708,13 @@ 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.
@@ -1644,7 +2763,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
@@ -1680,14 +2799,20 @@ 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`).
      */
     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 +2826,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 +2835,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 +2859,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).
      *
@@ -1840,25 +2991,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 +3102,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.
@@ -2159,6 +3334,33 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      *   (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>;
@@ -2173,6 +3375,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 +3424,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[]>;
     /**
@@ -2351,11 +3614,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,9 +3635,29 @@ 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
      */
@@ -2397,9 +3686,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 +3893,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, and `setSystemCapabilities` — 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 +3930,8 @@ declare function createObjectStackAdapter<T = unknown>(config: {
     autoReconnect?: boolean;
     maxReconnectAttempts?: number;
     reconnectDelay?: number;
-}): DataSource<T>;
+    /** [ADR-0066] See {@link ObjectStackAdapter.setSystemCapabilities}. */
+    systemCapabilities?: string[];
+}): 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 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 };