@object-ui/data-objectstack 16.0.0 → 17.1.0

package/dist/index.js

@@ -5,7 +5,32 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 // src/index.ts
 import { ObjectStackClient } from "@objectstack/client";
 
+// ../types/src/index.ts
+import {
+  defineStack,
+  ObjectStackSchema,
+  ObjectStackDefinitionSchema
+} from "@objectstack/spec";
+
+// ../types/src/error-code.ts
+function errorCodeIs(err, code) {
+  const raw = err?.code;
+  if (typeof raw !== "string" || raw.length === 0) return false;
+  return raw.toUpperCase() === code.toUpperCase();
+}
+function errorCodeIsAnyOf(err, codes) {
+  return codes.some((c) => errorCodeIs(err, c));
+}
+
 // ../core/src/utils/filter-converter.ts
+var FilterOperatorError = class extends Error {
+  constructor(message) {
+    super(message);
+    __publicField(this, "code", "INVALID_FILTER");
+    __publicField(this, "httpStatus", 400);
+    this.name = "FilterOperatorError";
+  }
+};
 function convertOperatorToAST(operator) {
   const operatorMap = {
     "$eq": "=",
@@ -35,11 +60,9 @@ function convertFiltersToAST(filter) {
     if (typeof value === "object" && !Array.isArray(value)) {
       for (const [operator, operatorValue] of Object.entries(value)) {
         if (operator === "$regex") {
-          console.warn(
-            `[ObjectUI] Warning: $regex operator is not fully supported. Converting to 'contains' which only supports substring matching, not regex patterns. Field: '${field}', Value: ${JSON.stringify(operatorValue)}. Consider using $contains or $startsWith instead.`
+          throw new FilterOperatorError(
+            `[ObjectUI] The '$regex' filter operator is not supported. It used to be converted to 'contains', which matches a literal substring rather than a pattern \u2014 a different result, not a degraded one. Field: '${field}', Value: ${JSON.stringify(operatorValue)}. Use $contains, $startsWith or $endsWith.`
           );
-          conditions.push([field, "contains", operatorValue]);
-          continue;
         }
         if (operator === "$null") {
           conditions.push([field, operatorValue ? "is_null" : "is_not_null", true]);
@@ -53,7 +76,7 @@ function convertFiltersToAST(filter) {
         if (astOperator) {
           conditions.push([field, astOperator, operatorValue]);
         } else {
-          throw new Error(
+          throw new FilterOperatorError(
             `[ObjectUI] Unknown filter operator '${operator}' for field '${field}'. Supported operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $between, $contains, $notContains, $startsWith, $endsWith, $null, $exists. If you need exact object matching, use the value directly without an operator.`
           );
         }
@@ -71,6 +94,72 @@ function convertFiltersToAST(filter) {
   return ["and", ...conditions];
 }
 
+// ../core/src/adapters/batchTransaction.ts
+function idOf(rec) {
+  if (rec == null) return void 0;
+  return rec.id ?? rec._id ?? rec.recordId;
+}
+function resolveRefs(data, results) {
+  const out = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (value && typeof value === "object" && !Array.isArray(value) && typeof value.$ref === "number") {
+      const refIndex = value.$ref;
+      const id = idOf(results[refIndex]);
+      if (id === void 0) {
+        throw new Error(
+          `batchTransaction: field "${key}" references operation ${refIndex}, which has not produced an id (forward or invalid $ref)`
+        );
+      }
+      out[key] = id;
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+async function emulateBatchTransaction(dataSource, operations) {
+  const results = [];
+  const created = [];
+  try {
+    for (const op of operations) {
+      const action = op.action ?? "create";
+      if (action === "create") {
+        const record = await dataSource.create(
+          op.object,
+          resolveRefs(op.data ?? {}, results)
+        );
+        results.push(record);
+        const id = idOf(record);
+        if (id) created.push({ object: op.object, id });
+      } else if (action === "update") {
+        if (op.id == null) {
+          throw new Error(`batchTransaction: update on "${op.object}" requires an id`);
+        }
+        results.push(
+          await dataSource.update(
+            op.object,
+            op.id,
+            resolveRefs(op.data ?? {}, results)
+          )
+        );
+      } else {
+        if (op.id == null) {
+          throw new Error(`batchTransaction: delete on "${op.object}" requires an id`);
+        }
+        results.push(await dataSource.delete(op.object, op.id));
+      }
+    }
+    return { results };
+  } catch (err) {
+    if (created.length > 0) {
+      await Promise.allSettled(
+        [...created].reverse().map((c) => dataSource.delete(c.object, c.id))
+      );
+    }
+    throw err;
+  }
+}
+
 // ../core/src/utils/reference-keys.ts
 function normalizeFieldReferenceKeys(fieldDef) {
   if (!fieldDef || typeof fieldDef !== "object") return fieldDef;
@@ -271,893 +360,896 @@ var MetadataCache = class {
   }
 };
 
-// src/errors.ts
-var ObjectStackError = class extends Error {
+// src/metadata-client.ts
+var META_PREFIX = "/meta";
+var API_PREFIX = "/api/v1";
+function buildBase(config) {
+  const trimmed = config.baseUrl.replace(/\/+$/, "");
+  const scoped = config.environmentId ? `${API_PREFIX}/environments/${encodeURIComponent(config.environmentId)}${META_PREFIX}` : `${API_PREFIX}${META_PREFIX}`;
+  if (/\/api\/v\d+$/i.test(trimmed)) {
+    const stripped = trimmed.replace(/\/api\/v\d+$/i, "");
+    const scopedNoApi = config.environmentId ? `${API_PREFIX}/environments/${encodeURIComponent(config.environmentId)}${META_PREFIX}` : `${API_PREFIX}${META_PREFIX}`;
+    return `${stripped}${scopedNoApi}`;
+  }
+  return `${trimmed}${scoped}`;
+}
+async function parseError(res) {
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    body = await res.text().catch(() => void 0);
+  }
+  const bodyObj = body && typeof body === "object" ? body : void 0;
+  const errNode = bodyObj?.error;
+  const message = (errNode && typeof errNode === "object" ? errNode.message : errNode) ?? bodyObj?.message ?? `Metadata request failed: ${res.status} ${res.statusText}`;
+  const err = new Error(String(message));
+  err.status = res.status;
+  err.body = body;
+  const details = errNode && typeof errNode === "object" ? errNode.details : void 0;
+  const issues = details?.issues ?? (errNode && typeof errNode === "object" ? errNode.issues : void 0) ?? bodyObj?.issues;
+  if (Array.isArray(issues)) err.issues = issues;
+  const code = details?.code ?? (errNode && typeof errNode === "object" ? errNode.code : void 0) ?? bodyObj?.code;
+  if (code != null) err.code = String(code);
+  return err;
+}
+var MetadataClient = class _MetadataClient {
+  constructor(config) {
+    __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) {
+    return new _MetadataClient({
+      baseUrl: this.base.replace(/\/api\/v\d+(?:\/environments\/[^/]+)?\/meta$/, "").replace(/\/+$/, ""),
+      environmentId,
+      fetch: this.fetchImpl,
+      headers: this.headers,
+      previewDrafts: this.previewDrafts
+    });
+  }
   /**
-   * Create a new ObjectStackError
-   * 
-   * @param message - Human-readable error message
-   * @param code - Unique error code for programmatic handling
-   * @param statusCode - Optional HTTP status code
-   * @param details - Optional additional error details for debugging
+   * 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.
    */
-  constructor(message, code, statusCode, details) {
-    super(message);
-    __publicField(this, "code", code);
-    __publicField(this, "statusCode", statusCode);
-    __publicField(this, "details", details);
-    this.name = "ObjectStackError";
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, this.constructor);
+  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). */
+  async listTypes() {
+    const res = await this.fetchImpl(this.base, { 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;
+    if (data && Array.isArray(data.entries)) return data.entries;
+    if (data && Array.isArray(data.items)) return data.items;
+    if (data && Array.isArray(data.types)) {
+      return data.types.map((t) => ({ type: t }));
+    }
+    return [];
+  }
+  /** List items of a metadata type (e.g. `object`, `field`, `view`). */
+  async list(type, options = {}) {
+    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);
+    const data = await res.json();
+    if (Array.isArray(data)) return data;
+    if (data && Array.isArray(data.items)) {
+      return data.items;
     }
+    return [];
   }
   /**
-   * Convert error to JSON for logging/debugging
+   * 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.
    */
-  toJSON() {
-    return {
-      name: this.name,
-      message: this.message,
-      code: this.code,
-      statusCode: this.statusCode,
-      details: this.details,
-      stack: this.stack
-    };
-  }
-};
-var MetadataNotFoundError = class extends ObjectStackError {
-  constructor(objectName, details) {
-    super(
-      `Metadata not found for object: ${objectName}`,
-      "METADATA_NOT_FOUND",
-      404,
-      { objectName, ...details }
-    );
-    this.name = "MetadataNotFoundError";
+  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 ?? [];
   }
-};
-var BulkOperationError = class extends ObjectStackError {
   /**
-   * Create a new BulkOperationError
-   * 
-   * @param operation - The bulk operation that failed (create, update, delete)
-   * @param successCount - Number of successful operations
-   * @param failureCount - Number of failed operations
-   * @param errors - Array of individual errors
-   * @param details - Additional error details
+   * 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.
    */
-  constructor(operation, successCount, failureCount, errors, details) {
-    super(
-      `Bulk ${operation} operation failed: ${successCount} succeeded, ${failureCount} failed`,
-      "BULK_OPERATION_ERROR",
-      500,
-      {
-        operation,
-        successCount,
-        failureCount,
-        errors,
-        ...details
-      }
-    );
-    __publicField(this, "successCount", successCount);
-    __publicField(this, "failureCount", failureCount);
-    __publicField(this, "errors", errors);
-    this.name = "BulkOperationError";
+  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();
   }
   /**
-   * Get a summary of the bulk operation failure
+   * 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.
    */
-  getSummary() {
-    const total = this.successCount + this.failureCount;
-    const failureRate = total > 0 ? this.failureCount / total : 0;
-    return {
-      operation: this.details?.operation,
-      total,
-      successful: this.successCount,
-      failed: this.failureCount,
-      failureRate,
-      errors: this.errors
-    };
+  async getDraft(type, name, options = {}) {
+    return this.get(type, name, { state: "draft", ...options.packageId ? { packageId: options.packageId } : {} });
   }
-};
-var ConnectionError = class extends ObjectStackError {
-  constructor(message, url, details, statusCode) {
-    super(
-      `Connection error: ${message}`,
-      "CONNECTION_ERROR",
-      statusCode || 503,
-      { url, ...details }
-    );
-    __publicField(this, "url", url);
-    this.name = "ConnectionError";
-  }
-};
-var AuthenticationError = class extends ObjectStackError {
-  constructor(message = "Authentication failed", details, statusCode) {
-    super(
-      message,
-      "AUTHENTICATION_ERROR",
-      statusCode || 401,
-      details
-    );
-    this.name = "AuthenticationError";
-  }
-};
-var ValidationError = class extends ObjectStackError {
   /**
-   * Create a new ValidationError
-   * 
-   * @param message - Human-readable error message
-   * @param field - The field that failed validation (optional)
-   * @param validationErrors - Array of validation error details
-   * @param details - Additional error details
+   * Save (PUT) a metadata item. The framework accepts both the bare
+   * item payload and the `{ item: ... }` / `{ metadata: ... }`
+   * envelopes; we send bare for consistency. Pass `mode: 'draft'` to
+   * stage the change without publishing (Studio's "Save" button).
    */
-  constructor(message, field, validationErrors, details) {
-    super(
-      message,
-      "VALIDATION_ERROR",
-      400,
-      {
-        field,
-        validationErrors,
-        ...details
-      }
-    );
-    __publicField(this, "field", field);
-    __publicField(this, "validationErrors", validationErrors);
-    this.name = "ValidationError";
+  async save(type, name, item, options = {}) {
+    if (!name || !String(name).trim()) {
+      throw new Error(
+        `MetadataClient.save: name must be non-empty (type="${type}"). The PUT /meta/:type/:name route requires a name segment.`
+      );
+    }
+    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,
+      "Content-Type": "application/json"
+    };
+    if (options.ifMatch) headers["If-Match"] = options.ifMatch;
+    if (options.actor) headers["X-Actor"] = options.actor;
+    const res = await this.fetchImpl(url, {
+      method: "PUT",
+      headers,
+      body: JSON.stringify(item)
+    });
+    if (!res.ok) throw await parseError(res);
+    return await res.json();
   }
   /**
-   * Get all validation errors as a formatted list
+   * 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.
    */
-  getValidationErrors() {
-    return this.validationErrors || [];
+  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;
   }
-};
-function createErrorFromResponse(response, context) {
-  const status = response?.status || response?.statusCode || 500;
-  const message = response?.message || response?.statusText || "Unknown error";
-  const details = {
-    context,
-    response: {
-      status,
-      data: response?.data,
-      headers: response?.headers
+  /**
+   * 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, 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 };
     }
-  };
-  switch (status) {
-    case 401:
-      return new AuthenticationError(message, details, 401);
-    case 403:
-      return new AuthenticationError(message, details, 403);
-    case 404:
-      if (context?.includes("metadata") || context?.includes("schema") || context?.includes("getObjectSchema")) {
-        const objectName = extractObjectName(context);
-        return new MetadataNotFoundError(objectName, details);
-      }
-      return new ObjectStackError(message, "NOT_FOUND", 404, details);
-    case 400:
-      return new ValidationError(message, void 0, response?.data?.errors, details);
-    case 503:
-      return new ConnectionError(message, response?.config?.url, details, 503);
-    case 504:
-      return new ConnectionError(message, response?.config?.url, details, 504);
-    default:
-      return new ObjectStackError(message, "UNKNOWN_ERROR", status, details);
-  }
-}
-function extractObjectName(context) {
-  if (!context) return "unknown";
-  const match = context.match(/\(([^)]+)\)/);
-  return match ? match[1] : "unknown";
-}
-function isObjectStackError(error) {
-  return error instanceof ObjectStackError;
-}
-function isErrorType(error, errorClass) {
-  return error instanceof errorClass;
-}
-
-// src/cloud.ts
-var CloudOperations = class {
-  constructor(getClient) {
-    __publicField(this, "getClient", getClient);
+    if (!res.ok) throw await parseError(res);
+    const body = await res.json();
+    const hasEnvelope = body && ("code" in body || "overlay" in body || "effective" in body);
+    if (!hasEnvelope) {
+      return {
+        code: null,
+        overlay: null,
+        overlayScope: null,
+        effective: body
+      };
+    }
+    return {
+      code: body.code ?? null,
+      overlay: body.overlay ?? null,
+      overlayScope: body.overlayScope ?? 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 } : {}
+    };
   }
   /**
-   * Deploy an application to the cloud.
+   * 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 deploy(appId, config) {
-    const client = this.getClient();
-    const result = await client.cloud?.deploy?.(appId, config);
-    return result ?? { deploymentId: `deploy-${Date.now()}`, status: "pending" };
+  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 : {}
+    };
   }
   /**
-   * Get deployment status.
+   * Find every metadata item that references this one (Phase 3a). Useful
+   * for pre-delete impact analysis: "Are any views pointing at this
+   * object before I drop it?".
    */
-  async getDeploymentStatus(deploymentId) {
-    const client = this.getClient();
-    const result = await client.cloud?.getDeployment?.(deploymentId);
-    return result ?? { status: "unknown" };
+  async references(type, name) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/references`;
+    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
+    if (res.status === 404) return [];
+    if (!res.ok) throw await parseError(res);
+    const data = await res.json();
+    return Array.isArray(data) ? data : data?.items ?? [];
   }
   /**
-   * Search marketplace entries.
+   * 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 searchMarketplace(query, category) {
-    const client = this.getClient();
-    const result = await client.cloud?.marketplace?.search?.({ query, category });
-    return result?.items ?? [];
+  async reset(type, name, options = {}) {
+    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;
+    const res = await this.fetchImpl(url, { method: "DELETE", headers });
+    if (!res.ok) throw await parseError(res);
+    return await res.json();
   }
   /**
-   * Install a marketplace plugin.
+   * 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 installPlugin(pluginId) {
-    const client = this.getClient();
-    const result = await client.cloud?.marketplace?.install?.(pluginId);
-    return result ?? { success: false };
-  }
-};
-
-// src/contracts.ts
-function validatePluginContract(contract) {
-  const errors = [];
-  const warnings = [];
-  if (!contract.name || contract.name.trim().length === 0) {
-    errors.push({ field: "name", message: "Plugin name is required", code: "MISSING_NAME" });
-  }
-  if (!contract.version || !/^\d+\.\d+\.\d+/.test(contract.version)) {
-    errors.push({ field: "version", message: "Valid semver version is required", code: "INVALID_VERSION" });
-  }
-  if (!contract.exports || contract.exports.length === 0) {
-    errors.push({ field: "exports", message: "At least one export is required", code: "NO_EXPORTS" });
-  }
-  if (contract.exports) {
-    const validTypes = ["component", "hook", "utility", "provider"];
-    for (const exp of contract.exports) {
-      if (!exp.name) {
-        errors.push({ field: "exports.name", message: "Export name is required", code: "MISSING_EXPORT_NAME" });
-      }
-      if (!validTypes.includes(exp.type)) {
-        errors.push({ field: "exports.type", message: `Invalid export type: ${exp.type}`, code: "INVALID_EXPORT_TYPE" });
-      }
-    }
-  }
-  if (!contract.permissions || contract.permissions.length === 0) {
-    warnings.push("No permissions declared \u2014 plugin will have minimal access");
-  }
-  return { valid: errors.length === 0, errors, warnings };
-}
-function generateContractManifest(contract) {
-  return {
-    $schema: "https://objectui.org/schemas/plugin-contract-v1.json",
-    name: contract.name,
-    version: contract.version,
-    peerDependencies: contract.peerDependencies ?? {},
-    exports: contract.exports.map((exp) => ({
-      name: exp.name,
-      type: exp.type,
-      description: exp.description ?? ""
-    })),
-    permissions: contract.permissions ?? [],
-    api: contract.api ?? {},
-    generatedAt: (/* @__PURE__ */ new Date()).toISOString()
-  };
-}
-
-// src/userState.ts
-var DEFAULT_RESOURCE = "sys_user_preference";
-function createObjectStackUserStateAdapter(options) {
-  const {
-    dataSource,
-    userId,
-    key,
-    resource = DEFAULT_RESOURCE,
-    onError = () => {
-    }
-  } = options;
-  let cachedRowId = null;
-  let saveChain = Promise.resolve();
-  const findExisting = async () => {
-    const params = {
-      $filter: {
-        user_id: userId,
-        key
-      },
-      $top: 1
+  async publish(type, name, options = {}) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/publish`;
+    const headers = {
+      ...this.headers,
+      "Content-Type": "application/json"
     };
-    const result = await dataSource.find(resource, params);
-    const rows = result?.data ?? [];
-    const match = rows.find((r) => {
-      if (!r) return false;
-      const userMismatch = r.user_id !== void 0 && r.user_id !== userId;
-      const keyMismatch = r.key !== void 0 && r.key !== key;
-      return !userMismatch && !keyMismatch;
+    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 } : {})
     });
-    return match ?? null;
-  };
-  const decodeValue = (value) => {
-    if (Array.isArray(value)) return value;
-    if (typeof value === "string") {
-      try {
-        const parsed = JSON.parse(value);
-        return Array.isArray(parsed) ? parsed : [];
-      } catch {
-        return [];
-      }
-    }
-    return [];
-  };
-  const upsert = async (items) => {
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    if (cachedRowId !== null) {
-      try {
-        await dataSource.update(resource, cachedRowId, { value: items, updated_at: now });
-        return;
-      } catch (updateError) {
-        cachedRowId = null;
-        onError("save", updateError);
-      }
-    }
-    const existing = await findExisting();
-    if (existing && existing.id !== void 0 && existing.id !== null) {
-      cachedRowId = existing.id;
-      await dataSource.update(resource, existing.id, { value: items, updated_at: now });
-      return;
-    }
-    try {
-      const created = await dataSource.create(resource, {
-        user_id: userId,
-        key,
-        value: items,
-        updated_at: now
-      });
-      const newId = created?.id;
-      if (newId !== void 0 && newId !== null) cachedRowId = newId;
-    } catch (createError) {
-      const recovered = await findExisting();
-      if (recovered && recovered.id !== void 0 && recovered.id !== null) {
-        cachedRowId = recovered.id;
-        await dataSource.update(resource, recovered.id, { value: items, updated_at: now });
-        return;
-      }
-      throw createError;
-    }
-  };
-  return {
-    async load() {
-      try {
-        const row = await findExisting();
-        if (!row) {
-          cachedRowId = null;
-          return [];
-        }
-        if (row.id !== void 0 && row.id !== null) cachedRowId = row.id;
-        return decodeValue(row.value);
-      } catch (error) {
-        onError("load", error);
-        return [];
-      }
-    },
-    async save(items) {
-      const run = saveChain.then(() => upsert(items)).catch((error) => {
-        onError("save", error);
-      });
-      saveChain = run;
-      return run;
-    }
-  };
-}
-
-// src/integration.ts
-var IntegrationManager = class {
-  constructor() {
-    __publicField(this, "integrations", /* @__PURE__ */ new Map());
+    if (!res.ok) throw await parseError(res);
+    return await res.json();
   }
   /**
-   * Register a new integration.
+   * 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.
    */
-  register(id, config) {
-    this.integrations.set(id, config);
+  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();
   }
   /**
-   * Remove an integration.
+   * 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.
    */
-  unregister(id) {
-    this.integrations.delete(id);
+  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();
   }
-  /**
-   * Get all registered integrations.
-   */
-  getAll() {
-    return new Map(this.integrations);
+  /** Fetch the durable history (change log) for one metadata item. */
+  async history(type, name, options = {}) {
+    const params = new URLSearchParams();
+    if (options.sinceSeq !== void 0) params.set("sinceSeq", String(options.sinceSeq));
+    if (options.limit !== void 0) params.set("limit", String(options.limit));
+    const qs = params.toString();
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/history${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();
   }
   /**
-   * Get integrations that match a specific event.
+   * 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.
    */
-  getForEvent(event) {
-    return Array.from(this.integrations.values()).filter(
-      (integration) => integration.enabled && integration.triggers?.some((t) => t.event === event)
-    );
+  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/errors.ts
+var ObjectStackError = class extends Error {
   /**
-   * Dispatch an event to all matching integrations.
-   * Returns results for each integration.
+   * Create a new ObjectStackError
+   * 
+   * @param message - Human-readable error message
+   * @param code - Unique error code for programmatic handling
+   * @param statusCode - Optional HTTP status code
+   * @param details - Optional additional error details for debugging
    */
-  async dispatch(event, payload) {
-    const matching = this.getForEvent(event);
-    const results = [];
-    for (const [id, integration] of this.integrations) {
-      if (!matching.includes(integration)) continue;
-      try {
-        await this.send(integration, payload);
-        results.push({ id, success: true });
-      } catch (err) {
-        results.push({ id, success: false, error: err.message });
-      }
+  constructor(message, code, statusCode, details) {
+    super(message);
+    __publicField(this, "code", code);
+    __publicField(this, "statusCode", statusCode);
+    __publicField(this, "details", details);
+    this.name = "ObjectStackError";
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
     }
-    return results;
   }
   /**
-   * Send payload to a specific integration.
+   * Convert error to JSON for logging/debugging
    */
-  async send(integration, payload) {
-    switch (integration.provider) {
-      case "webhook": {
-        const cfg = integration.config;
-        const url = cfg.url;
-        try {
-          const parsed = new URL(url);
-          if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-            throw new Error(`Invalid URL protocol: ${parsed.protocol}`);
-          }
-        } catch (e) {
-          if (e instanceof TypeError) {
-            throw new Error(`Invalid webhook URL: ${url}`);
-          }
-          throw e;
-        }
-        await fetch(url, {
-          method: cfg.method,
-          headers: {
-            "Content-Type": "application/json",
-            ...cfg.headers
-          },
-          body: JSON.stringify(payload)
-        });
-        break;
-      }
-      case "slack": {
-        const cfg = integration.config;
-        const url = cfg.webhookUrl;
-        try {
-          const parsed = new URL(url);
-          if (parsed.protocol !== "https:") {
-            throw new Error(`Invalid Slack webhook URL protocol: ${parsed.protocol}`);
-          }
-        } catch (e) {
-          if (e instanceof TypeError) {
-            throw new Error(`Invalid Slack webhook URL: ${url}`);
-          }
-          throw e;
-        }
-        await fetch(url, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({
-            channel: cfg.channel,
-            username: cfg.username,
-            icon_emoji: cfg.iconEmoji,
-            text: JSON.stringify(payload)
-          })
-        });
-        break;
-      }
-      // Email and other providers would require server-side implementation
-      default:
-        break;
-    }
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      statusCode: this.statusCode,
+      details: this.details,
+      stack: this.stack
+    };
   }
 };
-
-// src/metadata-client.ts
-var META_PREFIX = "/meta";
-var API_PREFIX = "/api/v1";
-function buildBase(config) {
-  const trimmed = config.baseUrl.replace(/\/+$/, "");
-  const scoped = config.environmentId ? `${API_PREFIX}/environments/${encodeURIComponent(config.environmentId)}${META_PREFIX}` : `${API_PREFIX}${META_PREFIX}`;
-  if (/\/api\/v\d+$/i.test(trimmed)) {
-    const stripped = trimmed.replace(/\/api\/v\d+$/i, "");
-    const scopedNoApi = config.environmentId ? `${API_PREFIX}/environments/${encodeURIComponent(config.environmentId)}${META_PREFIX}` : `${API_PREFIX}${META_PREFIX}`;
-    return `${stripped}${scopedNoApi}`;
-  }
-  return `${trimmed}${scoped}`;
-}
-async function parseError(res) {
-  let body;
-  try {
-    body = await res.json();
-  } catch {
-    body = await res.text().catch(() => void 0);
-  }
-  const bodyObj = body && typeof body === "object" ? body : void 0;
-  const errNode = bodyObj?.error;
-  const message = (errNode && typeof errNode === "object" ? errNode.message : errNode) ?? bodyObj?.message ?? `Metadata request failed: ${res.status} ${res.statusText}`;
-  const err = new Error(String(message));
-  err.status = res.status;
-  err.body = body;
-  const details = errNode && typeof errNode === "object" ? errNode.details : void 0;
-  const issues = details?.issues ?? (errNode && typeof errNode === "object" ? errNode.issues : void 0) ?? bodyObj?.issues;
-  if (Array.isArray(issues)) err.issues = issues;
-  const code = details?.code ?? (errNode && typeof errNode === "object" ? errNode.code : void 0) ?? bodyObj?.code;
-  if (code != null) err.code = String(code);
-  return err;
-}
-var MetadataClient = class _MetadataClient {
-  constructor(config) {
-    __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;
+var MetadataNotFoundError = class extends ObjectStackError {
+  constructor(objectName, details) {
+    super(
+      `Metadata not found for object: ${objectName}`,
+      "METADATA_NOT_FOUND",
+      404,
+      { objectName, ...details }
+    );
+    this.name = "MetadataNotFoundError";
   }
-  /** Update the client's environment scope at runtime. */
-  withEnvironment(environmentId) {
-    return new _MetadataClient({
-      baseUrl: this.base.replace(/\/api\/v\d+(?:\/environments\/[^/]+)?\/meta$/, "").replace(/\/+$/, ""),
-      environmentId,
-      fetch: this.fetchImpl,
-      headers: this.headers,
-      previewDrafts: this.previewDrafts
-    });
+};
+var BulkOperationError = class extends ObjectStackError {
+  /**
+   * Create a new BulkOperationError
+   * 
+   * @param operation - The bulk operation that failed (create, update, delete)
+   * @param successCount - Number of successful operations
+   * @param failureCount - Number of failed operations
+   * @param errors - Array of individual errors
+   * @param details - Additional error details
+   */
+  constructor(operation, successCount, failureCount, errors, details) {
+    super(
+      `Bulk ${operation} operation failed: ${successCount} succeeded, ${failureCount} failed`,
+      "BULK_OPERATION_ERROR",
+      500,
+      {
+        operation,
+        successCount,
+        failureCount,
+        errors,
+        ...details
+      }
+    );
+    __publicField(this, "successCount", successCount);
+    __publicField(this, "failureCount", failureCount);
+    __publicField(this, "errors", errors);
+    this.name = "BulkOperationError";
   }
   /**
-   * 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.
+   * Get a summary of the bulk operation failure
    */
-  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
-    });
+  getSummary() {
+    const total = this.successCount + this.failureCount;
+    const failureRate = total > 0 ? this.failureCount / total : 0;
+    return {
+      operation: this.details?.operation,
+      total,
+      successful: this.successCount,
+      failed: this.failureCount,
+      failureRate,
+      errors: this.errors
+    };
   }
-  /** List all registered metadata types (returns the registry rows). */
-  async listTypes() {
-    const res = await this.fetchImpl(this.base, { 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;
-    if (data && Array.isArray(data.entries)) return data.entries;
-    if (data && Array.isArray(data.items)) return data.items;
-    if (data && Array.isArray(data.types)) {
-      return data.types.map((t) => ({ type: t }));
-    }
-    return [];
+};
+var ConnectionError = class extends ObjectStackError {
+  constructor(message, url, details, statusCode) {
+    super(
+      `Connection error: ${message}`,
+      "CONNECTION_ERROR",
+      statusCode || 503,
+      { url, ...details }
+    );
+    __publicField(this, "url", url);
+    this.name = "ConnectionError";
   }
-  /** List items of a metadata type (e.g. `object`, `field`, `view`). */
-  async list(type, options = {}) {
-    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);
-    const data = await res.json();
-    if (Array.isArray(data)) return data;
-    if (data && Array.isArray(data.items)) {
-      return data.items;
-    }
-    return [];
+};
+var AuthenticationError = class extends ObjectStackError {
+  constructor(message = "Authentication failed", details, statusCode) {
+    super(
+      message,
+      "AUTHENTICATION_ERROR",
+      statusCode || 401,
+      details
+    );
+    this.name = "AuthenticationError";
   }
+};
+var ValidationError = class extends ObjectStackError {
   /**
-   * 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.
+   * Create a new ValidationError
+   * 
+   * @param message - Human-readable error message
+   * @param field - The field that failed validation (optional)
+   * @param validationErrors - Array of validation error details
+   * @param details - Additional error details
    */
-  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 ?? [];
+  constructor(message, field, validationErrors, details) {
+    super(
+      message,
+      "VALIDATION_ERROR",
+      400,
+      {
+        field,
+        validationErrors,
+        ...details
+      }
+    );
+    __publicField(this, "field", field);
+    __publicField(this, "validationErrors", validationErrors);
+    this.name = "ValidationError";
   }
   /**
-   * Get a single metadata item. Returns the unwrapped item content
-   * (matching the framework REST handler which calls `res.json(item)`).
-   * Returns `null` on 404 to keep the call-site ergonomic.
+   * Get all validation errors as a formatted list
    */
-  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();
+  getValidationErrors() {
+    return this.validationErrors || [];
+  }
+};
+function createErrorFromResponse(response, context) {
+  const status = response?.status || response?.statusCode || 500;
+  const message = response?.message || response?.statusText || "Unknown error";
+  const details = {
+    context,
+    response: {
+      status,
+      data: response?.data,
+      headers: response?.headers
+    }
+  };
+  switch (status) {
+    case 401:
+      return new AuthenticationError(message, details, 401);
+    case 403:
+      return new AuthenticationError(message, details, 403);
+    case 404:
+      if (context?.includes("metadata") || context?.includes("schema") || context?.includes("getObjectSchema")) {
+        const objectName = extractObjectName(context);
+        return new MetadataNotFoundError(objectName, details);
+      }
+      return new ObjectStackError(message, "NOT_FOUND", 404, details);
+    case 400:
+      return new ValidationError(message, void 0, response?.data?.errors, details);
+    case 503:
+      return new ConnectionError(message, response?.config?.url, details, 503);
+    case 504:
+      return new ConnectionError(message, response?.config?.url, details, 504);
+    default:
+      return new ObjectStackError(message, "UNKNOWN_ERROR", status, details);
+  }
+}
+function extractObjectName(context) {
+  if (!context) return "unknown";
+  const match = context.match(/\(([^)]+)\)/);
+  return match ? match[1] : "unknown";
+}
+function isObjectStackError(error) {
+  return error instanceof ObjectStackError;
+}
+function isErrorType(error, errorClass) {
+  return error instanceof errorClass;
+}
+
+// src/cloud.ts
+var CloudOperations = class {
+  constructor(getClient) {
+    __publicField(this, "getClient", getClient);
   }
   /**
-   * 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.
+   * Deploy an application to the cloud.
    */
-  async getDraft(type, name, options = {}) {
-    return this.get(type, name, { state: "draft", ...options.packageId ? { packageId: options.packageId } : {} });
+  async deploy(appId, config) {
+    const client = this.getClient();
+    const result = await client.cloud?.deploy?.(appId, config);
+    return result ?? { deploymentId: `deploy-${Date.now()}`, status: "pending" };
   }
   /**
-   * Save (PUT) a metadata item. The framework accepts both the bare
-   * item payload and the `{ item: ... }` / `{ metadata: ... }`
-   * envelopes; we send bare for consistency. Pass `mode: 'draft'` to
-   * stage the change without publishing (Studio's "Save" button).
+   * Get deployment status.
    */
-  async save(type, name, item, options = {}) {
-    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,
-      "Content-Type": "application/json"
-    };
-    if (options.ifMatch) headers["If-Match"] = options.ifMatch;
-    if (options.actor) headers["X-Actor"] = options.actor;
-    const res = await this.fetchImpl(url, {
-      method: "PUT",
-      headers,
-      body: JSON.stringify(item)
-    });
-    if (!res.ok) throw await parseError(res);
-    return await res.json();
+  async getDeploymentStatus(deploymentId) {
+    const client = this.getClient();
+    const result = await client.cloud?.getDeployment?.(deploymentId);
+    return result ?? { status: "unknown" };
   }
   /**
-   * 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.
+   * Search marketplace entries.
    */
-  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;
+  async searchMarketplace(query, category) {
+    const client = this.getClient();
+    const result = await client.cloud?.marketplace?.search?.({ query, category });
+    return result?.items ?? [];
   }
   /**
-   * 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).
+   * Install a marketplace plugin.
    */
-  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 };
+  async installPlugin(pluginId) {
+    const client = this.getClient();
+    const result = await client.cloud?.marketplace?.install?.(pluginId);
+    return result ?? { success: false };
+  }
+};
+
+// src/contracts.ts
+function validatePluginContract(contract) {
+  const errors = [];
+  const warnings = [];
+  if (!contract.name || contract.name.trim().length === 0) {
+    errors.push({ field: "name", message: "Plugin name is required", code: "MISSING_NAME" });
+  }
+  if (!contract.version || !/^\d+\.\d+\.\d+/.test(contract.version)) {
+    errors.push({ field: "version", message: "Valid semver version is required", code: "INVALID_VERSION" });
+  }
+  if (!contract.exports || contract.exports.length === 0) {
+    errors.push({ field: "exports", message: "At least one export is required", code: "NO_EXPORTS" });
+  }
+  if (contract.exports) {
+    const validTypes = ["component", "hook", "utility", "provider"];
+    for (const exp of contract.exports) {
+      if (!exp.name) {
+        errors.push({ field: "exports.name", message: "Export name is required", code: "MISSING_EXPORT_NAME" });
+      }
+      if (!validTypes.includes(exp.type)) {
+        errors.push({ field: "exports.type", message: `Invalid export type: ${exp.type}`, code: "INVALID_EXPORT_TYPE" });
+      }
     }
-    if (!res.ok) throw await parseError(res);
-    const body = await res.json();
-    const hasEnvelope = body && ("code" in body || "overlay" in body || "effective" in body);
-    if (!hasEnvelope) {
-      return {
-        code: null,
-        overlay: null,
-        overlayScope: null,
-        effective: body
-      };
+  }
+  if (!contract.permissions || contract.permissions.length === 0) {
+    warnings.push("No permissions declared \u2014 plugin will have minimal access");
+  }
+  return { valid: errors.length === 0, errors, warnings };
+}
+function generateContractManifest(contract) {
+  return {
+    $schema: "https://objectui.org/schemas/plugin-contract-v1.json",
+    name: contract.name,
+    version: contract.version,
+    peerDependencies: contract.peerDependencies ?? {},
+    exports: contract.exports.map((exp) => ({
+      name: exp.name,
+      type: exp.type,
+      description: exp.description ?? ""
+    })),
+    permissions: contract.permissions ?? [],
+    api: contract.api ?? {},
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+
+// src/userState.ts
+var DEFAULT_RESOURCE = "sys_user_preference";
+function createObjectStackUserStateAdapter(options) {
+  const {
+    dataSource,
+    userId,
+    key,
+    resource = DEFAULT_RESOURCE,
+    onError = () => {
     }
-    return {
-      code: body.code ?? null,
-      overlay: body.overlay ?? null,
-      overlayScope: body.overlayScope ?? 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 } : {}
+  } = options;
+  let cachedRowId = null;
+  let saveChain = Promise.resolve();
+  const findExisting = async () => {
+    const params = {
+      $filter: {
+        user_id: userId,
+        key
+      },
+      $top: 1
     };
-  }
-  /**
-   * 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: {} };
+    const result = await dataSource.find(resource, params);
+    const rows = result?.data ?? [];
+    const match = rows.find((r) => {
+      if (!r) return false;
+      const userMismatch = r.user_id !== void 0 && r.user_id !== userId;
+      const keyMismatch = r.key !== void 0 && r.key !== key;
+      return !userMismatch && !keyMismatch;
+    });
+    return match ?? null;
+  };
+  const decodeValue = (value) => {
+    if (Array.isArray(value)) return value;
+    if (typeof value === "string") {
+      try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed) ? parsed : [];
+      } catch {
+        return [];
+      }
     }
-    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 : {}
-    };
+    return [];
+  };
+  const upsert = async (items) => {
+    if (cachedRowId !== null) {
+      try {
+        await dataSource.update(resource, cachedRowId, { value: items });
+        return;
+      } catch (updateError) {
+        cachedRowId = null;
+        onError("save", updateError);
+      }
+    }
+    const existing = await findExisting();
+    if (existing && existing.id !== void 0 && existing.id !== null) {
+      cachedRowId = existing.id;
+      await dataSource.update(resource, existing.id, { value: items });
+      return;
+    }
+    try {
+      const created = await dataSource.create(resource, {
+        user_id: userId,
+        key,
+        value: items
+      });
+      const newId = created?.id;
+      if (newId !== void 0 && newId !== null) cachedRowId = newId;
+    } catch (createError) {
+      const recovered = await findExisting();
+      if (recovered && recovered.id !== void 0 && recovered.id !== null) {
+        cachedRowId = recovered.id;
+        await dataSource.update(resource, recovered.id, { value: items });
+        return;
+      }
+      throw createError;
+    }
+  };
+  return {
+    async load() {
+      try {
+        const row = await findExisting();
+        if (!row) {
+          cachedRowId = null;
+          return [];
+        }
+        if (row.id !== void 0 && row.id !== null) cachedRowId = row.id;
+        return decodeValue(row.value);
+      } catch (error) {
+        onError("load", error);
+        return [];
+      }
+    },
+    async save(items) {
+      const run = saveChain.then(() => upsert(items)).catch((error) => {
+        onError("save", error);
+      });
+      saveChain = run;
+      return run;
+    }
+  };
+}
+
+// src/integration.ts
+var IntegrationManager = class {
+  constructor() {
+    __publicField(this, "integrations", /* @__PURE__ */ new Map());
   }
   /**
-   * Find every metadata item that references this one (Phase 3a). Useful
-   * for pre-delete impact analysis: "Are any views pointing at this
-   * object before I drop it?".
+   * Register a new integration.
    */
-  async references(type, name) {
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/references`;
-    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
-    if (res.status === 404) return [];
-    if (!res.ok) throw await parseError(res);
-    const data = await res.json();
-    return Array.isArray(data) ? data : data?.items ?? [];
+  register(id, config) {
+    this.integrations.set(id, config);
   }
   /**
-   * Reset a metadata customization overlay back to the artifact default.
-   * Idempotent: returns the result even when no overlay row existed.
-   * Pass `state: 'draft'` to discard the pending draft only (keeps the
-   * published overlay intact) — useful for a Studio "Discard draft" button.
+   * Remove an integration.
    */
-  async reset(type, name, options = {}) {
-    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;
-    const res = await this.fetchImpl(url, { method: "DELETE", headers });
-    if (!res.ok) throw await parseError(res);
-    return await res.json();
+  unregister(id) {
+    this.integrations.delete(id);
   }
   /**
-   * Promote the pending draft of an item to the active overlay
-   * (POST `/meta/:type/:name/publish`). Returns
-   * `{ success, version, seq, message }`. Throws a `404 no_draft` if
-   * nothing is pending and `409 metadata_conflict` if the published
-   * overlay moved while the draft was sitting.
+   * Get all registered integrations.
    */
-  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();
+  getAll() {
+    return new Map(this.integrations);
   }
   /**
-   * Restore an item to a previous version (POST `/meta/:type/:name/rollback`).
-   * The server reads the history row at `toVersion`, writes its body back
-   * as the active overlay with `operation_type='revert'`. Returns
-   * `{ success, version, seq, restoredFromVersion, message }`. Throws
-   * `404 version_not_found` for unknown versions and `409 version_not_restorable`
-   * when the target version is a delete tombstone.
+   * Get integrations that match a specific event.
    */
-  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();
+  getForEvent(event) {
+    return Array.from(this.integrations.values()).filter(
+      (integration) => integration.enabled && integration.triggers?.some((t) => t.event === event)
+    );
   }
   /**
-   * Compute a structured top-level key diff between two history versions
-   * (GET `/meta/:type/:name/diff?from=&to=`). Returns
-   * `{ added, removed, changed }` where each entry carries a `path` and
-   * the relevant value(s). Useful for "what changed in this draft?" and
-   * pre-rollback previews.
+   * Dispatch an event to all matching integrations.
+   * Returns results for each integration.
    */
-  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();
-    if (options.sinceSeq !== void 0) params.set("sinceSeq", String(options.sinceSeq));
-    if (options.limit !== void 0) params.set("limit", String(options.limit));
-    const qs = params.toString();
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/history${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();
+  async dispatch(event, payload) {
+    const matching = this.getForEvent(event);
+    const results = [];
+    for (const [id, integration] of this.integrations) {
+      if (!matching.includes(integration)) continue;
+      try {
+        await this.send(integration, payload);
+        results.push({ id, success: true });
+      } catch (err) {
+        results.push({ id, success: false, error: err.message });
+      }
+    }
+    return results;
   }
   /**
-   * Fetch the protection-audit trail for one metadata item
-   * (ADR-0010 §3.6 / Phase 4.1). Shows every save/publish/rollback/
-   * delete/reset attempt — allowed, denied, or forced — so the
-   * Studio "审计日志 / Audit log" tab can render who tried what
-   * and whether a lock blocked it.
+   * Send payload to a specific integration.
    */
-  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();
+  async send(integration, payload) {
+    switch (integration.provider) {
+      case "webhook": {
+        const cfg = integration.config;
+        const url = cfg.url;
+        try {
+          const parsed = new URL(url);
+          if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            throw new Error(`Invalid URL protocol: ${parsed.protocol}`);
+          }
+        } catch (e) {
+          if (e instanceof TypeError) {
+            throw new Error(`Invalid webhook URL: ${url}`);
+          }
+          throw e;
+        }
+        await fetch(url, {
+          method: cfg.method,
+          headers: {
+            "Content-Type": "application/json",
+            ...cfg.headers
+          },
+          body: JSON.stringify(payload)
+        });
+        break;
+      }
+      case "slack": {
+        const cfg = integration.config;
+        const url = cfg.webhookUrl;
+        try {
+          const parsed = new URL(url);
+          if (parsed.protocol !== "https:") {
+            throw new Error(`Invalid Slack webhook URL protocol: ${parsed.protocol}`);
+          }
+        } catch (e) {
+          if (e instanceof TypeError) {
+            throw new Error(`Invalid Slack webhook URL: ${url}`);
+          }
+          throw e;
+        }
+        await fetch(url, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            channel: cfg.channel,
+            username: cfg.username,
+            icon_emoji: cfg.iconEmoji,
+            text: JSON.stringify(payload)
+          })
+        });
+        break;
+      }
+      // Email and other providers would require server-side implementation
+      default:
+        break;
+    }
   }
 };
 
@@ -1348,38 +1440,107 @@ var FILTER_OPERATOR_ALIASES = {
   is_null: "isnull",
   isnull: "isnull",
   is_not_null: "isnotnull",
-  isnotnull: "isnotnull"
+  isnotnull: "isnotnull",
+  // Date comparisons. `before`/`after` are CANONICAL members of the spec's
+  // `VIEW_FILTER_OPERATORS` (ui/view.zod.ts), so a stored view legitimately
+  // carries them — but they are absent from `VALID_AST_OPERATORS`
+  // (data/filter.zod.ts), which gates `isFilterAST()`. Without these two
+  // entries they reached the wire unchanged, the server's AST gate rejected
+  // the shape, and driver-sql skipped the filter ENTIRELY — an unfiltered
+  // result set with no error anywhere. objectstack#3948.
+  before: "<",
+  after: ">"
 };
 function normalizeFilterOperator(op) {
   if (typeof op !== "string") return null;
   const lower = op.toLowerCase();
   return FILTER_OPERATOR_ALIASES[lower] ?? FILTER_OPERATOR_ALIASES[op] ?? op;
 }
+var MalformedFilterError = class extends Error {
+  constructor(entry, index) {
+    const shown = JSON.stringify(entry) ?? String(entry);
+    super(
+      `Filter entry ${index} is not a usable filter rule (${shown}). Expected { field, operator, value } with a non-empty field.`
+    );
+    __publicField(this, "code", "INVALID_FILTER");
+    __publicField(this, "httpStatus", 400);
+    __publicField(this, "entry");
+    __publicField(this, "index");
+    this.name = "MalformedFilterError";
+    this.entry = entry;
+    this.index = index;
+  }
+};
+function isMalformedFilterError(error) {
+  if (!error || typeof error !== "object") return false;
+  const e = error;
+  return e.code === "INVALID_FILTER" || e.name === "MalformedFilterError";
+}
 function objectFilterEntryToAST(entry) {
   if (!entry || typeof entry !== "object") return null;
-  const field = entry.field ?? entry.name;
+  const field = entry.field;
   const rawOp = entry.operator ?? entry.op ?? "=";
   const op = normalizeFilterOperator(rawOp);
   if (!field || !op) return null;
   return [String(field), op, entry.value];
 }
+function isObjectFilterEntryForm(filter) {
+  const first = filter[0];
+  return filter.length > 0 && typeof first === "object" && first !== null && !Array.isArray(first) && first.field !== void 0;
+}
+function objectFilterEntriesToAST(entries) {
+  const nodes = entries.map((entry, i) => {
+    if (Array.isArray(entry)) return translateFilterChild(entry);
+    const tuple = objectFilterEntryToAST(entry);
+    if (!tuple) throw new MalformedFilterError(entry, i);
+    return tuple;
+  });
+  return nodes.length === 1 ? nodes[0] : ["and", ...nodes];
+}
+var LOGICAL_AST_HEADS = /* @__PURE__ */ new Set(["and", "or"]);
+function translateFilterArray(filter) {
+  if (isObjectFilterEntryForm(filter)) return objectFilterEntriesToAST(filter);
+  const head = filter[0];
+  if (typeof head === "string" && LOGICAL_AST_HEADS.has(head.toLowerCase())) {
+    return [head, ...filter.slice(1).map(translateFilterChild)];
+  }
+  if (filter.every((child) => Array.isArray(child))) return filter.map(translateFilterChild);
+  return filter;
+}
+function translateFilterChild(child) {
+  if (Array.isArray(child)) return child.length > 0 ? translateFilterArray(child) : child;
+  if (child && typeof child === "object" && child.field !== void 0) {
+    const tuple = objectFilterEntryToAST(child);
+    if (tuple) return tuple;
+  }
+  return child;
+}
 function translateFilterToAST(filter) {
   if (filter === void 0 || filter === null) return void 0;
   if (Array.isArray(filter)) {
     if (filter.length === 0) return void 0;
-    const first = filter[0];
-    const isObjectForm = filter.length > 0 && typeof first === "object" && first !== null && !Array.isArray(first) && first.field !== void 0;
-    if (isObjectForm) {
-      const tuples = filter.map((entry) => objectFilterEntryToAST(entry)).filter((t) => t !== null);
-      if (tuples.length === 0) return void 0;
-      if (tuples.length === 1) return tuples[0];
-      return ["and", ...tuples];
-    }
-    return filter;
+    return translateFilterArray(filter);
   }
   if (typeof filter === "object") {
     if (Object.keys(filter).length === 0) return void 0;
-    return filter;
+    return convertFiltersToAST(filter);
+  }
+  return void 0;
+}
+function serializeOrderBy(orderby) {
+  if (orderby === void 0 || orderby === null) return void 0;
+  if (typeof orderby === "string") {
+    const trimmed = orderby.trim();
+    return trimmed.length > 0 ? trimmed : void 0;
+  }
+  const shorthand = (field, order) => String(order).toLowerCase() === "desc" ? `-${field}` : field;
+  if (Array.isArray(orderby)) {
+    const parts = orderby.map((item) => typeof item === "string" ? item.trim() : shorthand(item.field, item.order)).filter((s) => s.length > 0);
+    return parts.length > 0 ? parts.join(",") : void 0;
+  }
+  if (typeof orderby === "object") {
+    const parts = Object.entries(orderby).map(([field, order]) => shorthand(field, order));
+    return parts.length > 0 ? parts.join(",") : void 0;
   }
   return void 0;
 }
@@ -1398,6 +1559,16 @@ async function getSharedDiscovery(baseUrl, fetcher) {
 function clearSharedDiscoveryCache() {
   discoveryCache.clear();
 }
+function readTransactionalBatchCapability(discovery) {
+  const caps = discovery?.capabilities;
+  if (!caps || typeof caps !== "object") return void 0;
+  const value = caps.transactionalBatch;
+  if (typeof value === "boolean") return value;
+  if (value && typeof value === "object" && typeof value.enabled === "boolean") {
+    return value.enabled;
+  }
+  return void 0;
+}
 function is404Error(error) {
   if (!error || typeof error !== "object") return false;
   const err = error;
@@ -1405,7 +1576,46 @@ function is404Error(error) {
     return true;
   }
   const code = typeof err.code === "string" ? err.code : "";
-  return code === "object_not_found" || code === "record_not_found";
+  return errorCodeIsAnyOf({ code }, ["OBJECT_NOT_FOUND", "RECORD_NOT_FOUND"]);
+}
+var AnalyticsNotInstalledError = class extends Error {
+  constructor(surface, detail) {
+    super(
+      `Analytics capability is not installed on this deployment \u2014 ${surface} is unavailable. Install @objectstack/service-analytics and mount AnalyticsServicePlugin to enable it.` + (detail ? ` (server said: ${detail})` : "")
+    );
+    __publicField(this, "code", "ANALYTICS_NOT_INSTALLED");
+    /** The surface that was unavailable, for the message a host renders. */
+    __publicField(this, "surface");
+    this.name = "AnalyticsNotInstalledError";
+    this.surface = surface;
+  }
+};
+function isAnalyticsNotInstalledError(error) {
+  if (!error || typeof error !== "object") return false;
+  return error.code === "ANALYTICS_NOT_INSTALLED";
+}
+var AnalyticsQueryRejectedError = class extends Error {
+  constructor(detail, serverCode) {
+    super(
+      `Analytics rejected the query: ${detail ?? "the request body does not match the AnalyticsQuery contract"}`
+    );
+    __publicField(this, "code", "ANALYTICS_QUERY_REJECTED");
+    /** The server's own error code (e.g. `VALIDATION_FAILED`), when it sent one. */
+    __publicField(this, "serverCode");
+    this.name = "AnalyticsQueryRejectedError";
+    this.serverCode = serverCode;
+  }
+};
+function classifyAnalyticsFailure(error) {
+  const err = error ?? {};
+  const code = typeof err.code === "string" ? err.code : void 0;
+  const message = typeof err.message === "string" ? err.message : void 0;
+  const status = typeof err.httpStatus === "number" ? err.httpStatus : typeof err.status === "number" ? err.status : typeof err.statusCode === "number" ? err.statusCode : void 0;
+  if (code === "VALIDATION_FAILED" || status === 400) return { kind: "rejected", code, message };
+  if (status === 404 || status === 501 || code === "NOT_IMPLEMENTED" || code === "ROUTE_NOT_FOUND") {
+    return { kind: "not-installed", code, message };
+  }
+  return { kind: "unknown", code, message };
 }
 var ConcurrentUpdateError = class extends Error {
   constructor(opts) {
@@ -1427,9 +1637,25 @@ function isConcurrentUpdateError(error) {
 function normaliseClientError(error) {
   if (!error || typeof error !== "object") return error;
   const e = error;
+  const details = e.details ?? {};
+  if (e.code === "VALIDATION_FAILED" || e.name === "ValidationError") {
+    const rawFields = Array.isArray(details.fields) ? details.fields : Array.isArray(e.fields) ? e.fields : [];
+    const validationErrors = rawFields.map((f) => {
+      const rec = f ?? {};
+      const field = typeof rec.field === "string" ? rec.field : void 0;
+      if (!field) return null;
+      const message = typeof rec.message === "string" && rec.message.trim() ? rec.message : typeof rec.code === "string" ? rec.code : "";
+      return { field, message };
+    }).filter((x) => x !== null);
+    return new ValidationError(
+      typeof e.message === "string" ? e.message : "Validation failed",
+      validationErrors[0]?.field,
+      validationErrors,
+      { fields: rawFields }
+    );
+  }
   if (e.code !== "CONCURRENT_UPDATE" && e.httpStatus !== 409) return error;
   if (e.code !== "CONCURRENT_UPDATE") return error;
-  const details = e.details ?? {};
   return new ConcurrentUpdateError({
     currentVersion: typeof details.currentVersion === "string" ? details.currentVersion : null,
     currentRecord: details.currentRecord ?? null,
@@ -1443,7 +1669,7 @@ function createQuietHttpLogger() {
     const errBody = meta.error;
     if (errBody && typeof errBody === "object") {
       const code = errBody.code;
-      if (code === "object_not_found" || code === "record_not_found") return true;
+      if (errorCodeIsAnyOf({ code }, ["OBJECT_NOT_FOUND", "RECORD_NOT_FOUND"])) return true;
     }
     return false;
   };
@@ -1487,6 +1713,8 @@ var ObjectStackAdapter = class {
     __publicField(this, "reconnectAttempts", 0);
     __publicField(this, "baseUrl");
     __publicField(this, "token");
+    /** One "analytics capability is missing" console line per adapter, not per widget. */
+    __publicField(this, "analyticsCapabilityWarned", false);
     __publicField(this, "fetchImpl");
     // In-flight find() requests keyed by resource + serialized params.
     // Coalesces concurrent identical reads (e.g. React StrictMode double-mount,
@@ -1498,11 +1726,30 @@ var ObjectStackAdapter = class {
     // so optional collections like sys_presence don't hammer the server with
     // failing requests on every record open / panel render.
     __publicField(this, "missingResources", /* @__PURE__ */ new Set());
+    // Set once the server has told us it can't do a cross-object transactional
+    // batch (the client SDK's data.batchTransaction threw HTTP 404/405/501). After
+    // that, batchTransaction skips the SDK call and serves every call via the
+    // client-side emulation — the non-atomic fallback lives HERE, isolated to the
+    // one adapter that has to cope with a backend lacking server atomicity (#2679).
+    __publicField(this, "batchUnsupported", false);
+    // The server's declared cross-object atomic-batch capability, read from
+    // discovery at connect() (framework #3298 / objectui #2693). `true` → the
+    // backend GUARANTEES an atomic `/batch`, so batchTransaction trusts it and
+    // never degrades to the non-atomic emulation (any failure surfaces as a real
+    // error). `false` or `undefined` (capability absent → backend predates #3298)
+    // → keep the legacy runtime-probe + emulation fallback so a save is still
+    // possible; dropping it there would turn "saves, less safe" into "no save
+    // path" on older backends (#2679 compatibility constraint).
+    __publicField(this, "atomicBatchCapability");
     // Subscribers registered via onMutation(). Emitted after each successful
     // create/update/delete so data-bound views (ListView, ObjectView, kanban,
     // calendar) auto-refresh — the interface ListView relies on to reflect
     // inline-edit "Save All" writes without a manual reload.
     __publicField(this, "mutationListeners", /* @__PURE__ */ new Set());
+    // Subscribers registered via onWriteWarning(). Emitted after a create/update
+    // whose response carried `droppedFields` (framework #3431/#3455) so the app
+    // shell can surface a toast instead of the strip passing silently.
+    __publicField(this, "writeWarningListeners", /* @__PURE__ */ new Set());
     this.client = new ObjectStackClient({ ...config, logger: createQuietHttpLogger() });
     this.metadataCache = new MetadataCache(config.cache);
     this.autoReconnect = config.autoReconnect ?? true;
@@ -1536,6 +1783,7 @@ var ObjectStackAdapter = class {
           return body && typeof body.success === "boolean" && "data" in body ? body.data : body;
         });
         this.client.discoveryInfo = data;
+        this.atomicBatchCapability = readTransactionalBatchCapability(data);
         this.connected = true;
         this.reconnectAttempts = 0;
         this.setConnectionState("connected");
@@ -1673,6 +1921,77 @@ var ObjectStackAdapter = class {
     promise.then(cleanup, cleanup);
     return promise;
   }
+  /**
+   * Full-text search across every searchable object in a single round-trip.
+   *
+   * Hits `GET /api/v1/search?q=`, the platform's global search endpoint served
+   * by the registered search service (the pinyin full-text plugin) and backed
+   * by `metadata-protocol`'s `searchAll`. Unlike `find(resource, { $search })`
+   * — 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).
+   *
+   * Returns `{ query, hits }`. A backend without the search plugin installed
+   * answers `404`; we treat that as "no global search here" and return an empty
+   * hit set so callers can fall back to a per-object fanout rather than surface
+   * an error.
+   */
+  async searchAll(query, options) {
+    const trimmed = (query ?? "").trim();
+    if (trimmed === "") return { query: "", hits: [] };
+    await this.connect();
+    const queryParams = new URLSearchParams();
+    queryParams.set("q", trimmed);
+    if (options?.limit != null && options.limit > 0) {
+      queryParams.set("limit", String(options.limit));
+    }
+    if (options?.objects && options.objects.length > 0) {
+      queryParams.set("objects", options.objects.join(","));
+    }
+    const baseUrl = (this.baseUrl || "").replace(/\/$/, "");
+    const hasApiVersionSuffix = /\/api\/v\d+$/i.test(baseUrl);
+    const searchPath = hasApiVersionSuffix ? "/search" : "/api/v1/search";
+    const url = `${baseUrl}${searchPath}?${queryParams.toString()}`;
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.token) {
+      headers["Authorization"] = `Bearer ${this.token}`;
+    }
+    const res = await this.fetchImpl(url, { method: "GET", headers });
+    if (!res.ok) {
+      if (res.status === 404) return { query: trimmed, hits: [] };
+      const errorBody = await res.json().catch(() => ({ message: res.statusText }));
+      const err = new Error(
+        errorBody?.error?.message || errorBody?.message || res.statusText
+      );
+      err.status = res.status;
+      throw err;
+    }
+    const body = await res.json();
+    const payload = body && typeof body === "object" && typeof body.success === "boolean" && "data" in body ? body.data : body;
+    const rawHits = Array.isArray(payload?.hits) ? payload.hits : Array.isArray(payload) ? payload : [];
+    const hits = [];
+    for (const entry of rawHits) {
+      if (!entry || typeof entry !== "object") continue;
+      const h = entry;
+      const object = h.object ?? h.objectName ?? h.object_name;
+      const id = h.id ?? h.record?.id ?? h.record?._id;
+      if (typeof object !== "string" || id == null) continue;
+      hits.push({
+        object,
+        id: String(id),
+        title: typeof h.title === "string" ? h.title : void 0,
+        snippet: typeof h.snippet === "string" ? h.snippet : void 0,
+        record: h.record && typeof h.record === "object" ? h.record : void 0
+      });
+    }
+    return {
+      query: typeof payload?.query === "string" ? payload.query : trimmed,
+      hits
+    };
+  }
   /**
    * Find a single record by ID.
    */
@@ -1736,11 +2055,84 @@ var ObjectStackAdapter = class {
       this.mutationListeners.delete(callback);
     };
   }
+  /**
+   * Notify all write-warning subscribers. Isolated like {@link emitMutation}: a
+   * throwing listener must not break the write or starve the others.
+   */
+  emitWriteWarning(event) {
+    for (const listener of this.writeWarningListeners) {
+      try {
+        listener(event);
+      } catch (err) {
+        console.warn("ObjectStackAdapter: write-warning listener error", err);
+      }
+    }
+  }
+  /**
+   * Read `droppedFields` off a create/update response (framework #3431/#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.
+   */
+  notifyDroppedFields(operation, resource, result, id) {
+    const dropped = result?.droppedFields;
+    if (!Array.isArray(dropped) || dropped.length === 0) return;
+    const droppedFields = dropped.filter(
+      (e) => !!e && typeof e === "object" && Array.isArray(e.fields) && e.fields.length > 0
+    );
+    if (droppedFields.length === 0) return;
+    this.emitWriteWarning({ operation, resource, ...id !== void 0 ? { id } : {}, droppedFields });
+  }
+  /**
+   * Same, for the cross-object transactional batch (framework #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.
+   *
+   * This is the path that matters most for the warning: `batchTransaction` is
+   * how the console's record form saves a master-detail record, so a
+   * `readonlyWhen`-locked field edited in that form was stripped server-side
+   * while the UI reported a plain success. The operation kind is taken from the
+   * originating op so the toast doesn't call an update a create.
+   */
+  notifyBatchDroppedFields(operations, payload) {
+    const dropped = payload?.droppedFields;
+    if (!Array.isArray(dropped) || dropped.length === 0) return;
+    for (const entry of dropped) {
+      if (!entry || typeof entry !== "object") continue;
+      const e = entry;
+      if (!Array.isArray(e.fields) || e.fields.length === 0) continue;
+      const op = typeof e.index === "number" ? operations[e.index] : void 0;
+      const operation = (op?.action ?? "create") === "create" ? "create" : "update";
+      this.emitWriteWarning({
+        operation,
+        resource: e.object ?? op?.object ?? "",
+        ...op?.id !== void 0 && op?.id !== null ? { id: op.id } : {},
+        droppedFields: [{ object: e.object, fields: e.fields, reason: e.reason }]
+      });
+    }
+  }
+  /**
+   * Subscribe to write-warning events (a create/update dropped caller-supplied
+   * fields — #3431/#3455). Returns an unsubscribe function. The app shell uses
+   * this to toast the user; the write itself already succeeded.
+   */
+  onWriteWarning(callback) {
+    this.writeWarningListeners.add(callback);
+    return () => {
+      this.writeWarningListeners.delete(callback);
+    };
+  }
   async create(resource, data) {
     await this.connect();
-    const result = await this.client.data.create(resource, data);
-    this.emitMutation({ type: "create", resource, record: { ...result.record } });
-    return result.record;
+    try {
+      const result = await this.client.data.create(resource, data);
+      this.emitMutation({ type: "create", resource, record: { ...result.record } });
+      this.notifyDroppedFields("create", resource, result, result.record?.id);
+      return result.record;
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
   }
   /**
    * Update an existing record.
@@ -1763,6 +2155,7 @@ var ObjectStackAdapter = class {
         opts?.ifMatch ? { ifMatch: opts.ifMatch } : void 0
       );
       this.emitMutation({ type: "update", resource, id, record: { ...result.record } });
+      this.notifyDroppedFields("update", resource, result, id);
       return result.record;
     } catch (err) {
       throw normaliseClientError(err);
@@ -1885,33 +2278,85 @@ var ObjectStackAdapter = class {
    * @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).
+   * Cross-object transactional batch (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
+   * 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 /
+   * 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
+   *     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
+   *     still possible. Removing that here would regress older backends from
+   *     "saves, less safe" to "no save path" (#2679 compatibility constraint).
+   *     The non-atomic fallback stays isolated to THIS adapter.
    */
   async batchTransaction(operations) {
-    const url = `${this.baseUrl}/api/v1/batch`;
-    const response = await this.fetchImpl(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
+    await this.connect();
+    const guaranteed = this.atomicBatchCapability === true;
+    if (!guaranteed && this.batchUnsupported) {
+      return emulateBatchTransaction(this, operations);
+    }
+    try {
+      const payload = await this.client.data.batchTransaction(operations);
+      this.emitBatchMutations(operations, payload?.results);
+      this.notifyBatchDroppedFields(operations, payload);
+      return payload;
+    } catch (err) {
+      const status = this.errorStatusOf(err);
+      if (!guaranteed && this.batchStatusUnsupported(status)) {
+        return this.fallbackToEmulation(operations, status);
+      }
+      throw err;
+    }
+  }
+  /** True for statuses that mean "this backend can't do a transactional batch". */
+  batchStatusUnsupported(status) {
+    return status === 404 || status === 405 || status === 501;
+  }
+  /** Best-effort HTTP status extraction from a thrown SDK/client error. */
+  errorStatusOf(err) {
+    if (!err || typeof err !== "object") return void 0;
+    const e = err;
+    const s = e.httpStatus ?? e.status ?? e.statusCode;
+    return typeof s === "number" ? s : void 0;
+  }
+  /** Mark the endpoint unsupported (warn once) and serve via emulation. */
+  fallbackToEmulation(operations, status) {
+    if (!this.batchUnsupported) {
+      this.batchUnsupported = true;
+      console.warn(
+        `ObjectStackAdapter: POST /api/v1/batch unavailable (HTTP ${status ?? "?"}) \u2014 falling back to non-atomic client-side batch emulation. Cross-object saves on this backend are best-effort, not transactional.`
       );
     }
-    const payload = await response.json();
-    const results = Array.isArray(payload?.results) ? payload.results : [];
+    return emulateBatchTransaction(this, operations);
+  }
+  /**
+   * Emit one DataSourceMutationEvent per committed operation so the invalidation bus
+   * (#2269) sees writes that went through /batch exactly like single
+   * create/update/delete calls — master-detail ModalForm saves otherwise leave
+   * related lists and count badges stale (#2582). `results` is index-aligned
+   * with `operations`; creates take id/record from the server echo.
+   *
+   * Only called on the server-committed paths. The emulation branch drives the
+   * adapter's own create/update/delete primitives, which already emit — so it
+   * must NOT be routed through here, or events would double-fire.
+   */
+  emitBatchMutations(operations, rawResults) {
+    const results = Array.isArray(rawResults) ? rawResults : [];
     operations.forEach((op, i) => {
       const action = op.action ?? "create";
       const echo = results[i];
@@ -1923,7 +2368,6 @@ var ObjectStackAdapter = class {
         this.emitMutation({ type: "delete", resource: op.object, id: op.id });
       }
     });
-    return payload;
   }
   async bulk(resource, operation, data) {
     await this.connect();
@@ -2254,20 +2698,8 @@ var ObjectStackAdapter = class {
       const selectFields = params.$select.includes("id") ? params.$select : ["id", ...params.$select];
       queryParams.set("select", selectFields.join(","));
     }
-    if (params.$orderby) {
-      if (Array.isArray(params.$orderby)) {
-        const sortStr = params.$orderby.map((item) => {
-          if (typeof item === "string") return item;
-          const field = item.field;
-          const order = item.order || "asc";
-          return order === "desc" ? `-${field}` : field;
-        }).join(",");
-        queryParams.set("sort", sortStr);
-      } else {
-        const sortStr = Object.entries(params.$orderby).map(([field, order]) => order === "desc" ? `-${field}` : field).join(",");
-        queryParams.set("sort", sortStr);
-      }
-    }
+    const sortStr = serializeOrderBy(params.$orderby);
+    if (sortStr) queryParams.set("sort", sortStr);
     if (params.$filter !== void 0 && params.$filter !== null) {
       const translated = translateFilterToAST(params.$filter);
       if (translated !== void 0) {
@@ -2331,6 +2763,13 @@ var ObjectStackAdapter = class {
         queryParams.set("filter", JSON.stringify(translated));
       }
     }
+    const searchTerm = typeof request.search === "string" ? request.search.trim() : "";
+    if (searchTerm) {
+      queryParams.set("search", searchTerm);
+      if (request.searchFields && request.searchFields.length > 0) {
+        queryParams.set("searchFields", request.searchFields.join(","));
+      }
+    }
     const baseUrl = this.baseUrl.replace(/\/$/, "");
     const hasApiVersionSuffix = /\/api\/v\d+$/i.test(baseUrl);
     const dataPath = hasApiVersionSuffix ? "/data" : "/api/v1/data";
@@ -2359,38 +2798,14 @@ var ObjectStackAdapter = class {
       const isEmpty = Array.isArray(params.$filter) ? params.$filter.length === 0 : typeof params.$filter === "object" && Object.keys(params.$filter).length === 0;
       if (!isEmpty) {
         if (Array.isArray(params.$filter)) {
-          const isObjectForm = params.$filter.length > 0 && typeof params.$filter[0] === "object" && !Array.isArray(params.$filter[0]) && params.$filter[0].field !== void 0;
-          if (isObjectForm) {
-            const tuples = params.$filter.map((entry) => objectFilterEntryToAST(entry)).filter((t) => t !== null);
-            if (tuples.length === 0) {
-            } else if (tuples.length === 1) {
-              options.filters = tuples[0];
-            } else {
-              options.filters = ["and", ...tuples];
-            }
-          } else {
-            options.filters = params.$filter;
-          }
+          options.filters = translateFilterArray(params.$filter);
         } else {
           options.filters = convertFiltersToAST(params.$filter);
         }
       }
     }
-    if (params.$orderby) {
-      if (Array.isArray(params.$orderby)) {
-        options.sort = params.$orderby.map((item) => {
-          if (typeof item === "string") return item;
-          const field = item.field;
-          const order = item.order || "asc";
-          return order === "desc" ? `-${field}` : field;
-        });
-      } else {
-        const sortArray = Object.entries(params.$orderby).map(([field, order]) => {
-          return order === "desc" ? `-${field}` : field;
-        });
-        options.sort = sortArray;
-      }
-    }
+    const sort = serializeOrderBy(params.$orderby);
+    if (sort) options.sort = sort;
     if (params.$skip !== void 0) {
       options.skip = params.$skip;
     }
@@ -2644,22 +3059,18 @@ var ObjectStackAdapter = class {
    */
   async updateViewConfig(objectName, viewId, config) {
     await this.connect();
-    try {
-      const merged = { ...config || {}, object: config?.object || objectName, name: viewId };
-      const result = await this.client.meta.saveItem(
-        "view",
-        viewId,
-        merged
-      );
-      const cacheKey = `view:${objectName}:${viewId}`;
-      this.metadataCache.invalidate?.(cacheKey);
-      this.metadataCache.invalidate?.(`view-overrides:${objectName}`);
-      this.metadataCache.invalidate?.(`views:${objectName}`);
-      if (result && result.item) return result.item;
-      return result ?? void 0;
-    } catch (err) {
-      throw err;
-    }
+    const merged = { ...config || {}, object: config?.object || objectName, name: viewId };
+    const result = await this.client.meta.saveItem(
+      "view",
+      viewId,
+      merged
+    );
+    const cacheKey = `view:${objectName}:${viewId}`;
+    this.metadataCache.invalidate?.(cacheKey);
+    this.metadataCache.invalidate?.(`view-overrides:${objectName}`);
+    this.metadataCache.invalidate?.(`views:${objectName}`);
+    if (result && result.item) return result.item;
+    return result ?? void 0;
   }
   /**
    * List user-created views for a given object via the metadata overlay
@@ -2671,11 +3082,17 @@ var ObjectStackAdapter = class {
    * Filters by `data.object === objectName` (or top-level `object`)
    * client-side because the metadata index is name-only, not field-typed.
    */
-  async listViews(objectName) {
+  async listViews(objectName, options) {
     await this.connect();
     try {
-      const result = await this.client.meta.getItems("view");
-      const items = Array.isArray(result?.items) ? result.items : Array.isArray(result) ? result : [];
+      let items;
+      if (options?.previewDrafts) {
+        const draftItems = await this.metadataClient().withPreviewDrafts(true).list("view");
+        items = Array.isArray(draftItems) ? draftItems : [];
+      } else {
+        const result = await this.client.meta.getItems("view");
+        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;
@@ -2686,21 +3103,36 @@ var ObjectStackAdapter = class {
         return !(viewKind && FORM_FAMILY.has(viewKind));
       }).map((v) => {
         const spec = v.list ?? v;
+        const isDraft = v._draft === true || spec?._draft === true;
         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
+            isDefault: !!spec.isDefault,
+            ...isDraft ? { _draft: true } : {}
           };
         }
-        return spec;
+        return isDraft ? { ...spec, _draft: true } : spec;
       });
     } catch (err) {
       console.warn("[OBJECTSTACKDataSource] listViews failed:", err);
       return [];
     }
   }
+  /**
+   * Build a {@link MetadataClient} bound to this adapter's server + auth. Used
+   * by draft-aware reads (`listViews({ previewDrafts })`) so the `/meta` route,
+   * `?preview=draft` flag, and environment scoping live in the SDK rather than
+   * being hand-assembled at each call site (#2767 P3).
+   */
+  metadataClient() {
+    return new MetadataClient({
+      baseUrl: this.baseUrl,
+      fetch: this.fetchImpl,
+      ...this.token ? { headers: { Authorization: `Bearer ${this.token}` } } : {}
+    });
+  }
   /**
    * List registered import `mapping` artifacts targeting a given object
    * (framework #2611). Reads the `mapping` metadata kind via the overlay API
@@ -2745,14 +3177,10 @@ var ObjectStackAdapter = class {
       object: spec?.object || objectName,
       data: spec?.data || { provider: "object", object: objectName }
     };
-    try {
-      const result = await this.client.meta.saveItem("view", name, fullSpec);
-      this.metadataCache.invalidate?.(`views:${objectName}`);
-      if (result && result.item) return result.item;
-      return fullSpec;
-    } catch (err) {
-      throw err;
-    }
+    const result = await this.client.meta.saveItem("view", name, fullSpec);
+    this.metadataCache.invalidate?.(`views:${objectName}`);
+    if (result && result.item) return result.item;
+    return fullSpec;
   }
   /**
    * Apply a partial update to an existing overlay view. Reads the current
@@ -2775,15 +3203,11 @@ var ObjectStackAdapter = class {
       name: viewName,
       object: current?.object || current?.data?.object || objectName
     };
-    try {
-      const result = await this.client.meta.saveItem("view", viewName, merged);
-      this.metadataCache.invalidate?.(`views:${objectName}`);
-      this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
-      if (result && result.item) return result.item;
-      return merged;
-    } catch (err) {
-      throw err;
-    }
+    const result = await this.client.meta.saveItem("view", viewName, merged);
+    this.metadataCache.invalidate?.(`views:${objectName}`);
+    this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
+    if (result && result.item) return result.item;
+    return merged;
   }
   /**
    * Delete an overlay view (reset to artifact default if one exists, or
@@ -2792,14 +3216,10 @@ var ObjectStackAdapter = class {
    */
   async deleteView(objectName, viewName) {
     await this.connect();
-    try {
-      const result = await this.client.meta.deleteItem("view", viewName);
-      this.metadataCache.invalidate?.(`views:${objectName}`);
-      this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
-      return { deleted: !!(result?.deleted ?? result?.reset ?? true) };
-    } catch (err) {
-      throw err;
-    }
+    const result = await this.client.meta.deleteItem("view", viewName);
+    this.metadataCache.invalidate?.(`views:${objectName}`);
+    this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
+    return { deleted: !!(result?.deleted ?? result?.reset ?? true) };
   }
   /**
    * Get an application definition by name or ID.
@@ -2855,19 +3275,15 @@ var ObjectStackAdapter = class {
    */
   async updateDashboard(dashboardName, schema) {
     await this.connect();
-    try {
-      const result = await this.client.meta.saveItem(
-        "dashboard",
-        dashboardName,
-        schema
-      );
-      this.metadataCache.invalidate?.("dashboards");
-      this.metadataCache.invalidate?.(`dashboard:${dashboardName}`);
-      if (result && result.item) return result.item;
-      return result ?? void 0;
-    } catch (err) {
-      throw err;
-    }
+    const result = await this.client.meta.saveItem(
+      "dashboard",
+      dashboardName,
+      schema
+    );
+    this.metadataCache.invalidate?.("dashboards");
+    this.metadataCache.invalidate?.(`dashboard:${dashboardName}`);
+    if (result && result.item) return result.item;
+    return result ?? void 0;
   }
   /**
    * Perform server-side aggregation via the ObjectStack analytics API.
@@ -2893,6 +3309,7 @@ var ObjectStackAdapter = class {
     }
     try {
       const measureName = params.function === "count" ? "count" : `${params.field}_${params.function}`;
+      const valueKey = this.aggregateValueKey(params);
       const payload = {
         cube: resource,
         measures: [measureName],
@@ -2907,30 +3324,62 @@ var ObjectStackAdapter = class {
       const measureMissing = rawRows.length > 0 && rawRows.every((row) => {
         if (row == null) return true;
         if (measureName in row && row[measureName] != null) return false;
-        if (params.field in row && row[params.field] != null) return false;
+        if (valueKey in row && row[valueKey] != null) return false;
         return true;
       });
       if (measureMissing) {
-        const result = await this.find(resource, params.filter ? { $filter: params.filter } : void 0);
-        const records = result.data || [];
-        if (records.length === 0) return [];
-        return this.aggregateClientSide(records, params);
+        return await this.aggregateViaFind(resource, params);
       }
       return rawRows.map((row) => {
         const mapped = { ...row };
-        if (measureName !== params.field && measureName in mapped) {
-          mapped[params.field] = mapped[measureName];
+        if (measureName !== valueKey && measureName in mapped) {
+          mapped[valueKey] = mapped[measureName];
           delete mapped[measureName];
         }
         return mapped;
       });
-    } catch {
-      const result = await this.find(resource, params.filter ? { $filter: params.filter } : void 0);
-      const records = result.data || [];
-      if (records.length === 0) return [];
-      return this.aggregateClientSide(records, params);
+    } catch (e) {
+      const failure = classifyAnalyticsFailure(e);
+      if (failure.kind === "rejected") {
+        throw new AnalyticsQueryRejectedError(failure.message, failure.code);
+      }
+      if (failure.kind === "not-installed") {
+        this.warnAnalyticsCapabilityOnce(failure.message);
+      }
+      return await this.aggregateViaFind(resource, params);
     }
   }
+  /**
+   * Client-side aggregation over a server-scoped `find()` — the fallback used
+   * whenever the analytics endpoint cannot answer (capability absent, network
+   * failure, or a result whose measure came back missing).
+   *
+   * Forwarding `params.filter` is load-bearing: without it the fallback
+   * aggregates the whole table while the caller believes it applied a filter,
+   * which is the "KPI silently sums everything" failure this adapter has
+   * guarded against since the widget filter was threaded through.
+   */
+  async aggregateViaFind(resource, params) {
+    const result = await this.find(
+      resource,
+      params.filter ? { $filter: params.filter } : void 0
+    );
+    const records = result.data || [];
+    if (records.length === 0) return [];
+    return this.aggregateClientSide(records, params);
+  }
+  /**
+   * Say "the analytics capability isn't installed" ONCE per adapter, not once
+   * per widget: a dashboard fans out one aggregate() per KPI, and N identical
+   * console lines read like N different failures.
+   */
+  warnAnalyticsCapabilityOnce(detail) {
+    if (this.analyticsCapabilityWarned) return;
+    this.analyticsCapabilityWarned = true;
+    console.warn(
+      "[OBJECTSTACKDataSource] analytics capability unavailable \u2014 aggregating client-side from a scoped find(). Numbers stay correct but the semantic layer (cubes, joins, server-side rollups) is off. Install @objectstack/service-analytics to enable it." + (detail ? ` Server said: ${detail}` : "")
+    );
+  }
   /**
    * Run a semantic-layer `dataset` (ADR-0021) and return chart-ready rows.
    *
@@ -2969,6 +3418,9 @@ var ObjectStackAdapter = class {
         detail = errBody?.message || errBody?.error || JSON.stringify(errBody);
       } catch {
       }
+      if (res.status === 501 || res.status === 404) {
+        throw new AnalyticsNotInstalledError("POST /analytics/dataset/query", detail || void 0);
+      }
       throw new Error(`Dataset query failed: ${res.status} ${res.statusText}${detail ? ` \u2014 ${detail}` : ""}`);
     }
     const payload = await res.json();
@@ -2982,8 +3434,18 @@ var ObjectStackAdapter = class {
     return { rows, fields, object, dimensionFields, drillRawRows, totals };
   }
   /** Client-side aggregation fallback */
+  /**
+   * The result column an object-bound `aggregate` projects its value under
+   * (framework#3701, `chartAggregateValueKey` in `@objectstack/spec/ui`): the
+   * raw `field` name — no `sum_`-style decoration, unlike a dataset measure —
+   * or the literal `count` when a count names no field.
+   */
+  aggregateValueKey(params) {
+    return params.field || params.function || "count";
+  }
   aggregateClientSide(records, params) {
     const { field, function: aggFn, groupBy } = params;
+    const valueKey = this.aggregateValueKey(params);
     const groups = {};
     for (const record of records) {
       const key = String(record[groupBy] ?? "Unknown");
@@ -2991,7 +3453,7 @@ var ObjectStackAdapter = class {
       groups[key].push(record);
     }
     return Object.entries(groups).map(([key, group]) => {
-      const values = group.map((r) => Number(r[field]) || 0);
+      const values = field ? group.map((r) => Number(r[field]) || 0) : [];
       let result;
       switch (aggFn) {
         case "count":
@@ -3011,7 +3473,7 @@ var ObjectStackAdapter = class {
           result = values.reduce((a, b) => a + b, 0);
           break;
       }
-      return { [groupBy]: key, [field]: result };
+      return { [groupBy]: key, [valueKey]: result };
     });
   }
   /**
@@ -3213,12 +3675,16 @@ function createObjectStackAdapter(config) {
   return new ObjectStackAdapter(config);
 }
 export {
+  AnalyticsNotInstalledError,
+  AnalyticsQueryRejectedError,
   AuthenticationError,
   BulkOperationError,
   CloudOperations,
   ConcurrentUpdateError,
   ConnectionError,
+  FILTER_OPERATOR_ALIASES,
   IntegrationManager,
+  MalformedFilterError,
   MetadataClient,
   MetadataNotFoundError,
   ObjectStackAdapter,
@@ -3226,6 +3692,7 @@ export {
   SecurityManager,
   ValidationError,
   calculateAutoLayout,
+  classifyAnalyticsFailure,
   clearSharedDiscoveryCache,
   createDefaultCanvasConfig,
   createErrorFromResponse,
@@ -3234,10 +3701,14 @@ export {
   generateContractManifest,
   getSharedDiscovery,
   is404Error,
+  isAnalyticsNotInstalledError,
   isConcurrentUpdateError,
   isErrorType,
+  isMalformedFilterError,
   isObjectStackError,
   normaliseClientError,
+  readTransactionalBatchCapability,
+  serializeOrderBy,
   snapToGrid,
   validatePluginContract
 };