@object-ui/data-objectstack 6.1.0 → 6.2.0

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # @object-ui/data-objectstack
 
+## 6.2.0
+
+### Minor Changes
+
+- ec8dcde: Add visual editing for object & field metadata in the Setup app.
+
+  **`@object-ui/data-objectstack`** — new `MetadataClient` class. A thin,
+  auth-friendly wrapper over the framework's `/api/v1/meta/*` REST
+  endpoints (list / get / save / reset / history), with first-class
+  support for `If-Match` (optimistic concurrency), `X-Actor` (audit
+  attribution), environment-scoped paths
+  (`/environments/:id/meta/*`), and 404-as-null semantics. Use
+  `new MetadataClient({ baseUrl })` or `client.withEnvironment(id)` to
+  target a specific environment.
+
+  **`@object-ui/plugin-designer`** — two new route-ready pages that
+  together close the "Data Model" management loop in the Setup app:
+  - `MetadataObjectsPage` — lists every object schema (via
+    `MetadataClient.list('object')`), renders the existing
+    `ObjectManager`, and persists edits/deletes through PUT/DELETE on
+    the metadata REST surface. Honours `allowRuntimeCreate` and
+    surfaces server errors verbatim.
+  - `MetadataFieldsPage` — for a single object, loads the parent
+    schema, projects `fields` into the existing `FieldDesigner`, and
+    on save merges the edited field map back into the object before
+    issuing a single PUT. Preserves unknown per-field attributes so
+    nothing the designer doesn't render is dropped.
+
+  Both pages take either a pre-built `MetadataClient` or a
+  `MetadataClientConfig`; neither imposes a routing convention on the
+  host app — they can be mounted anywhere (e.g.
+  `/apps/setup/_meta/object` and `/apps/setup/_meta/object/:name/fields`).
+
+  These additions do not modify the underlying `ObjectManager` /
+  `FieldDesigner` components, which remain pure controlled-input
+  components usable in non-REST contexts.
+
+### Patch Changes
+
+- fe3c1d3: Metadata Admin engine — unified UI for all 27 metadata types.
+
+  A generic, schema-driven admin shell that replaces the old per-type
+  bespoke pages with a single registry-driven engine. Admins can now browse,
+  create, override, diff, and roll back every registered metadata type from
+  the Setup app → _All Metadata Types_.
+
+  ### New: `@object-ui/app-shell` views/metadata-admin
+  - **`MetadataDirectoryPage`** — auto-grouped tile directory by domain, with
+    free-text search, domain chips, and a _Writable only_ filter.
+  - **`MetadataResourceListPage` / `MetadataResourceEditPage` / `…CreatePage` / `…HistoryPage`** —
+    generic CRUD shell. Uses the new `/meta/types` schema field to render
+    SchemaForm; uses `?layers=code,overlay,effective` to power a 3-state diff
+    tab; uses `/references` to warn before destructive deletes.
+  - **`MetadataQuickFind`** — Cmd+Shift+M palette searching across types and
+    items.
+  - **`PermissionMatrixEditor`** — Salesforce-style matrix custom editor for
+    `type=permission`. Objects × CRUD/VAMA/lifecycle columns with cascade
+    rules (viewAllRecords ⟹ allowRead, etc.), expandable per-object field
+    R/W subtable, bulk-set (R / CRUD / All / None), filter, _only granted_
+    toggle, destructive-change confirmation, profile switch.
+  - **`DesignerEditorWrapper`** — generic load–edit–save shell that hosts any
+    bespoke designer (`ObjectViewConfigurator`, `DashboardEditor`,
+    `PageCanvasEditor`, …). Handles dirty tracking, Save / Reset / Refresh /
+    History buttons, and the read-only fallback when `allowOrgOverride` is
+    false.
+  - **`i18n.ts`** — bilingual (`en-US`, `zh-CN`) bundle for built-in type
+    labels, domain labels, and engine UI strings, with `detectLocale()` and a
+    `t(key)` helper.
+
+  ### New routing variant
+  - App nav now supports `{ type: 'component', componentRef, params? }` items.
+    `AppContent` resolves them through the existing `ComponentRegistry`.
+  - Built-in components registered: `metadata:directory`, `metadata:resource`,
+    `metadata:object/edit` (FieldsPage), `metadata:permission/edit`
+    (PermissionMatrixEditor), and lazy designer wrappers for view / dashboard
+    / page.
+
+  ### Plugin-designer
+  - Lazy-exported `ObjectManager`, `FieldDesigner`, `ObjectViewConfigurator`,
+    `DashboardEditor`, `PageCanvasEditor`, `MetadataObjectsPage`, and
+    `MetadataFieldsPage` so the engine can mount them on demand.
+
+  The temporary `/dev/meta` route is removed. Setup app navigation flows
+  through the new component routes.
+  - @object-ui/types@6.2.0
+  - @object-ui/core@6.2.0
+
 ## 6.1.0
 
 ### Patch Changes

package/dist/index.cjs

