@object-ui/data-objectstack 6.2.3 → 7.1.0

package/dist/index.cjs

@@ -814,9 +814,12 @@ var MetadataClient = class _MetadataClient {
     __publicField(this, "base");
     __publicField(this, "fetchImpl");
     __publicField(this, "headers");
+    /** ADR-0037: when true, reads render the draft-overlaid world. */
+    __publicField(this, "previewDrafts");
     this.base = buildBase(config);
     this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
     this.headers = { Accept: "application/json", ...config.headers ?? {} };
+    this.previewDrafts = config.previewDrafts === true;
   }
   /** Update the client's environment scope at runtime. */
   withEnvironment(environmentId) {
@@ -824,7 +827,24 @@ var MetadataClient = class _MetadataClient {
       baseUrl: this.base.replace(/\/api\/v\d+(?:\/environments\/[^/]+)?\/meta$/, "").replace(/\/+$/, ""),
       environmentId,
       fetch: this.fetchImpl,
-      headers: this.headers
+      headers: this.headers,
+      previewDrafts: this.previewDrafts
+    });
+  }
+  /**
+   * Derive a client whose reads render the draft-overlaid world (or not).
+   * Same base/fetch/headers; used by the app-shell to switch the whole
+   * renderer tree into ADR-0037 preview mode off one URL flag.
+   */
+  withPreviewDrafts(previewDrafts) {
+    if (previewDrafts === this.previewDrafts) return this;
+    const envMatch = this.base.match(/\/api\/v\d+\/environments\/([^/]+)\/meta$/);
+    return new _MetadataClient({
+      baseUrl: this.base.replace(/\/api\/v\d+(?:\/environments\/[^/]+)?\/meta$/, "").replace(/\/+$/, ""),
+      ...envMatch ? { environmentId: decodeURIComponent(envMatch[1]) } : {},
+      fetch: this.fetchImpl,
+      headers: this.headers,
+      previewDrafts
     });
   }
   /** List all registered metadata types (returns the registry rows). */
@@ -842,7 +862,10 @@ var MetadataClient = class _MetadataClient {
   }
   /** List items of a metadata type (e.g. `object`, `field`, `view`). */
   async list(type, options = {}) {
-    const qs = options.packageId ? `?package=${encodeURIComponent(options.packageId)}` : "";
+    const params = [];
+    if (options.packageId) params.push(`package=${encodeURIComponent(options.packageId)}`);
+    if (this.previewDrafts) params.push("preview=draft");
+    const qs = params.length ? `?${params.join("&")}` : "";
     const url = `${this.base}/${encodeURIComponent(type)}${qs}`;
     const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
     if (!res.ok) throw await parseError(res);
@@ -853,25 +876,70 @@ var MetadataClient = class _MetadataClient {
     }
     return [];
   }
+  /**
+   * List pending DRAFT items (ADR-0033) — what an AI authored but nobody
+   * published yet. `list()` only sees published/active metadata, so a
+   * just-built app package looks empty there; this surfaces the drafts so the
+   * console can show a "pending changes" view and draft-aware package contents.
+   * Optionally narrow by `packageId` and/or `type`. Returns light headers
+   * (no body) carrying `packageId` for grouping.
+   */
+  async listDrafts(options = {}) {
+    const params = [];
+    if (options.packageId) params.push(`packageId=${encodeURIComponent(options.packageId)}`);
+    if (options.type) params.push(`type=${encodeURIComponent(options.type)}`);
+    const qs = params.length ? `?${params.join("&")}` : "";
+    const url = `${this.base}/_drafts${qs}`;
+    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
+    if (!res.ok) throw await parseError(res);
+    const data = await res.json();
+    if (Array.isArray(data)) return data;
+    return data?.drafts ?? data?.data?.drafts ?? [];
+  }
   /**
    * Get a single metadata item. Returns the unwrapped item content
    * (matching the framework REST handler which calls `res.json(item)`).
    * Returns `null` on 404 to keep the call-site ergonomic.
    */
-  async get(type, name) {
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}`;
+  async get(type, name, options = {}) {
+    const params = [];
+    if (options.state === "draft") params.push("state=draft");
+    else if (this.previewDrafts) params.push("preview=draft");
+    if (options.packageId) params.push(`package=${encodeURIComponent(options.packageId)}`);
+    const qs = params.length ? `?${params.join("&")}` : "";
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}${qs}`;
     const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
     if (res.status === 404) return null;
     if (!res.ok) throw await parseError(res);
     return await res.json();
   }
