@object-ui/data-objectstack 15.0.0 → 16.1.0

package/dist/index.cjs

@@ -47,6 +47,7 @@ __export(index_exports, {
   isErrorType: () => isErrorType,
   isObjectStackError: () => isObjectStackError,
   normaliseClientError: () => normaliseClientError,
+  readTransactionalBatchCapability: () => readTransactionalBatchCapability,
   snapToGrid: () => snapToGrid,
   validatePluginContract: () => validatePluginContract
 });
@@ -119,6 +120,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;
@@ -319,893 +386,898 @@ 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
-    };
+  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 MetadataNotFoundError = class extends ObjectStackError {
-  constructor(objectName, details) {
-    super(
-      `Metadata not found for object: ${objectName}`,
-      "METADATA_NOT_FOUND",
-      404,
-      { objectName, ...details }
-    );
-    this.name = "MetadataNotFoundError";
+  /**
+   * Get a single metadata item. Returns the unwrapped item content
+   * (matching the framework REST handler which calls `res.json(item)`).
+   * Returns `null` on 404 to keep the call-site ergonomic.
+   */
+  async get(type, name, 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();
   }
-};
-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
+   * 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.
    */
-  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 getDraft(type, name, options = {}) {
+    return this.get(type, name, { state: "draft", ...options.packageId ? { packageId: options.packageId } : {} });
   }
   /**
-   * Get a summary of the bulk operation failure
+   * 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).
    */
-  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 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();
   }
-};
-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
+   * 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.
    */
-  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 publishDraft(type, name) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/publish`;
+    const res = await this.fetchImpl(url, {
+      method: "POST",
+      headers: { ...this.headers, "Content-Type": "application/json", Accept: "application/json" },
+      body: "{}"
+    });
+    if (!res.ok) throw await parseError(res);
+    const body = await res.json().catch(() => ({}));
+    const inner = body?.data && typeof body.data === "object" ? body.data : body;
+    return inner;
   }
   /**
-   * Get all validation errors as a formatted list
+   * 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).
    */
-  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
+  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 };
+  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();
   }
-};
-
-// 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
+  /**
+   * Restore an item to a previous version (POST `/meta/:type/:name/rollback`).
+   * The server reads the history row at `toVersion`, writes its body back
+   * as the active overlay with `operation_type='revert'`. Returns
+   * `{ success, version, seq, restoredFromVersion, message }`. Throws
+   * `404 version_not_found` for unknown versions and `409 version_not_restorable`
+   * when the target version is a delete tombstone.
+   */
+  async rollback(type, name, toVersion, options = {}) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/rollback`;
+    const headers = {
+      ...this.headers,
+      "Content-Type": "application/json"
     };
-    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({
+        toVersion,
+        ...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.
+   * 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.
    */
-  register(id, config) {
-    this.integrations.set(id, config);
+  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();
   }
-  /**
-   * Remove an integration.
-   */
-  unregister(id) {
-    this.integrations.delete(id);
+  /** 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 all registered integrations.
+   * 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.
    */
-  getAll() {
-    return new Map(this.integrations);
+  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 {
   /**
-   * Get integrations that match a specific event.
+   * 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
    */
-  getForEvent(event) {
-    return Array.from(this.integrations.values()).filter(
-      (integration) => integration.enabled && integration.triggers?.some((t) => t.event === event)
-    );
+  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);
+    }
   }
   /**
-   * Dispatch an event to all matching integrations.
-   * Returns results for each integration.
+   * Convert error to JSON for logging/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 });
-      }
-    }
-    return results;
+  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";
   }
+};
+var BulkOperationError = class extends ObjectStackError {
   /**
-   * Send payload to a specific integration.
+   * 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
    */
-  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;
+  constructor(operation, successCount, failureCount, errors, details) {
+    super(
+      `Bulk ${operation} operation failed: ${successCount} succeeded, ${failureCount} failed`,
+      "BULK_OPERATION_ERROR",
+      500,
+      {
+        operation,
+        successCount,
+        failureCount,
+        errors,
+        ...details
       }
-      // Email and other providers would require server-side implementation
-      default:
-        break;
-    }
-  }
-};
-
-// 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
-    });
+    );
+    __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 };
-    }
-    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
-      };
+  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" });
+      }
     }
-    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 } : {}
-    };
   }
-  /**
-   * Cross-type sweep of load-time validation results — calls
-   * `GET /meta/diagnostics`. Returns every entry the framework
-   * considers invalid (or, when `severity: 'warning'`, also entries
-   * with only warnings).
-   *
-   * Used by the Studio's governance overview page and by the
-   * directory page to show "N invalid" badges per metadata type.
-   */
-  async diagnostics(options = {}) {
-    const params = [];
-    if (options.type) params.push(`type=${encodeURIComponent(options.type)}`);
-    if (options.severity) params.push(`severity=${encodeURIComponent(options.severity)}`);
-    if (options.packageId) params.push(`package=${encodeURIComponent(options.packageId)}`);
-    const qs = params.length ? `?${params.join("&")}` : "";
-    const url = `${this.base}/diagnostics${qs}`;
-    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
-    if (res.status === 404) {
-      return { entries: [], total: 0, scannedTypes: 0, scannedItems: 0, stats: {} };
+  if (!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 = () => {
     }
-    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 : {}
+  } = options;
+  let cachedRowId = null;
+  let saveChain = Promise.resolve();
+  const findExisting = async () => {
+    const params = {
+      $filter: {
+        user_id: userId,
+        key
+      },
+      $top: 1
     };
+    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 [];
+      }
+    }
+    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());
   }
   /**
-   * 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;
+    }
   }
 };
 
@@ -1446,6 +1518,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;
@@ -1546,6 +1628,21 @@ 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
@@ -1584,6 +1681,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");
@@ -1933,33 +2031,84 @@ 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);
+      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 MutationEvent 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];
@@ -1971,7 +2120,6 @@ var ObjectStackAdapter = class {
         this.emitMutation({ type: "delete", resource: op.object, id: op.id });
       }
     });
-    return payload;
   }
   async bulk(resource, operation, data) {
     await this.connect();
@@ -2692,22 +2840,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
@@ -2719,11 +2863,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;
@@ -2734,21 +2884,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
@@ -2793,14 +2958,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
@@ -2823,15 +2984,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
@@ -2840,14 +2997,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.
@@ -2903,19 +3056,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.
@@ -3287,6 +3436,7 @@ function createObjectStackAdapter(config) {
   isErrorType,
   isObjectStackError,
   normaliseClientError,
+  readTransactionalBatchCapability,
   snapToGrid,
   validatePluginContract
 });