@@ -28,6 +28,7 @@ __export(index_exports, {
   ConcurrentUpdateError: () => ConcurrentUpdateError,
   ConnectionError: () => ConnectionError,
   IntegrationManager: () => IntegrationManager,
+  MetadataClient: () => MetadataClient,
   MetadataNotFoundError: () => MetadataNotFoundError,
   ObjectStackAdapter: () => ObjectStackAdapter,
   ObjectStackError: () => ObjectStackError,
@@ -779,6 +780,181 @@ var IntegrationManager = class {
   }
 };
 
+// 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 message = (body && typeof body === "object" && "error" in body ? String(body.error) : void 0) ?? `Metadata request failed: ${res.status} ${res.statusText}`;
+  const err = new Error(message);
+  err.status = res.status;
+  err.body = body;
+  if (body && typeof body === "object" && "code" in body) {
+    err.code = String(body.code);
+  }
+  return err;
+}
+var MetadataClient = class _MetadataClient {
+  constructor(config) {
+    __publicField(this, "base");
+    __publicField(this, "fetchImpl");
+    __publicField(this, "headers");
+    this.base = buildBase(config);
+    this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this.headers = { Accept: "application/json", ...config.headers ?? {} };
+  }
+  /** 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
+    });
+  }
+  /** 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 qs = options.packageId ? `?package=${encodeURIComponent(options.packageId)}` : "";
+    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 [];
+  }
+  /**
+   * Get a single metadata item. Returns the unwrapped item content
+   * (matching the framework REST handler which calls `res.json(item)`).
+   * Returns `null` on 404 to keep the call-site ergonomic.
+   */
+  async get(type, name) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}`;
+    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();
+  }
+  /**
+   * Save (PUT) a metadata item. The framework accepts both the bare
+   * item payload and the `{ item: ... }` / `{ metadata: ... }`
+   * envelopes; we send bare for consistency.
+   */
+  async save(type, name, item, options = {}) {
+    const qs = options.force ? "?force=true" : "";
+    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 the 3-state layered view of a metadata item (Phase 3a). Returns
+   * `code` (the artifact / fallback default), `overlay` (the saved
+   * customisation, if any), and `effective` (what the runtime sees).
+   */
+  async layered(type, name) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}?layers=true`;
+    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
+      };
+    }
+    return {
+      code: body.code ?? null,
+      overlay: body.overlay ?? null,
+      overlayScope: body.overlayScope ?? null,
+      effective: body.effective ?? null
+    };
+  }
+  /**
+   * 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 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 ?? [];
+  }
+  /**
+   * Reset a metadata customization overlay back to the artifact default.
+   * Idempotent: returns the result even when no overlay row existed.
+   */
+  async reset(type, name, options = {}) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}`;
+    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();
+  }
+  /** 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();
+  }
+};
+
 // src/security.ts
 var SecurityManager = class {
   constructor(policy = {}) {
@@ -2348,6 +2524,7 @@ function createObjectStackAdapter(config) {
   ConcurrentUpdateError,
   ConnectionError,
   IntegrationManager,
+  MetadataClient,
   MetadataNotFoundError,
   ObjectStackAdapter,
   ObjectStackError,

package/dist/index.d.cts

@@ -491,6 +491,162 @@ declare class IntegrationManager {
     private send;
 }
 
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * MetadataClient
+ *
+ * Thin, framework-agnostic HTTP client for the ObjectStack metadata
+ * API (`/api/v1/meta/*`). Used by the platform Setup app surfaces in
+ * `@object-ui/plugin-designer` (Object Manager, Field Designer, etc.)
+ * so they can read and write protocol metadata without depending on
+ * `ObjectStackAdapter` (which is a generic data-source binding and
+ * carries a lot of view/dashboard-specific behaviour we don't need
+ * here).
+ *
+ * Endpoints (see `packages/rest/src/rest-server.ts`):
+ *   GET    /api/v1/meta                  — list all metadata types
+ *   GET    /api/v1/meta/:type            — list items of a type
+ *   GET    /api/v1/meta/:type/:name      — get one item (returns the
+ *                                          unwrapped item content)
+ *   PUT    /api/v1/meta/:type/:name      — save (overlay) one item
+ *                                          honours `If-Match` for OCC
+ *   DELETE /api/v1/meta/:type/:name      — reset overlay to artifact
+ *   GET    /api/v1/meta/:type/:name/history — durable change log
+ *
+ * The client deliberately keeps the response shape opaque (typed as
+ * `unknown`/generic `T`) so callers explicitly narrow per-metadata-
+ * type, mirroring the framework's "single Zod source per type" rule.
+ */
+interface MetadataClientConfig {
+    /** Base URL of the ObjectStack server (no trailing slash needed). */
+    baseUrl: string;
+    /**
+     * Optional environment ID to scope reads/writes to a tenant. When
+     * provided, requests use the scoped path
+     * `/api/v1/environments/:environmentId/meta/...` and overlays are
+     * persisted in the environment's own metadata store.
+     */
+    environmentId?: string;
+    /** Optional custom fetch implementation (defaults to `globalThis.fetch`). */
+    fetch?: typeof fetch;
+    /** Additional headers (e.g. auth) included on every request. */
+    headers?: Record<string, string>;
+}
+interface MetadataListOptions {
+    /** Filter by source package id (matches the `package` query param). */
+    packageId?: string;
+}
+interface MetadataSaveOptions {
+    /**
+     * Optimistic concurrency token (the `checksum` returned by the last
+     * read). When present, sent as the `If-Match` header so concurrent
+     * edits get a 409 instead of overwriting each other.
+     */
+    ifMatch?: string;
+    /** Optional actor id, sent as `X-Actor` for history attribution. */
+    actor?: string;
+    /**
+     * Bypass destructive-change protection (Phase 3a). The server returns
+     * `409 destructive_change` with `issues[]` if a write would drop or
+     * narrow data; setting `force: true` adds `?force=true` to the request
+     * so the operator can confirm and proceed.
+     */
+    force?: boolean;
+}
+/** Layered view of a metadata item — Phase 3a `?layers=true`. */
+interface MetadataLayered<T = unknown> {
+    /** Code-level (artifact) item; null if the item only exists as an overlay. */
+    code: T | null;
+    /** Org/environment overlay (just the saved delta or full overlay row). */
+    overlay: T | null;
+    /** Overlay scope (`organization` | `environment` | `package` | null). */
+    overlayScope: string | null;
+    /** Merged effective view — what the runtime actually sees. */
+    effective: T | null;
+}
+/** Reference back-pointer — Phase 3a `/references`. */
+interface MetadataReference {
+    /** Referencing item's metadata type. */
+    fromType: string;
+    /** Referencing item's name. */
+    fromName: string;
+    /** JSON path within the referencing item that holds the reference. */
+    path: string;
+    /** The actual value seen at `path` (the referenced name). */
+    value: string;
+}
+interface MetadataHistoryOptions {
+    /** Only return events after this sequence number. */
+    sinceSeq?: number;
+    /** Limit the number of events returned. */
+    limit?: number;
+}
+interface MetadataError extends Error {
+    status: number;
+    code?: string;
+    body?: unknown;
+}
+/**
+ * MetadataClient — read/write protocol metadata via the framework REST API.
+ *
+ * @example
+ * ```ts
+ * const client = new MetadataClient({ baseUrl: 'http://localhost:3000' });
+ * const objects = await client.list<{ name: string; label?: string }>('object');
+ * const account = await client.get<{ fields: Record<string, unknown> }>('object', 'account');
+ * await client.save('object', 'account', { ...account, label: 'Customer' });
+ * ```
+ */
+declare class MetadataClient {
+    private readonly base;
+    private readonly fetchImpl;
+    private readonly headers;
+    constructor(config: MetadataClientConfig);
+    /** Update the client's environment scope at runtime. */
+    withEnvironment(environmentId: string | undefined): MetadataClient;
+    /** List all registered metadata types (returns the registry rows). */
+    listTypes(): Promise<unknown[]>;
+    /** List items of a metadata type (e.g. `object`, `field`, `view`). */
+    list<T = unknown>(type: string, options?: MetadataListOptions): Promise<T[]>;
+    /**
+     * 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<T = unknown>(type: string, name: string): Promise<T | null>;
+    /**
+     * Save (PUT) a metadata item. The framework accepts both the bare
+     * item payload and the `{ item: ... }` / `{ metadata: ... }`
+     * envelopes; we send bare for consistency.
+     */
+    save<T = unknown>(type: string, name: string, item: unknown, options?: MetadataSaveOptions): Promise<T>;
+    /**
+     * 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).
+     */
+    layered<T = unknown>(type: string, name: string): Promise<MetadataLayered<T>>;
+    /**
+     * 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?".
+     */
+    references(type: string, name: string): Promise<MetadataReference[]>;
+    /**
+     * Reset a metadata customization overlay back to the artifact default.
+     * Idempotent: returns the result even when no overlay row existed.
+     */
+    reset<T = unknown>(type: string, name: string, options?: MetadataSaveOptions): Promise<T>;
+    /** Fetch the durable history (change log) for one metadata item. */
+    history<T = unknown>(type: string, name: string, options?: MetadataHistoryOptions): Promise<T>;
+}
+
 /**
  * ObjectUI
  * Copyright (c) 2024-present ObjectStack Inc.
@@ -1233,4 +1389,4 @@ declare function createObjectStackAdapter<T = unknown>(config: {
     reconnectDelay?: number;
 }): DataSource<T>;
 
-export { type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, type CacheStats, type CloudDeploymentConfig, type CloudHostingConfig, type CloudMarketplaceEntry, CloudOperations, ConcurrentUpdateError, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, type DataMaskingConfig, type DataMaskingRule, type EmailIntegrationConfig, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, MetadataNotFoundError, ObjectStackAdapter, ObjectStackError, type ObjectStackUserStateAdapterOptions, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, type UserDataAdapter, ValidationError, type WebhookIntegrationConfig, calculateAutoLayout, clearSharedDiscoveryCache, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, createObjectStackUserStateAdapter, generateContractManifest, getSharedDiscovery, is404Error, isConcurrentUpdateError, isErrorType, isObjectStackError, normaliseClientError, snapToGrid, validatePluginContract };
+export { type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, type CacheStats, type CloudDeploymentConfig, type CloudHostingConfig, type CloudMarketplaceEntry, CloudOperations, ConcurrentUpdateError, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, type DataMaskingConfig, type DataMaskingRule, type EmailIntegrationConfig, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, MetadataClient, type MetadataClientConfig, type MetadataError, type MetadataHistoryOptions, type MetadataLayered, type MetadataListOptions, MetadataNotFoundError, type MetadataReference, type MetadataSaveOptions, ObjectStackAdapter, ObjectStackError, type ObjectStackUserStateAdapterOptions, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, type UserDataAdapter, ValidationError, type WebhookIntegrationConfig, calculateAutoLayout, clearSharedDiscoveryCache, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, createObjectStackUserStateAdapter, generateContractManifest, getSharedDiscovery, is404Error, isConcurrentUpdateError, isErrorType, isObjectStackError, normaliseClientError, snapToGrid, validatePluginContract };

package/dist/index.d.ts

@@ -491,6 +491,162 @@ declare class IntegrationManager {
     private send;
 }
 
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * MetadataClient
+ *
+ * Thin, framework-agnostic HTTP client for the ObjectStack metadata
+ * API (`/api/v1/meta/*`). Used by the platform Setup app surfaces in
+ * `@object-ui/plugin-designer` (Object Manager, Field Designer, etc.)
+ * so they can read and write protocol metadata without depending on
+ * `ObjectStackAdapter` (which is a generic data-source binding and
+ * carries a lot of view/dashboard-specific behaviour we don't need
+ * here).
+ *
+ * Endpoints (see `packages/rest/src/rest-server.ts`):
+ *   GET    /api/v1/meta                  — list all metadata types
+ *   GET    /api/v1/meta/:type            — list items of a type
+ *   GET    /api/v1/meta/:type/:name      — get one item (returns the
+ *                                          unwrapped item content)
+ *   PUT    /api/v1/meta/:type/:name      — save (overlay) one item
+ *                                          honours `If-Match` for OCC
+ *   DELETE /api/v1/meta/:type/:name      — reset overlay to artifact
+ *   GET    /api/v1/meta/:type/:name/history — durable change log
+ *
+ * The client deliberately keeps the response shape opaque (typed as
+ * `unknown`/generic `T`) so callers explicitly narrow per-metadata-
+ * type, mirroring the framework's "single Zod source per type" rule.
+ */
+interface MetadataClientConfig {
+    /** Base URL of the ObjectStack server (no trailing slash needed). */
+    baseUrl: string;
+    /**
+     * Optional environment ID to scope reads/writes to a tenant. When
+     * provided, requests use the scoped path
+     * `/api/v1/environments/:environmentId/meta/...` and overlays are
+     * persisted in the environment's own metadata store.
+     */
+    environmentId?: string;
+    /** Optional custom fetch implementation (defaults to `globalThis.fetch`). */
+    fetch?: typeof fetch;
+    /** Additional headers (e.g. auth) included on every request. */
+    headers?: Record<string, string>;
+}
+interface MetadataListOptions {
+    /** Filter by source package id (matches the `package` query param). */
+    packageId?: string;
+}
+interface MetadataSaveOptions {
+    /**
+     * Optimistic concurrency token (the `checksum` returned by the last
+     * read). When present, sent as the `If-Match` header so concurrent
+     * edits get a 409 instead of overwriting each other.
+     */
+    ifMatch?: string;
+    /** Optional actor id, sent as `X-Actor` for history attribution. */
+    actor?: string;
+    /**
+     * Bypass destructive-change protection (Phase 3a). The server returns
+     * `409 destructive_change` with `issues[]` if a write would drop or
+     * narrow data; setting `force: true` adds `?force=true` to the request
+     * so the operator can confirm and proceed.
+     */
+    force?: boolean;
+}
+/** Layered view of a metadata item — Phase 3a `?layers=true`. */
+interface MetadataLayered<T = unknown> {
+    /** Code-level (artifact) item; null if the item only exists as an overlay. */
+    code: T | null;
+    /** Org/environment overlay (just the saved delta or full overlay row). */
+    overlay: T | null;
+    /** Overlay scope (`organization` | `environment` | `package` | null). */
+    overlayScope: string | null;
+    /** Merged effective view — what the runtime actually sees. */
+    effective: T | null;
+}
+/** Reference back-pointer — Phase 3a `/references`. */
+interface MetadataReference {
+    /** Referencing item's metadata type. */
+    fromType: string;
+    /** Referencing item's name. */
+    fromName: string;
+    /** JSON path within the referencing item that holds the reference. */
+    path: string;
+    /** The actual value seen at `path` (the referenced name). */
+    value: string;
+}
+interface MetadataHistoryOptions {
+    /** Only return events after this sequence number. */
+    sinceSeq?: number;
+    /** Limit the number of events returned. */
+    limit?: number;
+}
+interface MetadataError extends Error {
+    status: number;
+    code?: string;
+    body?: unknown;
+}
+/**
+ * MetadataClient — read/write protocol metadata via the framework REST API.
+ *
+ * @example
+ * ```ts
+ * const client = new MetadataClient({ baseUrl: 'http://localhost:3000' });
+ * const objects = await client.list<{ name: string; label?: string }>('object');
+ * const account = await client.get<{ fields: Record<string, unknown> }>('object', 'account');
+ * await client.save('object', 'account', { ...account, label: 'Customer' });
+ * ```
+ */
+declare class MetadataClient {
+    private readonly base;
+    private readonly fetchImpl;
+    private readonly headers;
+    constructor(config: MetadataClientConfig);
+    /** Update the client's environment scope at runtime. */
+    withEnvironment(environmentId: string | undefined): MetadataClient;
+    /** List all registered metadata types (returns the registry rows). */
+    listTypes(): Promise<unknown[]>;
+    /** List items of a metadata type (e.g. `object`, `field`, `view`). */
+    list<T = unknown>(type: string, options?: MetadataListOptions): Promise<T[]>;
+    /**
+     * 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<T = unknown>(type: string, name: string): Promise<T | null>;
+    /**
+     * Save (PUT) a metadata item. The framework accepts both the bare
+     * item payload and the `{ item: ... }` / `{ metadata: ... }`
+     * envelopes; we send bare for consistency.
+     */
+    save<T = unknown>(type: string, name: string, item: unknown, options?: MetadataSaveOptions): Promise<T>;
+    /**
+     * 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).
+     */
+    layered<T = unknown>(type: string, name: string): Promise<MetadataLayered<T>>;
+    /**
+     * 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?".
+     */
+    references(type: string, name: string): Promise<MetadataReference[]>;
+    /**
+     * Reset a metadata customization overlay back to the artifact default.
+     * Idempotent: returns the result even when no overlay row existed.
+     */
+    reset<T = unknown>(type: string, name: string, options?: MetadataSaveOptions): Promise<T>;
+    /** Fetch the durable history (change log) for one metadata item. */
+    history<T = unknown>(type: string, name: string, options?: MetadataHistoryOptions): Promise<T>;
+}
+
 /**
  * ObjectUI
  * Copyright (c) 2024-present ObjectStack Inc.
@@ -1233,4 +1389,4 @@ declare function createObjectStackAdapter<T = unknown>(config: {
     reconnectDelay?: number;
 }): DataSource<T>;
 
-export { type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, type CacheStats, type CloudDeploymentConfig, type CloudHostingConfig, type CloudMarketplaceEntry, CloudOperations, ConcurrentUpdateError, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, type DataMaskingConfig, type DataMaskingRule, type EmailIntegrationConfig, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, MetadataNotFoundError, ObjectStackAdapter, ObjectStackError, type ObjectStackUserStateAdapterOptions, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, type UserDataAdapter, ValidationError, type WebhookIntegrationConfig, calculateAutoLayout, clearSharedDiscoveryCache, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, createObjectStackUserStateAdapter, generateContractManifest, getSharedDiscovery, is404Error, isConcurrentUpdateError, isErrorType, isObjectStackError, normaliseClientError, snapToGrid, validatePluginContract };
+export { type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, type CacheStats, type CloudDeploymentConfig, type CloudHostingConfig, type CloudMarketplaceEntry, CloudOperations, ConcurrentUpdateError, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, type DataMaskingConfig, type DataMaskingRule, type EmailIntegrationConfig, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, MetadataClient, type MetadataClientConfig, type MetadataError, type MetadataHistoryOptions, type MetadataLayered, type MetadataListOptions, MetadataNotFoundError, type MetadataReference, type MetadataSaveOptions, ObjectStackAdapter, ObjectStackError, type ObjectStackUserStateAdapterOptions, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, type UserDataAdapter, ValidationError, type WebhookIntegrationConfig, calculateAutoLayout, clearSharedDiscoveryCache, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, createObjectStackUserStateAdapter, generateContractManifest, getSharedDiscovery, is404Error, isConcurrentUpdateError, isErrorType, isObjectStackError, normaliseClientError, snapToGrid, validatePluginContract };

package/dist/index.js

@@ -732,6 +732,181 @@ var IntegrationManager = class {
   }
 };
 
+// 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 message = (body && typeof body === "object" && "error" in body ? String(body.error) : void 0) ?? `Metadata request failed: ${res.status} ${res.statusText}`;
+  const err = new Error(message);
+  err.status = res.status;
+  err.body = body;
+  if (body && typeof body === "object" && "code" in body) {
+    err.code = String(body.code);
+  }
+  return err;
+}
+var MetadataClient = class _MetadataClient {
+  constructor(config) {
+    __publicField(this, "base");
+    __publicField(this, "fetchImpl");
+    __publicField(this, "headers");
+    this.base = buildBase(config);
+    this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this.headers = { Accept: "application/json", ...config.headers ?? {} };
+  }
+  /** 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
+    });
+  }
+  /** 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 qs = options.packageId ? `?package=${encodeURIComponent(options.packageId)}` : "";
+    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 [];
+  }
+  /**
+   * Get a single metadata item. Returns the unwrapped item content
+   * (matching the framework REST handler which calls `res.json(item)`).
+   * Returns `null` on 404 to keep the call-site ergonomic.
+   */
+  async get(type, name) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}`;
+    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();
+  }
+  /**
+   * Save (PUT) a metadata item. The framework accepts both the bare
+   * item payload and the `{ item: ... }` / `{ metadata: ... }`
+   * envelopes; we send bare for consistency.
+   */
+  async save(type, name, item, options = {}) {
+    const qs = options.force ? "?force=true" : "";
+    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 the 3-state layered view of a metadata item (Phase 3a). Returns
+   * `code` (the artifact / fallback default), `overlay` (the saved
+   * customisation, if any), and `effective` (what the runtime sees).
+   */
+  async layered(type, name) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}?layers=true`;
+    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
+      };
+    }
+    return {
+      code: body.code ?? null,
+      overlay: body.overlay ?? null,
+      overlayScope: body.overlayScope ?? null,
+      effective: body.effective ?? null
+    };
+  }
+  /**
+   * 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 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 ?? [];
+  }
+  /**
+   * Reset a metadata customization overlay back to the artifact default.
+   * Idempotent: returns the result even when no overlay row existed.
+   */
+  async reset(type, name, options = {}) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}`;
+    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();
+  }
+  /** 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();
+  }
+};
+
 // src/security.ts
 var SecurityManager = class {
   constructor(policy = {}) {
@@ -2300,6 +2475,7 @@ export {
   ConcurrentUpdateError,
   ConnectionError,
   IntegrationManager,
+  MetadataClient,
   MetadataNotFoundError,
   ObjectStackAdapter,
   ObjectStackError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/data-objectstack",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "description": "ObjectStack Data Adapter for Object UI",
   "license": "MIT",
   "type": "module",
@@ -22,9 +22,9 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@objectstack/client": "^5.2.0",
-    "@object-ui/core": "6.1.0",
-    "@object-ui/types": "6.1.0"
+    "@objectstack/client": "^6.7.1",
+    "@object-ui/core": "6.2.0",
+    "@object-ui/types": "6.2.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1",

package/src/index.ts

@@ -2068,6 +2068,21 @@ export type { PluginContract, PluginExport, PluginAPIContract, ContractValidatio
 export { IntegrationManager } from './integration';
 export type { IntegrationConfig, IntegrationTrigger, IntegrationProvider, SlackIntegrationConfig, EmailIntegrationConfig, WebhookIntegrationConfig } from './integration';
 
+// Metadata API client — read/write protocol metadata via /api/v1/meta/*.
+// Used by plugin-designer to back the Setup-app Object Manager and Field
+// Designer surfaces; kept separate from ObjectStackAdapter so callers
+// can use it without the full data-source surface.
+export { MetadataClient } from './metadata-client';
+export type {
+  MetadataClientConfig,
+  MetadataListOptions,
+  MetadataSaveOptions,
+  MetadataHistoryOptions,
+  MetadataError,
+  MetadataLayered,
+  MetadataReference,
+} from './metadata-client';
+
 export { SecurityManager } from './security';
 export type { SecurityPolicy, CSPConfig, AuditLogConfig, AuditEventType, DataMaskingConfig, DataMaskingRule, AuditLogEntry } from './security';
 

package/src/metadata-client.test.ts

@@ -0,0 +1,124 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { MetadataClient } from './metadata-client';
+
+function mockFetch(handler: (url: string, init?: RequestInit) => Promise<Response>): typeof fetch {
+  return vi.fn(handler) as unknown as typeof fetch;
+}
+
+function jsonResponse(body: unknown, init?: ResponseInit): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+    ...init,
+  });
+}
+
+describe('MetadataClient', () => {
+  let urls: string[];
+  let inits: (RequestInit | undefined)[];
+
+  beforeEach(() => {
+    urls = [];
+    inits = [];
+  });
+
+  function client(baseUrl: string, environmentId?: string) {
+    return new MetadataClient({
+      baseUrl,
+      environmentId,
+      fetch: mockFetch(async (url, init) => {
+        urls.push(url);
+        inits.push(init);
+        if (init?.method === 'PUT' || init?.method === 'DELETE') {
+          return jsonResponse({ ok: true });
+        }
+        if (url.endsWith('/meta')) return jsonResponse([{ type: 'object' }]);
+        if (url.match(/\/meta\/object$/)) return jsonResponse([{ name: 'account' }]);
+        if (url.match(/\/meta\/object\/account$/)) {
+          return jsonResponse({ name: 'account', label: 'Account' });
+        }
+        if (url.match(/\/meta\/object\/missing$/)) {
+          return new Response('not found', { status: 404 });
+        }
+        if (url.match(/history$/)) return jsonResponse({ events: [] });
+        return jsonResponse({ items: [{ name: 'fallback' }] });
+      }),
+    });
+  }
+
+  it('builds unscoped URLs against the bare baseUrl', async () => {
+    await client('http://localhost:3000').list('object');
+    expect(urls[0]).toBe('http://localhost:3000/api/v1/meta/object');
+  });
+
+  it('builds scoped URLs when environmentId is set', async () => {
+    await client('http://localhost:3000', 'env_42').list('object');
+    expect(urls[0]).toBe('http://localhost:3000/api/v1/environments/env_42/meta/object');
+  });
+
+  it('collapses /api/v1 suffix on baseUrl to avoid duplication', async () => {
+    await client('http://localhost:3000/api/v1').list('object');
+    expect(urls[0]).toBe('http://localhost:3000/api/v1/meta/object');
+  });
+
+  it('returns null on 404 from get()', async () => {
+    const result = await client('http://localhost:3000').get('object', 'missing');
+    expect(result).toBeNull();
+  });
+
+  it('unwraps `items` envelope on list when the server returns one', async () => {
+    const c = new MetadataClient({
+      baseUrl: 'http://localhost:3000',
+      fetch: mockFetch(async () => jsonResponse({ items: [{ name: 'wrapped' }] })),
+    });
+    const items = await c.list<{ name: string }>('field');
+    expect(items).toEqual([{ name: 'wrapped' }]);
+  });
+
+  it('sends If-Match and X-Actor headers on save when provided', async () => {
+    await client('http://localhost:3000').save('object', 'account', { foo: 1 }, {
+      ifMatch: 'sha256:abc',
+      actor: 'user_1',
+    });
+    expect(inits[0]?.method).toBe('PUT');
+    const headers = inits[0]?.headers as Record<string, string>;
+    expect(headers['If-Match']).toBe('sha256:abc');
+    expect(headers['X-Actor']).toBe('user_1');
+    expect(headers['Content-Type']).toBe('application/json');
+    expect(inits[0]?.body).toBe(JSON.stringify({ foo: 1 }));
+  });
+
+  it('encodes type and name path segments', async () => {
+    await client('http://localhost:3000').get('object', 'has spaces');
+    expect(urls[0]).toBe('http://localhost:3000/api/v1/meta/object/has%20spaces');
+  });
+
+  it('builds history URL with query params', async () => {
+    await client('http://localhost:3000').history('view', 'all', { sinceSeq: 10, limit: 5 });
+    expect(urls[0]).toBe('http://localhost:3000/api/v1/meta/view/all/history?sinceSeq=10&limit=5');
+  });
+
+  it('throws MetadataError with status and body on failure', async () => {
+    const c = new MetadataClient({
+      baseUrl: 'http://localhost:3000',
+      fetch: mockFetch(async () =>
+        new Response(JSON.stringify({ error: 'metadata_conflict', code: 'metadata_conflict' }), {
+          status: 409,
+          headers: { 'content-type': 'application/json' },
+        })),
+    });
+    await expect(c.save('object', 'account', {})).rejects.toMatchObject({
+      status: 409,
+      code: 'metadata_conflict',
+      message: 'metadata_conflict',
+    });
+  });
+});

package/src/metadata-client.ts

@@ -0,0 +1,338 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * MetadataClient
+ *
+ * Thin, framework-agnostic HTTP client for the ObjectStack metadata
+ * API (`/api/v1/meta/*`). Used by the platform Setup app surfaces in
+ * `@object-ui/plugin-designer` (Object Manager, Field Designer, etc.)
+ * so they can read and write protocol metadata without depending on
+ * `ObjectStackAdapter` (which is a generic data-source binding and
+ * carries a lot of view/dashboard-specific behaviour we don't need
+ * here).
+ *
+ * Endpoints (see `packages/rest/src/rest-server.ts`):
+ *   GET    /api/v1/meta                  — list all metadata types
+ *   GET    /api/v1/meta/:type            — list items of a type
+ *   GET    /api/v1/meta/:type/:name      — get one item (returns the
+ *                                          unwrapped item content)
+ *   PUT    /api/v1/meta/:type/:name      — save (overlay) one item
+ *                                          honours `If-Match` for OCC
+ *   DELETE /api/v1/meta/:type/:name      — reset overlay to artifact
+ *   GET    /api/v1/meta/:type/:name/history — durable change log
+ *
+ * The client deliberately keeps the response shape opaque (typed as
+ * `unknown`/generic `T`) so callers explicitly narrow per-metadata-
+ * type, mirroring the framework's "single Zod source per type" rule.
+ */
+
+export interface MetadataClientConfig {
+  /** Base URL of the ObjectStack server (no trailing slash needed). */
+  baseUrl: string;
+  /**
+   * Optional environment ID to scope reads/writes to a tenant. When
+   * provided, requests use the scoped path
+   * `/api/v1/environments/:environmentId/meta/...` and overlays are
+   * persisted in the environment's own metadata store.
+   */
+  environmentId?: string;
+  /** Optional custom fetch implementation (defaults to `globalThis.fetch`). */
+  fetch?: typeof fetch;
+  /** Additional headers (e.g. auth) included on every request. */
+  headers?: Record<string, string>;
+}
+
+export interface MetadataListOptions {
+  /** Filter by source package id (matches the `package` query param). */
+  packageId?: string;
+}
+
+export interface MetadataSaveOptions {
+  /**
+   * Optimistic concurrency token (the `checksum` returned by the last
+   * read). When present, sent as the `If-Match` header so concurrent
+   * edits get a 409 instead of overwriting each other.
+   */
+  ifMatch?: string;
+  /** Optional actor id, sent as `X-Actor` for history attribution. */
+  actor?: string;
+  /**
+   * Bypass destructive-change protection (Phase 3a). The server returns
+   * `409 destructive_change` with `issues[]` if a write would drop or
+   * narrow data; setting `force: true` adds `?force=true` to the request
+   * so the operator can confirm and proceed.
+   */
+  force?: boolean;
+}
+
+/** Layered view of a metadata item — Phase 3a `?layers=true`. */
+export interface MetadataLayered<T = unknown> {
+  /** Code-level (artifact) item; null if the item only exists as an overlay. */
+  code: T | null;
+  /** Org/environment overlay (just the saved delta or full overlay row). */
+  overlay: T | null;
+  /** Overlay scope (`organization` | `environment` | `package` | null). */
+  overlayScope: string | null;
+  /** Merged effective view — what the runtime actually sees. */
+  effective: T | null;
+}
+
+/** Reference back-pointer — Phase 3a `/references`. */
+export interface MetadataReference {
+  /** Referencing item's metadata type. */
+  fromType: string;
+  /** Referencing item's name. */
+  fromName: string;
+  /** JSON path within the referencing item that holds the reference. */
+  path: string;
+  /** The actual value seen at `path` (the referenced name). */
+  value: string;
+}
+
+export interface MetadataHistoryOptions {
+  /** Only return events after this sequence number. */
+  sinceSeq?: number;
+  /** Limit the number of events returned. */
+  limit?: number;
+}
+
+export interface MetadataError extends Error {
+  status: number;
+  code?: string;
+  body?: unknown;
+}
+
+const META_PREFIX = '/meta';
+const API_PREFIX = '/api/v1';
+
+function buildBase(config: MetadataClientConfig): string {
+  const trimmed = config.baseUrl.replace(/\/+$/, '');
+  const scoped = config.environmentId
+    ? `${API_PREFIX}/environments/${encodeURIComponent(config.environmentId)}${META_PREFIX}`
+    : `${API_PREFIX}${META_PREFIX}`;
+  // Allow baseUrl to already include `/api/v1`; collapse the duplicate.
+  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: Response): Promise<MetadataError> {
+  let body: unknown;
+  try {
+    body = await res.json();
+  } catch {
+    body = await res.text().catch(() => undefined);
+  }
+  const message =
+    (body && typeof body === 'object' && 'error' in (body as Record<string, unknown>)
+      ? String((body as Record<string, unknown>).error)
+      : undefined) ?? `Metadata request failed: ${res.status} ${res.statusText}`;
+  const err = new Error(message) as MetadataError;
+  err.status = res.status;
+  err.body = body;
+  if (body && typeof body === 'object' && 'code' in (body as Record<string, unknown>)) {
+    err.code = String((body as Record<string, unknown>).code);
+  }
+  return err;
+}
+
+/**
+ * MetadataClient — read/write protocol metadata via the framework REST API.
+ *
+ * @example
+ * ```ts
+ * const client = new MetadataClient({ baseUrl: 'http://localhost:3000' });
+ * const objects = await client.list<{ name: string; label?: string }>('object');
+ * const account = await client.get<{ fields: Record<string, unknown> }>('object', 'account');
+ * await client.save('object', 'account', { ...account, label: 'Customer' });
+ * ```
+ */
+export class MetadataClient {
+  private readonly base: string;
+  private readonly fetchImpl: typeof fetch;
+  private readonly headers: Record<string, string>;
+
+  constructor(config: MetadataClientConfig) {
+    this.base = buildBase(config);
+    this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this.headers = { Accept: 'application/json', ...(config.headers ?? {}) };
+  }
+
+  /** Update the client's environment scope at runtime. */
+  withEnvironment(environmentId: string | undefined): MetadataClient {
+    return new MetadataClient({
+      baseUrl: this.base
+        .replace(/\/api\/v\d+(?:\/environments\/[^/]+)?\/meta$/, '')
+        .replace(/\/+$/, ''),
+      environmentId,
+      fetch: this.fetchImpl,
+      headers: this.headers,
+    });
+  }
+
+  /** List all registered metadata types (returns the registry rows). */
+  async listTypes(): Promise<unknown[]> {
+    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;
+    // Framework REST returns `{ types: string[], entries: TypeEntry[] }`
+    // where `entries` is the rich per-type registry row. Older / scoped
+    // shapes may use `items`. Prefer `entries` (rich), fall back to
+    // `items` (legacy), then synthesize stub entries from `types[]`
+    // if neither is present.
+    if (data && Array.isArray((data as any).entries)) return (data as any).entries;
+    if (data && Array.isArray((data as any).items)) return (data as any).items;
+    if (data && Array.isArray((data as any).types)) {
+      return (data as any).types.map((t: string) => ({ type: t }));
+    }
+    return [];
+  }
+
+  /** List items of a metadata type (e.g. `object`, `field`, `view`). */
+  async list<T = unknown>(type: string, options: MetadataListOptions = {}): Promise<T[]> {
+    const qs = options.packageId
+      ? `?package=${encodeURIComponent(options.packageId)}`
+      : '';
+    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 as T[];
+    if (data && Array.isArray((data as { items?: unknown[] }).items)) {
+      return (data as { items: T[] }).items;
+    }
+    return [];
+  }
+
+  /**
+   * 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<T = unknown>(type: string, name: string): Promise<T | null> {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}`;
+    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()) as T;
+  }
+
+  /**
+   * Save (PUT) a metadata item. The framework accepts both the bare
+   * item payload and the `{ item: ... }` / `{ metadata: ... }`
+   * envelopes; we send bare for consistency.
+   */
+  async save<T = unknown>(
+    type: string,
+    name: string,
+    item: unknown,
+    options: MetadataSaveOptions = {},
+  ): Promise<T> {
+    const qs = options.force ? '?force=true' : '';
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}${qs}`;
+    const headers: Record<string, string> = {
+      ...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()) as T;
+  }
+
+  /**
+   * 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<T = unknown>(type: string, name: string): Promise<MetadataLayered<T>> {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}?layers=true`;
+    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()) as MetadataLayered<T> & Record<string, unknown>;
+    const hasEnvelope =
+      body && (('code' in body) || ('overlay' in body) || ('effective' in body));
+    if (!hasEnvelope) {
+      return {
+        code: null,
+        overlay: null,
+        overlayScope: null,
+        effective: body as unknown as T,
+      };
+    }
+    return {
+      code: body.code ?? null,
+      overlay: body.overlay ?? null,
+      overlayScope: body.overlayScope ?? null,
+      effective: body.effective ?? null,
+    };
+  }
+
+  /**
+   * 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 references(type: string, name: string): Promise<MetadataReference[]> {
+    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 as MetadataReference[]) : (data?.items ?? []);
+  }
+
+  /**
+   * Reset a metadata customization overlay back to the artifact default.
+   * Idempotent: returns the result even when no overlay row existed.
+   */
+  async reset<T = unknown>(
+    type: string,
+    name: string,
+    options: MetadataSaveOptions = {},
+  ): Promise<T> {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}`;
+    const headers: Record<string, string> = { ...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()) as T;
+  }
+
+  /** Fetch the durable history (change log) for one metadata item. */
+  async history<T = unknown>(
+    type: string,
+    name: string,
+    options: MetadataHistoryOptions = {},
+  ): Promise<T> {
+    const params = new URLSearchParams();
+    if (options.sinceSeq !== undefined) params.set('sinceSeq', String(options.sinceSeq));
+    if (options.limit !== undefined) 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()) as T;
+  }
+}