+  /**
+   * Read the pending draft body for an item (`?state=draft`). Returns
+   * `null` when there is no draft pending. Draft reads do NOT fall
+   * back to the published overlay or the artifact registry — a `null`
+   * unambiguously means "nothing to publish".
+   *
+   * Note: the framework wraps draft responses in an envelope
+   * `{ type, name, item }` (matching `getMetaItem`); callers should
+   * read `.item` to get the body. The legacy `get()` returns the
+   * unwrapped body, so this method preserves that asymmetry by
+   * returning whatever the server sent.
+   */
+  async getDraft(type, name, options = {}) {
+    return this.get(type, name, { state: "draft", ...options.packageId ? { packageId: options.packageId } : {} });
+  }
   /**
    * Save (PUT) a metadata item. The framework accepts both the bare
    * item payload and the `{ item: ... }` / `{ metadata: ... }`
-   * envelopes; we send bare for consistency.
+   * envelopes; we send bare for consistency. Pass `mode: 'draft'` to
+   * stage the change without publishing (Studio's "Save" button).
    */
   async save(type, name, item, options = {}) {
-    const qs = options.force ? "?force=true" : "";
+    const params = [];
+    if (options.force) params.push("force=true");
+    if (options.mode === "draft") params.push("mode=draft");
+    if (options.packageId) params.push(`package=${encodeURIComponent(options.packageId)}`);
+    const qs = params.length ? `?${params.join("&")}` : "";
     const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}${qs}`;
     const headers = {
       ...this.headers,
@@ -887,13 +955,38 @@ var MetadataClient = class _MetadataClient {
     if (!res.ok) throw await parseError(res);
     return await res.json();
   }
+  /**
+   * Publish a single pending draft BY REFERENCE — promotes the draft row for
+   * `(type, name)` into the active overlay and drops the draft. Works for ANY
+   * draft, including ones with no `packageId` binding (which the package-scoped
+   * `/packages/:id/publish-drafts` flow cannot reach). Use this to publish the
+   * exact set returned by {@link listDrafts} without needing a package.
+   *
+   * Returns the server result. For `seed` drafts the protocol also materializes
+   * the rows and reports under `seedApplied` — a data problem never fails the
+   * publish, so callers should check `seedApplied?.success` and warn the user
+   * rather than assume the data went live.
+   */
+  async publishDraft(type, name) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/publish`;
+    const res = await this.fetchImpl(url, {
+      method: "POST",
+      headers: { ...this.headers, "Content-Type": "application/json", Accept: "application/json" },
+      body: "{}"
+    });
+    if (!res.ok) throw await parseError(res);
+    const body = await res.json().catch(() => ({}));
+    const inner = body?.data && typeof body.data === "object" ? body.data : body;
+    return inner;
+  }
   /**
    * Get the 3-state layered view of a metadata item (Phase 3a). Returns
    * `code` (the artifact / fallback default), `overlay` (the saved
    * customisation, if any), and `effective` (what the runtime sees).
    */
-  async layered(type, name) {
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}?layers=true`;
+  async layered(type, name, options = {}) {
+    const pkg = options.packageId ? `&package=${encodeURIComponent(options.packageId)}` : "";
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}?layers=true${pkg}`;
     const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
     if (res.status === 404) {
       return { code: null, overlay: null, overlayScope: null, effective: null };
@@ -913,7 +1006,50 @@ var MetadataClient = class _MetadataClient {
       code: body.code ?? null,
       overlay: body.overlay ?? null,
       overlayScope: body.overlayScope ?? null,
-      effective: body.effective ?? null
+      effective: body.effective ?? null,
+      ...body._diagnostics ? { _diagnostics: body._diagnostics } : {},
+      // ADR-0010 Phase 4 — pass through the metadata-protection envelope so
+      // the editor can render lock affordances without a second round trip.
+      ...body.lock !== void 0 ? { lock: body.lock } : {},
+      ...body.lockReason !== void 0 ? { lockReason: body.lockReason } : {},
+      ...body.lockSource !== void 0 ? { lockSource: body.lockSource } : {},
+      ...body.lockDocsUrl !== void 0 ? { lockDocsUrl: body.lockDocsUrl } : {},
+      ...body.provenance !== void 0 ? { provenance: body.provenance } : {},
+      ...body.packageId !== void 0 ? { packageId: body.packageId } : {},
+      ...body.packageVersion !== void 0 ? { packageVersion: body.packageVersion } : {},
+      ...body.editable !== void 0 ? { editable: body.editable } : {},
+      ...body.deletable !== void 0 ? { deletable: body.deletable } : {},
+      ...body.resettable !== void 0 ? { resettable: body.resettable } : {}
+    };
+  }
+  /**
+   * Cross-type sweep of load-time validation results — calls
+   * `GET /meta/diagnostics`. Returns every entry the framework
+   * considers invalid (or, when `severity: 'warning'`, also entries
+   * with only warnings).
+   *
+   * Used by the Studio's governance overview page and by the
+   * directory page to show "N invalid" badges per metadata type.
+   */
+  async diagnostics(options = {}) {
+    const params = [];
+    if (options.type) params.push(`type=${encodeURIComponent(options.type)}`);
+    if (options.severity) params.push(`severity=${encodeURIComponent(options.severity)}`);
+    if (options.packageId) params.push(`package=${encodeURIComponent(options.packageId)}`);
+    const qs = params.length ? `?${params.join("&")}` : "";
+    const url = `${this.base}/diagnostics${qs}`;
+    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
+    if (res.status === 404) {
+      return { entries: [], total: 0, scannedTypes: 0, scannedItems: 0, stats: {} };
+    }
+    if (!res.ok) throw await parseError(res);
+    const data = await res.json();
+    return {
+      entries: Array.isArray(data.entries) ? data.entries : [],
+      total: typeof data.total === "number" ? data.total : 0,
+      scannedTypes: typeof data.scannedTypes === "number" ? data.scannedTypes : 0,
+      scannedItems: typeof data.scannedItems === "number" ? data.scannedItems : 0,
+      stats: data.stats && typeof data.stats === "object" ? data.stats : {}
     };
   }
   /**
@@ -932,9 +1068,12 @@ var MetadataClient = class _MetadataClient {
   /**
    * Reset a metadata customization overlay back to the artifact default.
    * Idempotent: returns the result even when no overlay row existed.
+   * Pass `state: 'draft'` to discard the pending draft only (keeps the
+   * published overlay intact) — useful for a Studio "Discard draft" button.
    */
   async reset(type, name, options = {}) {
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}`;
+    const qs = options.state === "draft" ? "?state=draft" : "";
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}${qs}`;
     const headers = { ...this.headers };
     if (options.ifMatch) headers["If-Match"] = options.ifMatch;
     if (options.actor) headers["X-Actor"] = options.actor;
@@ -942,6 +1081,75 @@ var MetadataClient = class _MetadataClient {
     if (!res.ok) throw await parseError(res);
     return await res.json();
   }
+  /**
+   * Promote the pending draft of an item to the active overlay
+   * (POST `/meta/:type/:name/publish`). Returns
+   * `{ success, version, seq, message }`. Throws a `404 no_draft` if
+   * nothing is pending and `409 metadata_conflict` if the published
+   * overlay moved while the draft was sitting.
+   */
+  async publish(type, name, options = {}) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/publish`;
+    const headers = {
+      ...this.headers,
+      "Content-Type": "application/json"
+    };
+    if (options.actor) headers["X-Actor"] = options.actor;
+    const res = await this.fetchImpl(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(options.message ? { message: options.message } : {})
+    });
+    if (!res.ok) throw await parseError(res);
+    return await res.json();
+  }
+  /**
+   * Restore an item to a previous version (POST `/meta/:type/:name/rollback`).
+   * The server reads the history row at `toVersion`, writes its body back
+   * as the active overlay with `operation_type='revert'`. Returns
+   * `{ success, version, seq, restoredFromVersion, message }`. Throws
+   * `404 version_not_found` for unknown versions and `409 version_not_restorable`
+   * when the target version is a delete tombstone.
+   */
+  async rollback(type, name, toVersion, options = {}) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/rollback`;
+    const headers = {
+      ...this.headers,
+      "Content-Type": "application/json"
+    };
+    if (options.actor) headers["X-Actor"] = options.actor;
+    const res = await this.fetchImpl(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        toVersion,
+        ...options.message ? { message: options.message } : {}
+      })
+    });
+    if (!res.ok) throw await parseError(res);
+    return await res.json();
+  }
+  /**
+   * Compute a structured top-level key diff between two history versions
+   * (GET `/meta/:type/:name/diff?from=&to=`). Returns
+   * `{ added, removed, changed }` where each entry carries a `path` and
+   * the relevant value(s). Useful for "what changed in this draft?" and
+   * pre-rollback previews.
+   */
+  async diff(type, name, fromVersion, toVersion) {
+    const params = new URLSearchParams();
+    if (fromVersion !== void 0) params.set("from", String(fromVersion));
+    if (toVersion !== void 0) params.set("to", String(toVersion));
+    const qs = params.toString();
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/diff${qs ? `?${qs}` : ""}`;
+    const res = await this.fetchImpl(url, {
+      method: "GET",
+      headers: this.headers,
+      cache: "no-store"
+    });
+    if (!res.ok) throw await parseError(res);
+    return await res.json();
+  }
   /** Fetch the durable history (change log) for one metadata item. */
   async history(type, name, options = {}) {
     const params = new URLSearchParams();
@@ -953,6 +1161,22 @@ var MetadataClient = class _MetadataClient {
     if (!res.ok) throw await parseError(res);
     return await res.json();
   }
+  /**
+   * Fetch the protection-audit trail for one metadata item
+   * (ADR-0010 §3.6 / Phase 4.1). Shows every save/publish/rollback/
+   * delete/reset attempt — allowed, denied, or forced — so the
+   * Studio "审计日志 / Audit log" tab can render who tried what
+   * and whether a lock blocked it.
+   */
+  async audit(type, name, options = {}) {
+    const params = new URLSearchParams();
+    if (options.limit !== void 0) params.set("limit", String(options.limit));
+    const qs = params.toString();
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/audit${qs ? `?${qs}` : ""}`;
+    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
+    if (!res.ok) throw await parseError(res);
+    return await res.json();
+  }
 };
 
 // src/security.ts
@@ -1437,7 +1661,7 @@ var ObjectStackAdapter = class {
     if (existing) return existing;
     const promise = (async () => {
       await this.connect();
-      if (params?.$expand && params.$expand.length > 0) {
+      if (params?.$expand && params.$expand.length > 0 || params?.$search != null && String(params.$search).trim() !== "") {
         const result = await this.rawFindWithPopulate(resource, params);
         return this.normalizeQueryResult(result, params);
       }
@@ -1635,6 +1859,34 @@ var ObjectStackAdapter = class {
    * @param data - Array of records to process
    * @returns Promise resolving to array of results
    */
+  /**
+   * Cross-object transactional batch (ObjectStack #1604). 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).
+   */
+  async batchTransaction(operations) {
+    const url = `${this.baseUrl}/api/v1/batch`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...this.getAuthHeaders() },
+      // Send the session cookie too: in the browser console auth is cookie-based
+      // (no bearer `token`), so without `credentials: 'include'` this raw fetch
+      // is unauthenticated — every master-detail batch save would 401. Bearer
+      // (server-to-server) and cookie (console) auth now both work.
+      credentials: "include",
+      body: JSON.stringify({ operations })
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ message: response.statusText }));
+      throw new ObjectStackError(
+        error.error || error.message || `Batch failed with status ${response.status}`,
+        "BATCH_ERROR",
+        response.status
+      );
+    }
+    return response.json();
+  }
   async bulk(resource, operation, data) {
     await this.connect();
     if (!data || data.length === 0) {
@@ -1772,13 +2024,14 @@ var ObjectStackAdapter = class {
     const resultObj = result;
     const records = resultObj.records || resultObj.value || [];
     const total = resultObj.total ?? resultObj.count ?? records.length;
+    const hasMore = typeof resultObj.hasMore === "boolean" ? resultObj.hasMore : params?.$top ? records.length === params.$top : false;
     return {
       data: records,
       total,
       // Calculate page number safely
       page: params?.$skip && params.$top ? Math.floor(params.$skip / params.$top) + 1 : 1,
       pageSize: params?.$top,
-      hasMore: params?.$top ? records.length === params.$top : false
+      hasMore
     };
   }
   /**
@@ -1798,6 +2051,12 @@ var ObjectStackAdapter = class {
     if (params.$skip !== void 0) {
       queryParams.set("skip", String(params.$skip));
     }
+    if (params.$search != null && String(params.$search).trim() !== "") {
+      queryParams.set("search", String(params.$search).trim());
+    }
+    if (params.$searchFields && params.$searchFields.length > 0) {
+      queryParams.set("searchFields", params.$searchFields.join(","));
+    }
     if (params.$select && params.$select.length > 0) {
       const selectFields = params.$select.includes("id") ? params.$select : ["id", ...params.$select];
       queryParams.set("select", selectFields.join(","));
@@ -1898,6 +2157,12 @@ var ObjectStackAdapter = class {
     if (params.$top !== void 0) {
       options.top = params.$top;
     }
+    if (params.$search != null && String(params.$search).trim() !== "") {
+      options.search = String(params.$search).trim();
+    }
+    if (params.$searchFields && params.$searchFields.length > 0) {
+      options.searchFields = params.$searchFields;
+    }
     return options;
   }
   /**
@@ -1910,13 +2175,10 @@ var ObjectStackAdapter = class {
   async getObjectSchema(objectName) {
     await this.connect();
     try {
-      const schema = await this.metadataCache.get(objectName, async () => {
-        const result = await this.client.meta.getItem("object", objectName);
-        if (result && result.item) {
-          return result.item;
-        }
-        return result;
-      });
+      const schema = await this.metadataCache.get(
+        objectName,
+        () => this.fetchObjectSchemaFresh(objectName)
+      );
       return schema;
     } catch (error) {
       const errorObj = error;
@@ -1929,6 +2191,48 @@ var ObjectStackAdapter = class {
       throw createErrorFromResponse(errorObj, `getObjectSchema(${objectName})`);
     }
   }
+  /**
+   * Fetch a single object's schema while always revalidating the browser cache.
+   *
+   * The server serves `GET /api/v1/meta/object/:name` with
+   * `Cache-Control: public, max-age=3600`, so the default `fetch` the SDK uses
+   * keeps returning the same response from the browser HTTP cache for up to an
+   * hour without contacting the origin. Because the create/edit form reads the
+   * object schema through {@link getObjectSchema}, a field added + published in
+   * the same session never appears in the form even though it is live (the LIST
+   * endpoint, `/meta/object`, is uncached — which is why list views update).
+   *
+   * Issuing the read with `cache: 'no-cache'` forces a conditional revalidation
+   * (`If-None-Match`): a changed ETag returns the fresh schema, an unchanged one
+   * still gets a cheap `304`. We go through `fetchImpl` (the adapter's
+   * authenticated fetch) rather than `client.meta.getItem` because the SDK does
+   * not expose the request cache mode.
+   */
+  async fetchObjectSchemaFresh(objectName) {
+    const baseUrl = (this.baseUrl || "").replace(/\/$/, "");
+    const hasApiVersionSuffix = /\/api\/v\d+$/i.test(baseUrl);
+    const metaPath = hasApiVersionSuffix ? "/meta" : "/api/v1/meta";
+    const url = `${baseUrl}${metaPath}/object/${encodeURIComponent(objectName)}`;
+    const headers = { "Content-Type": "application/json" };
+    if (this.token) {
+      headers["Authorization"] = `Bearer ${this.token}`;
+    }
+    const res = await this.fetchImpl(url, {
+      method: "GET",
+      headers,
+      // Revalidate instead of serving the stale `max-age` body (see doc above).
+      cache: "no-cache"
+    });
+    if (!res.ok) {
+      const errBody = await res.json().catch(() => ({ message: res.statusText }));
+      const err = new Error(errBody?.error?.message || errBody?.message || res.statusText);
+      err.status = res.status;
+      throw err;
+    }
+    const body = await res.json();
+    const data = body && typeof body === "object" && "success" in body && "data" in body ? body.data : body;
+    return data && typeof data === "object" && "item" in data ? data.item : data;
+  }
   /**
    * Get access to the underlying ObjectStack client for advanced operations.
    */
@@ -2004,7 +2308,7 @@ var ObjectStackAdapter = class {
     try {
       const cacheKey = `view:${objectName}:${viewId}`;
       return await this.metadataCache.get(cacheKey, async () => {
-        const result = await this.client.meta.getItem(objectName, viewId);
+        const result = await this.client.meta.getItem("view", viewId);
         if (result && result.item) return result.item;
         return result ?? null;
       });
@@ -2063,12 +2367,26 @@ var ObjectStackAdapter = class {
     try {
       const result = await this.client.meta.getItems("view");
       const items = Array.isArray(result?.items) ? result.items : Array.isArray(result) ? result : [];
+      const FORM_FAMILY = /* @__PURE__ */ new Set(["form", "detail"]);
       return items.filter((v) => {
         if (!v) return false;
         const spec = v.list ?? v;
         const obj = spec?.data?.object ?? spec?.object ?? spec?.objectName;
-        return obj === objectName;
-      }).map((v) => v.list ?? v);
+        if (obj !== objectName) return false;
+        const viewKind = v.viewKind ?? spec?.viewKind;
+        return !(viewKind && FORM_FAMILY.has(viewKind));
+      }).map((v) => {
+        const spec = v.list ?? v;
+        if (spec && spec.config && typeof spec.config === "object") {
+          return {
+            ...spec.config,
+            name: spec.name ?? spec.config.name,
+            label: spec.label ?? spec.config.label,
+            isDefault: !!spec.isDefault
+          };
+        }
+        return spec;
+      });
     } catch (err) {
       console.warn("[OBJECTSTACKDataSource] listViews failed:", err);
       return [];
@@ -2285,6 +2603,56 @@ var ObjectStackAdapter = class {
       return this.aggregateClientSide(records, params);
     }
   }
+  /**
+   * Run a semantic-layer `dataset` (ADR-0021) and return chart-ready rows.
+   *
+   * Posts to `POST /api/v1/analytics/dataset/query` (see `@objectstack/rest`
+   * `registerAnalyticsEndpoints`). Accepts either a saved dataset name or an
+   * inline draft definition — the inline form is what the Studio dataset
+   * editor sends to preview an unsaved draft. The adapter's bearer token is
+   * forwarded so tenant/RLS scoping (ADR-0021 D-C) is enforced server-side.
+   *
+   * Unlike {@link aggregate}, this does NOT fall back to client-side
+   * aggregation: cross-object joins can only run on the server, so a failure
+   * is surfaced to the caller (the preview panel shows the error) rather than
+   * silently returning wrong numbers.
+   *
+   * @param dataset - An inline dataset definition (draft) OR a saved dataset name.
+   * @param selection - Dimension/measure names to project + runtime directives.
+   */
+  async queryDataset(dataset, selection) {
+    await this.connect();
+    const base = (this.baseUrl || "").replace(/\/$/, "");
+    const url = `${base}/api/v1/analytics/dataset/query`;
+    const previewDrafts = typeof window !== "undefined" && new URLSearchParams(window.location.search).get("preview") === "draft";
+    const requestBody = typeof dataset === "string" ? { datasetName: dataset, selection, ...previewDrafts ? { previewDrafts: true } : {} } : { dataset, selection, ...previewDrafts ? { previewDrafts: true } : {} };
+    const res = await this.fetchImpl(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...this.token ? { Authorization: `Bearer ${this.token}` } : {}
+      },
+      body: JSON.stringify(requestBody)
+    });
+    if (!res.ok) {
+      let detail = "";
+      try {
+        const errBody = await res.json();
+        detail = errBody?.message || errBody?.error || JSON.stringify(errBody);
+      } catch {
+      }
+      throw new Error(`Dataset query failed: ${res.status} ${res.statusText}${detail ? ` \u2014 ${detail}` : ""}`);
+    }
+    const payload = await res.json();
+    const data = payload && typeof payload === "object" && "success" in payload && "data" in payload ? payload.data : payload;
+    const rows = Array.isArray(data?.rows) ? data.rows : Array.isArray(data) ? data : [];
+    const fields = Array.isArray(data?.fields) ? data.fields : [];
+    const object = typeof data?.object === "string" ? data.object : void 0;
+    const dimensionFields = data?.dimensionFields && typeof data.dimensionFields === "object" ? data.dimensionFields : void 0;
+    const drillRawRows = Array.isArray(data?.drillRawRows) ? data.drillRawRows : void 0;
+    const totals = Array.isArray(data?.totals) ? data.totals : void 0;
+    return { rows, fields, object, dimensionFields, drillRawRows, totals };
+  }
   /** Client-side aggregation fallback */
   aggregateClientSide(records, params) {
     const { field, function: aggFn, groupBy } = params;