@objectstack/metadata-protocol 11.1.0

package/dist/index.d.ts

@@ -0,0 +1,1893 @@
+import * as _objectstack_metadata_core from '@objectstack/metadata-core';
+import { MetadataRepository, MetaRef, MetadataItem, PutOptions, PutResult, DeleteOptions, DeleteResult, MetadataWriteIntent, ListFilter, MetadataItemHeader, HistoryOptions, MetadataEvent, WatchFilter } from '@objectstack/metadata-core';
+import { ObjectStackProtocol, MetadataCacheRequest, MetadataCacheResponse, BatchUpdateRequest, BatchUpdateResponse, UpdateManyDataRequest, DeleteManyDataRequest, InstallPackageRequest, InstallPackageResponse } from '@objectstack/spec/api';
+import { IDataEngine } from '@objectstack/core';
+import { IFeedService, ISeedLoaderService, IDataEngine as IDataEngine$1, IMetadataService } from '@objectstack/spec/contracts';
+import { MetadataValidationResult, MetadataLock, MetadataProvenance } from '@objectstack/spec/kernel';
+import { SeedLoaderRequest, SeedLoaderResult, ObjectDependencyGraph, Seed, SeedLoaderConfigInput } from '@objectstack/spec/data';
+
+/** One runtime-verification finding (ADR-0038 BuildIssue, layer 'runtime'). */
+interface RuntimeBuildIssue {
+    layer: 'runtime';
+    severity: 'error' | 'warning';
+    /** The artifact whose runtime behaviour is broken. */
+    artifact: {
+        type: string;
+        name: string;
+    };
+    /** What it exercised, when narrower than the artifact (e.g. a widget). */
+    ref?: {
+        type: string;
+        name: string;
+        member?: string;
+    };
+    /** 'seed_not_applied' | 'view_read_failed' | 'empty_query' | 'widget_query_failed' | 'probes_unavailable' */
+    code: string;
+    message: string;
+    fix?: string;
+}
+/** Aggregate result of one post-publish probe pass. */
+interface BuildProbeReport {
+    /** Findings, empty when every probe passed. */
+    issues: RuntimeBuildIssue[];
+    /** How many probes actually ran, per plane (0s mean nothing to probe). */
+    checked: {
+        seeds: number;
+        views: number;
+        widgets: number;
+    };
+}
+/** The single read the probes need from the data engine. */
+interface ProbeEngine {
+    find(objectName: string, query: unknown): Promise<Array<Record<string, unknown>>>;
+}
+/** Optional analytics surface — when absent, widget probes degrade to a warning. */
+interface ProbeAnalytics {
+    queryDataset(dataset: unknown, selection: unknown, context?: unknown): Promise<unknown>;
+}
+interface RunBuildProbesOptions {
+    engine: ProbeEngine;
+    /** Read an ACTIVE (published) item body by type+name; undefined when absent. */
+    getItem: (type: string, name: string) => Promise<unknown | undefined>;
+    /** The just-published artifact set (publishPackageDrafts' `published`). */
+    published: Array<{
+        type: string;
+        name: string;
+    }>;
+    /**
+     * The kernel's analytics service, when one is mounted. Widget probes run
+     * the SAME `queryDataset` path the dashboard renderer hits — absent
+     * service means widgets can't be probed (one aggregate warning, not
+     * per-widget noise).
+     */
+    analytics?: ProbeAnalytics;
+    /** Threaded into engine/analytics reads (tenant scoping). */
+    organizationId?: string | null;
+}
+/**
+ * Run the L3 runtime probes over a just-published artifact set:
+ *
+ *  • per published `seed` — its target object must have rows now
+ *    (`seed_not_applied`: the rows were promised but never materialized);
+ *  • per published `view` — a limit-1 read through the same engine the
+ *    renderer uses must not throw (`view_read_failed`);
+ *  • per published `dashboard` widget — its real dataset selection must
+ *    execute (`widget_query_failed`) and must not return empty on an object
+ *    that HAS rows (`empty_query` — the four-layer staging incident class).
+ *
+ * All probes are reads (limit-1 / single aggregate); a probe crash is
+ * reported, never thrown — verification must not break the publish it
+ * verifies.
+ */
+declare function runBuildProbes(opts: RunBuildProbesOptions): Promise<BuildProbeReport>;
+
+/**
+ * Re-export the canonical validation-result type so callers in this
+ * package don't need to dual-import from `@objectstack/spec/kernel`.
+ */
+type MetadataDiagnostics = MetadataValidationResult;
+/**
+ * Compute spec diagnostics for a single metadata document.
+ *
+ * Returns `undefined` when the type has no registered Zod schema
+ * (`function` / `service` / `router`, or any plugin type that has not
+ * called `registerMetadataTypeSchema()`). Callers MUST treat that as
+ * "no opinion" — not as "valid" — and either skip decoration entirely
+ * or surface a `validatable: false` flag if their UI cares.
+ */
+declare function computeMetadataDiagnostics(type: string, item: unknown): MetadataDiagnostics | undefined;
+/**
+ * Attach `_diagnostics` to a single metadata item. Returns the item
+ * unchanged when no diagnostics could be computed (unknown type) or
+ * when the input is not an object.
+ *
+ * The returned reference is always a shallow copy when decoration
+ * occurs — callers must not assume identity equality with the input.
+ */
+declare function decorateMetadataItem<T>(type: string, item: T): T;
+/**
+ * Decorate an array of metadata items. Non-array inputs and non-object
+ * elements are returned unchanged, preserving the upstream defensive
+ * "items may be a wrapped or naked array" contract documented in
+ * `rest-server.ts`.
+ */
+declare function decorateMetadataItems<T>(type: string, items: T[]): T[];
+/** Minimal object-definition shape the reference checker needs. */
+interface ObjectDefLike {
+    fields?: Record<string, {
+        type?: string;
+    }> | Array<{
+        name: string;
+        type?: string;
+    }>;
+}
+/**
+ * Cross-document reference checks Zod cannot express: every field a list
+ * view's user-facing filter surface points at must exist on the source
+ * object, and binding-dependent visualizations must have resolvable
+ * bindings (kanban → select-like `groupByField`).
+ *
+ * Pure function — callers (read decoration, the ADR-0033 AI apply loop)
+ * supply the already-resolved object definition. Returns `{ valid: true }`
+ * when every reference resolves; errors use the same wire shape as
+ * {@link computeMetadataDiagnostics} so consumers can merge the two.
+ *
+ * Spec-shape validation stays in `computeMetadataDiagnostics`; this only
+ * covers what a schema alone cannot see.
+ */
+declare function computeViewReferenceDiagnostics(view: Record<string, unknown>, objectDef: ObjectDefLike): MetadataDiagnostics;
+
+/**
+ * Guarantee a `view` body carries a top-level `name`.
+ *
+ * {@link ObjectStackProtocolImplementation.getMetaItems} only surfaces a
+ * sys_metadata overlay row when its parsed body has a top-level `name` (objects
+ * and dashboards include one; some view producers — notably loose `{ list }`
+ * fragments — do not, so the view is silently dropped from the object's view
+ * list and never appears as a tab). We stamp the save name here, at the single
+ * write chokepoint, without otherwise reshaping the document.
+ *
+ * Deliberately does NOT convert shape: both the `defineView` container form
+ * (`{ list, listViews, … }`) and the `{ name, object, viewKind, config }`
+ * record form are valid and the console consumes both — reshaping a container
+ * into a record risks producing an invalid record (e.g. a non-`<object>.<key>`
+ * name). Structural validity is enforced separately by the view metadata schema
+ * during the spec-validation step. No-op for non-view types and bodies that
+ * already carry a `name`.
+ */
+declare function normalizeViewMetadata(type: string, item: unknown, saveName: string): unknown;
+/**
+ * Thrown by `updateData` / `deleteData` when the caller supplies an
+ * `expectedVersion` that does not match the current record's `updated_at`.
+ *
+ * The HTTP layer maps this to `409 Conflict` with code `CONCURRENT_UPDATE`,
+ * and includes both the current server-side version and the current record
+ * payload so the client can render an informed conflict-resolution UI
+ * ("Reload latest" vs. "Overwrite anyway").
+ *
+ * NOTE: This is an *application-level* compare-and-set — not an atomic
+ * storage-layer CAS. There is a small TOCTOU window between the version
+ * check and the subsequent write. For the conflict frequency this targets
+ * (different users seconds-to-minutes apart in B2B record editing) this
+ * is more than adequate; a future revision can push the check into the
+ * driver's UPDATE statement (`WHERE id=? AND updated_at=?`) for true
+ * atomicity.
+ */
+declare class ConcurrentUpdateError extends Error {
+    readonly code = "CONCURRENT_UPDATE";
+    readonly status = 409;
+    readonly currentVersion: string | null;
+    readonly currentRecord: unknown;
+    constructor(opts: {
+        currentVersion: string | null;
+        currentRecord: unknown;
+        message?: string;
+    });
+}
+declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
+    private engine;
+    private getServicesRegistry?;
+    private getFeedService?;
+    /**
+     * Project scope applied to sys_metadata reads/writes. When undefined
+     * (single-kernel deployments), rows land in / come from the
+     * platform-global bucket (`environment_id IS NULL`). When set, every
+     * saveMetaItem insert/update and loadMetaFromDb query is filtered by
+     * `environment_id = environmentId`, so per-project kernels see only their own
+     * metadata even if several projects share the same physical database.
+     */
+    private environmentId?;
+    /**
+     * Lazily-instantiated SysMetadataRepository per organization. Keyed by
+     * `${organizationId ?? '__env__'}`. Repositories are stateful — they
+     * carry the per-org `seqCounter` and watch subscribers — so we cache
+     * them rather than constructing one per call.
+     */
+    private overlayRepos;
+    constructor(engine: IDataEngine, getServicesRegistry?: () => Map<string, any>, getFeedService?: () => IFeedService | undefined, environmentId?: string);
+    /**
+     * Lazily obtain a SysMetadataRepository for the given organization.
+     * Env-wide overlays (organizationId == null) share a singleton under
+     * the `__env__` key.
+     */
+    private getOverlayRepo;
+    /**
+     * One-time guard for ensuring the overlay-uniqueness UNIQUE INDEX exists
+     * on `sys_metadata`. ADR-0005: scopes overlays by
+     * `(type, name, organization_id, environment_id, scope)` for active rows only.
+     * Idempotent SQL — safe to attempt on every protocol instance.
+     *
+     * Inlined here (rather than importing from @objectstack/metadata/migrations)
+     * to avoid a circular dependency: metadata already depends on objectql.
+     */
+    private overlayIndexEnsured;
+    private ensureOverlayIndex;
+    /**
+     * Exposes the project scope the protocol is bound to. Consumers like
+     * the HTTP dispatcher use this to decide whether to trust the process-
+     * wide SchemaRegistry or whether they must route a read through the
+     * protocol's environment_id-filtered lookup.
+     */
+    getProjectId(): string | undefined;
+    private requireFeedService;
+    getDiscovery(): Promise<{
+        version: string;
+        apiName: string;
+        routes: {
+            data: string;
+            metadata: string;
+            discovery?: string | undefined;
+            ui?: string | undefined;
+            auth?: string | undefined;
+            automation?: string | undefined;
+            storage?: string | undefined;
+            analytics?: string | undefined;
+            graphql?: string | undefined;
+            packages?: string | undefined;
+            workflow?: string | undefined;
+            approvals?: string | undefined;
+            realtime?: string | undefined;
+            notifications?: string | undefined;
+            ai?: string | undefined;
+            i18n?: string | undefined;
+            feed?: string | undefined;
+        };
+        services: Record<string, {
+            enabled: boolean;
+            status: "available" | "registered" | "unavailable" | "degraded" | "stub";
+            handlerReady?: boolean | undefined;
+            route?: string | undefined;
+            provider?: string | undefined;
+            version?: string | undefined;
+            message?: string | undefined;
+            rateLimit?: {
+                requestsPerMinute?: number | undefined;
+                requestsPerHour?: number | undefined;
+                burstLimit?: number | undefined;
+                retryAfterMs?: number | undefined;
+            } | undefined;
+        }>;
+        capabilities: Record<string, {
+            enabled: boolean;
+            description?: string;
+        }>;
+    }>;
+    getMetaTypes(): Promise<{
+        types: any[];
+        entries: {
+            actions?: {
+                name: string;
+                label: string;
+                type: "url" | "flow" | "script" | "api" | "form" | "modal";
+                refreshAfter: boolean;
+                objectName?: string | undefined;
+                icon?: string | undefined;
+                locations?: ("list_toolbar" | "list_item" | "record_header" | "record_more" | "record_related" | "record_section" | "global_nav")[] | undefined;
+                component?: "action:button" | "action:icon" | "action:menu" | "action:group" | undefined;
+                target?: string | undefined;
+                openIn?: "self" | "new-tab" | undefined;
+                body?: {
+                    language: "expression";
+                    source: string;
+                } | {
+                    language: "js";
+                    source: string;
+                    capabilities: ("log" | "api.read" | "api.write" | "api.transaction" | "crypto.uuid" | "crypto.hash")[];
+                    timeoutMs?: number | undefined;
+                    memoryMb?: number | undefined;
+                } | undefined;
+                execute?: string | undefined;
+                params?: {
+                    required: boolean;
+                    name?: string | undefined;
+                    field?: string | undefined;
+                    objectOverride?: string | undefined;
+                    label?: string | undefined;
+                    type?: "number" | "boolean" | "date" | "record" | "file" | "code" | "json" | "url" | "summary" | "datetime" | "color" | "time" | "text" | "textarea" | "email" | "phone" | "password" | "secret" | "markdown" | "html" | "richtext" | "currency" | "percent" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "user" | "image" | "avatar" | "video" | "audio" | "formula" | "autonumber" | "composite" | "repeater" | "location" | "address" | "rating" | "slider" | "signature" | "qrcode" | "progress" | "tags" | "vector" | undefined;
+                    options?: {
+                        label: string;
+                        value: string;
+                    }[] | undefined;
+                    placeholder?: string | undefined;
+                    helpText?: string | undefined;
+                    defaultValue?: unknown;
+                    defaultFromRow?: boolean | undefined;
+                }[] | undefined;
+                variant?: "link" | "primary" | "secondary" | "danger" | "ghost" | undefined;
+                confirmText?: string | undefined;
+                successMessage?: string | undefined;
+                errorMessage?: string | undefined;
+                undoable?: boolean | undefined;
+                resultDialog?: {
+                    title?: string | undefined;
+                    description?: string | undefined;
+                    acknowledge?: string | undefined;
+                    format?: "json" | "text" | "secret" | "qrcode" | "code-list" | undefined;
+                    fields?: {
+                        path: string;
+                        label?: string | undefined;
+                        format?: "json" | "text" | "secret" | "qrcode" | "code-list" | undefined;
+                    }[] | undefined;
+                } | undefined;
+                visible?: {
+                    dialect: "cron" | "cel" | "js" | "template";
+                    source?: string | undefined;
+                    ast?: unknown;
+                    meta?: {
+                        rationale?: string | undefined;
+                        generatedBy?: string | undefined;
+                    } | undefined;
+                } | undefined;
+                disabled?: boolean | {
+                    dialect: "cron" | "cel" | "js" | "template";
+                    source?: string | undefined;
+                    ast?: unknown;
+                    meta?: {
+                        rationale?: string | undefined;
+                        generatedBy?: string | undefined;
+                    } | undefined;
+                } | undefined;
+                requiredPermissions?: string[] | undefined;
+                shortcut?: string | undefined;
+                bulkEnabled?: boolean | undefined;
+                ai?: {
+                    exposed: boolean;
+                    description
+                    /**
+                     * Simple hash function for ETag generation (browser-compatible)
+                     * Uses a basic hash algorithm instead of crypto.createHash
+                     */
+                    ?: string | undefined;
+                    category?: "data" | "flow" | "analytics" | "action" | "integration" | "vector_search" | "utility" | undefined;
+                    paramHints?: Record<string, {
+                        description?: string | undefined;
+                        enum?: (string | number)[] | undefined;
+                        examples?: unknown[] | undefined;
+                    }> | undefined;
+                    outputSchema?: Record<string, unknown> | undefined;
+                    requiresConfirmation?: boolean | undefined;
+                } | undefined;
+                recordIdParam?: string | undefined;
+                recordIdField?: string | undefined;
+                bodyShape?: "flat" | {
+                    wrap: string;
+                } | undefined;
+                method?: "POST" | "PUT" | "DELETE" | "PATCH" | undefined;
+                bodyExtra?: Record<string, unknown> | undefined;
+                mode?: "custom" | "create" | "delete" | "edit" | undefined;
+                opensInNewTab?: boolean | undefined;
+                newTabUrl?: string | undefined;
+                timeout?: number | undefined;
+                aria?: {
+                    ariaLabel?: string | undefined;
+                    ariaDescribedBy?: string | undefined;
+                    role?: string | undefined;
+                } | undefined;
+            }[] | undefined;
+            createSeed?: {} | null | undefined;
+            type: string;
+            schemaId: string;
+            allowOrgOverride: boolean;
+            overrideSource: "registry" | "env";
+            schema: Record<string, unknown>;
+            form: {
+                type: "modal" | "split" | "drawer" | "simple" | "tabbed" | "wizard";
+                data?: {
+                    provider: "object";
+                    object: string;
+                } | {
+                    provider: "api";
+                    read?: {
+                        url: string;
+                        method: "POST" | "PUT" | "DELETE" | "PATCH" | "GET";
+                        headers?: Record<string, string> | undefined;
+                        params?: Record<string, unknown> | undefined;
+                        body?: unknown;
+                    } | undefined;
+                    write?: {
+                        url: string;
+                        method: "POST" | "PUT" | "DELETE" | "PATCH" | "GET";
+                        headers?: Record<string, string> | undefined;
+                        params?: Record<string, unknown> | undefined;
+                        body?: unknown;
+                    } | undefined;
+                } | {
+                    provider: "value";
+                    items: unknown[];
+                } | {
+                    provider: "schema";
+                    schemaId: string;
+                    schema?: Record<string, unknown> | undefined;
+                } | undefined;
+                sections?: {
+                    collapsible: boolean;
+                    collapsed: boolean;
+                    columns: 2 | 1 | 4 | 3;
+                    fields: any[];
+                    name?: string | undefined;
+                    label?: string | undefined;
+                    description?: string | undefined;
+                    visibleOn?: {
+                        dialect: "cel" | "js" | "cron" | "template";
+                        source?: string | undefined;
+                        ast?: unknown;
+                        meta?: {
+                            rationale?: string | undefined;
+                            generatedBy?: string | undefined;
+                        } | undefined;
+                    } | {
+                        dialect: "js" | "cron" | "cel" | "template";
+                        source?: string | undefined;
+                        ast?: unknown;
+                        meta?: {
+                            rationale?: string | undefined;
+                            generatedBy?: string | undefined;
+                        } | undefined;
+                    } | undefined;
+                }[] | undefined;
+                groups?: {
+                    collapsible: boolean;
+                    collapsed: boolean;
+                    columns: 2 | 1 | 4 | 3;
+                    fields: any[];
+                    name?: string | undefined;
+                    label?: string | undefined;
+                    description?: string | undefined;
+                    visibleOn?: {
+                        dialect: "cel" | "js" | "cron" | "template";
+                        source?: string | undefined;
+                        ast?: unknown;
+                        meta?: {
+                            rationale?: string | undefined;
+                            generatedBy?: string | undefined;
+                        } | undefined;
+                    } | {
+                        dialect: "js" | "cron" | "cel" | "template";
+                        source?: string | undefined;
+                        ast?: unknown;
+                        meta?: {
+                            rationale?: string | undefined;
+                            generatedBy?: string | undefined;
+                        } | undefined;
+                    } | undefined;
+                }[] | undefined;
+                subforms?: {
+                    childObject: string;
+                    relationshipField?: string | undefined;
+                    columns?: any[] | undefined;
+                    amountField?: string | undefined;
+                    totalField?: string | undefined;
+                    title?: string | undefined;
+                    addLabel?: string | undefined;
+                    minRows?: number | undefined;
+                    maxRows?: number | undefined;
+                }[] | undefined;
+                defaultSort?: {
+                    field: string;
+                    order: "asc" | "desc";
+                }[] | undefined;
+                sharing?: {
+                    enabled: boolean;
+                    allowAnonymous: boolean;
+                    publicLink?: string | undefined;
+                    password?: string | undefined;
+                    allowedDomains?: string[] | undefined;
+                    expiresAt?: string | undefined;
+                } | undefined;
+                submitBehavior?: {
+                    kind: "thank-you";
+                    title?: string | undefined;
+                    message?: string | undefined;
+                } | {
+                    kind: "redirect";
+                    url: string;
+                    delayMs?: number | undefined;
+                } | {
+                    kind: "continue";
+                } | {
+                    kind: "next-record";
+                } | undefined;
+                aria?: {
+                    ariaLabel?: string | undefined;
+                    ariaDescribedBy?: string | undefined;
+                    role?: string | undefined;
+                } | undefined;
+            };
+            label: string;
+            filePatterns: string[];
+            supportsOverlay: boolean;
+            allowRuntimeCreate: boolean;
+            supportsVersioning: boolean;
+            executionPinned: boolean;
+            loadOrder: number;
+            domain: "data" | "ui" | "automation" | "ai" | "system" | "security";
+            description?: string | undefined;
+        }[];
+    }>;
+    /**
+     * Sweep all (or filtered) metadata types and report entries that
+     * fail spec validation. Powers the Studio governance view
+     * (`GET /api/v1/meta/diagnostics`) and `os doctor`-style CLI
+     * checks.
+     *
+     * `severity` defaults to `'error'` — only entries with at least
+     * one Zod error issue are returned. `'warning'` includes
+     * everything we surface (warnings are reserved for a future lint
+     * layer on top of spec validation).
+     *
+     * `type` may be either a singular (`'view'`) or plural (`'views'`)
+     * identifier; the underlying `getMetaItems` already normalises.
+     *
+     * Implementation note: leverages the `_diagnostics` already
+     * decorated onto items by `getMetaItems()` to avoid running
+     * `safeParse()` twice. For types whose schema is unregistered we
+     * skip silently (they cannot be validated and should not appear
+     * as "valid" either — they are simply opaque to this report).
+     */
+    getMetaDiagnostics(request?: {
+        type?: string;
+        severity?: 'error' | 'warning';
+        organizationId?: string;
+        packageId?: string;
+    }): Promise<{
+        entries: Array<{
+            type: string;
+            name: string;
+            diagnostics: MetadataDiagnostics;
+        }>;
+        total: number;
+        scannedTypes: number;
+        scannedItems: number;
+        /**
+         * Per-type aggregate stats — count of items and the list of
+         * packages contributing to each type. Computed in the same
+         * sweep so the Studio directory page can render tile counts
+         * and a package filter in one round-trip.
+         */
+        stats: Record<string, {
+            count: number;
+            locked: number;
+            packages: string[];
+        }>;
+    }>;
+    getMetaItems(request: {
+        type: string;
+        packageId?: string;
+        organizationId?: string;
+        previewDrafts?: boolean;
+    }): Promise<{
+        type: string;
+        items: any[];
+    }>;
+    getMetaItem(request: {
+        type: string;
+        name: string;
+        packageId?: string;
+        organizationId?: string;
+        state?: 'active' | 'draft';
+        previewDrafts?: boolean;
+    }): Promise<{
+        type: string;
+        name: string;
+        item: any;
+    } | {
+        editable: boolean;
+        deletable: boolean;
+        resettable: boolean;
+        packageVersion?: string | undefined;
+        packageId?: string | undefined;
+        provenance?: "org" | "package" | "env-forced" | undefined;
+        lockDocsUrl?: string | undefined;
+        lockSource?: "package" | "artifact" | "env-forced" | undefined;
+        lockReason?: string | undefined;
+        type: string;
+        name: string;
+        item: unknown;
+        lock: "full" | "none" | "no-overlay" | "no-delete";
+    }>;
+    /**
+     * Phase 3a-layered-get: return the 3 layers of a metadata item
+     * separately — `code` (artifact-loaded baseline), `overlay` (per-org
+     * customisation row, if any), and `effective` (what `getMetaItem`
+     * would return, i.e. overlay-wins merge).
+     *
+     * Drives the "Code default vs Overlay vs Effective" diff tab in the
+     * generic Metadata Resource Edit page. Admins can see exactly what
+     * was customised and reset selectively.
+     *
+     * `code` is null if no artifact baseline exists; `overlay` is null if
+     * no sys_metadata row exists for the requested scope; `effective` is
+     * never null when either layer exists.
+     */
+    getMetaItemLayered(request: {
+        type: string;
+        name: string;
+        packageId?: string;
+        organizationId?: string;
+    }): Promise<{
+        type: string;
+        name: string;
+        code: unknown | null;
+        overlay: unknown | null;
+        overlayScope: 'org' | 'env' | null;
+        effective: unknown | null;
+        /**
+         * Load-time validation result for the effective payload — same
+         * shape attached to getMetaItems/getMetaItem by
+         * decorateMetadataItem. Undefined for types without a registered
+         * Zod schema (function/service/router). Lets the Studio edit
+         * page surface invalid-metadata banners + inline field errors
+         * without a second round-trip.
+         */
+        _diagnostics?: MetadataDiagnostics;
+        lock: MetadataLock;
+        lockReason?: string;
+        lockSource?: 'artifact' | 'package' | 'env-forced' | 'overlay';
+        lockDocsUrl?: string;
+        provenance?: MetadataProvenance;
+        packageId?: string;
+        packageVersion?: string;
+        editable: boolean;
+        deletable: boolean;
+        resettable: boolean;
+    }>;
+    /**
+     * ADR-0010 §3.6 / Phase 4.1 — read the metadata-protection audit log
+     * for a single item. Returns the most-recent rows of
+     * `sys_metadata_audit` for this (type, name) tuple, sorted newest
+     * first. Refused (`denied`) and forced (`forced`) writes both appear
+     * here — they never reach the `history` endpoint, which only tracks
+     * successful body snapshots.
+     *
+     * The table is provisioned by `platform-objects` and is the
+     * compliance surface for the lock-enforcement story. When the
+     * environment has not yet provisioned the table (legacy install
+     * prior to ADR-0010) the call returns `{ events: [] }` instead of
+     * raising, keeping the Studio tab harmless.
+     */
+    auditMetaItem(request: {
+        type: string;
+        name: string;
+        organizationId?: string | null;
+        limit?: number;
+    }): Promise<{
+        events: Array<{
+            id: unknown;
+            occurredAt: string;
+            actor: string;
+            source: string | null;
+            operation: 'save' | 'publish' | 'rollback' | 'delete' | 'reset';
+            outcome: 'allowed' | 'denied' | 'forced';
+            code: string;
+            lockState: MetadataLock | null;
+            lockOverridden: boolean;
+            requestId: string | null;
+            note: string | null;
+        }>;
+    }>;
+    getUiView(request: {
+        object: string;
+        type: 'list' | 'form';
+    }): Promise<{
+        list: {
+            type: "grid";
+            object: string;
+            label: any;
+            columns: {
+                field: string;
+                label: any;
+                sortable: boolean;
+            }[];
+            sort: any;
+            searchableFields: string[];
+        };
+        form?: undefined;
+    } | {
+        form: {
+            type: "simple";
+            object: string;
+            label: string;
+            sections: {
+                label: string;
+                columns: 2;
+                collapsible: boolean;
+                collapsed: boolean;
+                fields: {
+                    field: string;
+                    label: any;
+                    required: any;
+                    readonly: any;
+                    type: any;
+                    colSpan: number;
+                }[];
+            }[];
+        };
+        list?: undefined;
+    }>;
+    findData(request: {
+        object: string;
+        query?: any;
+        context?: any;
+    }): Promise<{
+        object: string;
+        records: any[];
+        total: number;
+        hasMore: boolean;
+    }>;
+    getData(request: {
+        object: string;
+        id: string;
+        expand?: string | string[];
+        select?: string | string[];
+        context?: any;
+    }): Promise<{
+        object: string;
+        id: string;
+        record: any;
+    }>;
+    createData(request: {
+        object: string;
+        data: any;
+        context?: any;
+    }): Promise<{
+        object: string;
+        id: any;
+        record: any;
+    }>;
+    /**
+     * Clone a record — read the source, drop engine-owned columns, and
+     * insert a fresh copy. Gated by the object's `enable.clone` capability
+     * (default `true`; only an explicit `enable.clone === false` disables it).
+     *
+     * Shallow by design: it duplicates the record's own scalar/business field
+     * values, not its related child records. The insert path re-stamps audit
+     * columns, regenerates `autonumber` fields, and recomputes derived
+     * (`formula`/`summary`) fields, so the copy is a valid new row rather than
+     * a byte-identical twin. Caller-supplied `overrides` are applied last and
+     * win over the copied values — the natural place to set a new `name`,
+     * clear a unique field, or reset status before insert.
+     */
+    cloneData(request: {
+        object: string;
+        id: string;
+        overrides?: Record<string, any>;
+        context?: any;
+    }): Promise<{
+        object: string;
+        id: any;
+        sourceId: string;
+        record: any;
+    }>;
+    updateData(request: {
+        object: string;
+        id: string;
+        data: any;
+        expectedVersion?: string;
+        context?: any;
+    }): Promise<{
+        object: string;
+        id: string;
+        record: any;
+    }>;
+    deleteData(request: {
+        object: string;
+        id: string;
+        expectedVersion?: string;
+        context?: any;
+    }): Promise<{
+        object: string;
+        id: string;
+        success: boolean;
+    }>;
+    /**
+     * Optimistic Concurrency Control gate shared by updateData/deleteData.
+     *
+     * When the caller passes a non-empty `expectedVersion` token (typically
+     * the `updated_at` value they read), this fetches the current record
+     * and compares its `updated_at` against the token. Mismatch → throw
+     * `ConcurrentUpdateError` which the REST layer maps to 409.
+     *
+     * Behaviour:
+     *  - Empty/missing token → no check (opt-in semantics; existing callers
+     *    that haven't yet adopted OCC are unaffected).
+     *  - Record not found → no check; downstream `engine.update` will
+     *    surface the usual `RECORD_NOT_FOUND` 404. We intentionally do not
+     *    treat "missing record" as a concurrency conflict.
+     *  - Record has no `updated_at` field (timestamps disabled) → no check.
+     *    Logging would be noisy here; OCC is opt-in and the absence of a
+     *    version column is an explicit "this object doesn't support OCC"
+     *    signal.
+     */
+    private assertVersionMatch;
+    /**
+     * Cross-object substring search across all registered objects that opt in
+     * via `enable.searchable !== false` and `enable.apiEnabled !== false`.
+     * Searches text-like fields (text/textarea/email/url/phone/markdown/html/string)
+     * whose `searchable: true` flag is set, falling back to the object's
+     * `displayNameField` (or `name`) when no fields are explicitly searchable.
+     *
+     * The query is split into whitespace-separated terms; each term must match
+     * (case-insensitive LIKE) at least one searchable field. RBAC/RLS is
+     * enforced by forwarding the caller's `context` to `engine.find` so users
+     * only see records they are entitled to read.
+     */
+    searchAll(request: {
+        q: string;
+        objects?: string[];
+        limit?: number;
+        perObject?: number;
+        context?: any;
+    }): Promise<{
+        query: string;
+        hits: Array<{
+            object: string;
+            id: string;
+            title: string;
+            snippet?: string;
+            record: any;
+        }>;
+        totalObjects: number;
+        totalHits: number;
+        truncated: boolean;
+    }>;
+    getMetaItemCached(request: {
+        type: string;
+        name: string;
+        cacheRequest?: MetadataCacheRequest;
+        locale?: string;
+    }): Promise<MetadataCacheResponse>;
+    batchData(request: {
+        object: string;
+        request: BatchUpdateRequest;
+    }): Promise<BatchUpdateResponse>;
+    createManyData(request: {
+        object: string;
+        records: any[];
+    }): Promise<any>;
+    updateManyData(request: UpdateManyDataRequest): Promise<BatchUpdateResponse>;
+    analyticsQuery(request: any): Promise<any>;
+    getAnalyticsMeta(request: any): Promise<any>;
+    private mapAnalyticsOperator;
+    triggerAutomation(_request: any): Promise<any>;
+    deleteManyData(request: DeleteManyDataRequest): Promise<any>;
+    /**
+     * Metadata types that are customer-overridable via {@link saveMetaItem}/
+     * {@link deleteMetaItem} in project-kernel mode. Derived from the canonical
+     * registry in {@link DEFAULT_METADATA_TYPE_REGISTRY}: a type opts in by
+     * setting `allowOrgOverride: true` on its registry entry. The set is
+     * augmented with the plural form of every singular so callers using REST
+     * conventions (`/api/v1/meta/views/...`) get the same gate. See ADR-0005
+     * §"Whitelist enforcement" for the rationale and the per-type rollout
+     * checklist.
+     */
+    private static readonly OVERLAY_ALLOWED_TYPES;
+    /**
+     * Phase 3a-env-writable: parse `OS_METADATA_WRITABLE` once.
+     * Comma-separated singular type names. When the env var is set, the
+     * listed types get treated as `allowOrgOverride: true` regardless of
+     * their static registry entry. This is the runtime escape hatch admins
+     * use to enable Studio-side editing of types whose protocol-level flag
+     * is still false (object, field, permission, …).
+     *
+     * Memoised at first call. Tests can override by clearing the cache via
+     * {@link ObjectStackProtocolImplementation.resetEnvWritableCache}.
+     */
+    private static _envWritableTypes;
+    private static envWritableTypes;
+    /** Test hook — clear the memoised env-writable cache. */
+    static resetEnvWritableCache(): void;
+    /**
+     * Types that opt into runtime creation of brand-new items (ADR-0005
+     * extension — two-tier model). A type may have
+     * `allowOrgOverride: false` (cannot overlay artifact-shipped items)
+     * yet still set `allowRuntimeCreate: true` (users can author new
+     * items in `sys_metadata`). The two flags are orthogonal; see
+     * {@link isArtifactBacked} for how the protocol decides which gate
+     * applies to a given save/delete.
+     */
+    /**
+     * Set of type names that have a static entry in
+     * `DEFAULT_METADATA_TYPE_REGISTRY`. Anything outside this set is
+     * runtime-registered (plugin-provided types like `theme`, `api`,
+     * `connector`) — the listing endpoint at `getMetaTypes()` synthesises
+     * those with `allowRuntimeCreate: true`, so this gate must agree.
+     */
+    private static readonly STATIC_REGISTRY_TYPES;
+    private static readonly RUNTIME_CREATE_ALLOWED_TYPES;
+    /** Normalize plural→singular before consulting the allow-list. */
+    private static isOverlayAllowed;
+    /** Does this type permit creating brand-new (artifact-free) items? */
+    private static isRuntimeCreateAllowed;
+    /**
+     * Does an artifact (npm-package-loaded) item exist at `(type, name)`?
+     *
+     * The schema registry's `_packageId` tag is set only when
+     * `registerItem(..., packageId)` is called with a truthy packageId
+     * — and only artifact loaders do that. DB-rehydrated items
+     * (sys_metadata rows registered back into the registry by
+     * `getMetaItems` / `loadMetaFromDb`) call `registerItem` without a
+     * packageId, so they carry no `_packageId` and are correctly
+     * excluded here.
+     *
+     * Used by the two-tier authorization model to distinguish
+     * "overlaying a packaged item" (requires `allowOrgOverride`) from
+     * "authoring a DB-only item" (requires only `allowRuntimeCreate`).
+     */
+    private isArtifactBacked;
+    /**
+     * Look up an item from the artifact registry across both the requested
+     * type and its singular/plural twin. Returns `undefined` when the
+     * registry is unavailable or the item is not artifact-backed.
+     */
+    private lookupArtifactItem;
+    /**
+     * True when `packageId` is a **writable base** — a DB-backed package an
+     * org or the AI may author *new* metadata into (ADR-0070 D2). The two
+     * read-only kinds return `false`:
+     *
+     *   • **Booted code packages** — they register a manifest into the engine
+     *     at startup (`registerApp` → `engine.manifests`); their items are
+     *     code-shipped artifacts. Only `allowOrgOverride` overlays are allowed
+     *     (ADR-0005), never fresh authored items.
+     *   • **Installed / platform packages** — manifest `scope` is `system` or
+     *     `cloud` (marketplace / platform-delivered).
+     *
+     * A project-scoped DB package, or a bare ADR-0048 *authoring-workspace* id
+     * with no registered manifest, is writable.
+     *
+     * NOTE: the code-package signal is the engine manifest map ONLY — we
+     * deliberately do NOT fall back to "owns ≥1 registered object" (the old
+     * `isLoadedPackage` heuristic). A writable base accrues registered objects
+     * once its drafts publish, and that must never flip the base to read-only
+     * — that is the exact #2252 read-only-after-publish trap this ADR removes.
+     */
+    private isWritablePackage;
+    /**
+     * Resolve the effective `_lock` for an item by consulting the
+     * artifact registry first, then the persisted overlay row. Artifact
+     * always wins — by design, an overlay cannot loosen a packaged
+     * lock (ADR-0010 §3.3).
+     *
+     * Returns `'none'` when nothing is locked, which is the common
+     * case. Safe to call when `environmentId` is undefined (control-
+     * plane bootstrap) — the lock check is only meaningful in tenant
+     * scope and the caller is expected to also gate on `environmentId`.
+     */
+    private getEffectiveLock;
+    /**
+     * Best-effort audit-row writer (ADR-0010 §3.6). Failures here are
+     * logged but never block the underlying decision: an environment
+     * without the audit table provisioned (legacy installs before this
+     * ADR landed) still answers normal API calls, just without the
+     * compliance trail. Phase 2 will make the audit table a hard
+     * dependency.
+     */
+    private recordMetadataAudit;
+    /**
+     * Phase 1 L3 enforcement for write operations (save / publish /
+     * rollback). Returns null on allow. Returns the structured `Error`
+     * the caller should `throw` on deny — also records the denial in
+     * the audit log so refused attempts are visible in compliance
+     * reports (refused writes never reach sys_metadata_history).
+     */
+    private assertLockAllowsWrite;
+    /** Counterpart of {@link assertLockAllowsWrite} for delete. */
+    private assertLockAllowsDelete;
+    /**
+     * Mirror an object-type overlay write into the in-memory engine
+     * registry so subsequent CRUD finds the new schema. Idempotent and
+     * safe to call after a successful persistence call. For the legacy
+     * write path this is invoked BEFORE persistence (historical behavior
+     * preserved); for the PR-10d.3 repository path it is invoked only
+     * AFTER `put()` resolves successfully, so a failed write — DB error,
+     * optimistic-lock conflict, validation failure — never leaks a
+     * stale schema into the registry.
+     */
+    private applyObjectRegistryMutation;
+    /**
+     * Heal the in-memory registry after a metadata reset (overlay-row
+     * delete) on control-plane kernels. Two layers:
+     *
+     *  1. Drop the plain-key runtime shadow so the packaged artifact
+     *     (registered under `<packageId>:<name>`) becomes the visible
+     *     value again. The shadow is written by the overlay-hydration
+     *     paths (`getMetaItems` / `loadMetaFromDb`) and — pre-fix —
+     *     survived the reset until restart, leaving stale overlay
+     *     content (and a stripped `_lock` envelope) in every
+     *     registry-direct read (ADR-0010 §3.3).
+     *  2. When no composite-key artifact exists, fall back to the
+     *     MetadataService baseline (FilesystemLoader-sourced types) and
+     *     re-register it, preserving the historical refresh behaviour
+     *     for items the SchemaRegistry never held as artifacts.
+     *
+     * Best-effort: a failure must never block the delete that already
+     * succeeded; the next full reload fixes the registry anyway.
+     */
+    private restoreArtifactRegistryView;
+    /**
+     * Ensure a just-PUBLISHED object's physical table exists so it is usable
+     * for data CRUD immediately — without a server restart. Registering the
+     * object (above) only updates the in-memory registry; the table is created
+     * by the driver's schema sync, which otherwise only runs at boot. Without
+     * this, inserting into a freshly-published object fails with "no such
+     * table" (surfaced as `object_not_found`) until the next restart.
+     * Best-effort + non-fatal: drivers without DDL (or read-only datasources)
+     * simply no-op, and a sync failure must not abort the publish.
+     */
+    private ensureObjectStorage;
+    /**
+     * Inverse of {@link ensureObjectStorage}: drop an object's physical table.
+     * DESTRUCTIVE — deletes the table and all its rows. Only invoked when a
+     * delete explicitly opts into storage teardown (see {@link deleteMetaItem}'s
+     * `dropStorage`), so publishing an object solely to preview it can be undone
+     * without leaving an orphan table. Best-effort: a failure is logged, not
+     * thrown — the metadata delete already succeeded, and a stray table is
+     * reclaimed by the next sync/drop rather than blocking the delete.
+     */
+    private dropObjectStorage;
+    /**
+     * Guard for storage teardown on delete. Drops a physical table only when
+     * the caller opted in AND it is safe: object types only (others have no
+     * table), active state only (drafts were never materialised), and never a
+     * `sys_`-prefixed platform table.
+     */
+    private shouldDropStorage;
+    saveMetaItem(request: {
+        type: string;
+        name: string;
+        item?: any;
+        organizationId?: string;
+        parentVersion?: string | null;
+        actor?: string;
+        force?: boolean;
+        mode?: 'draft' | 'publish';
+        packageId?: string | null;
+    }): Promise<{
+        success: boolean;
+        version: string;
+        seq: number;
+        state: string;
+        message: string;
+    } | {
+        success: boolean;
+        message: string;
+        version?: undefined;
+        seq?: undefined;
+        state?: undefined;
+    }>;
+    /**
+     * Yield the durable change-log for a single metadata item — every
+     * put/delete recorded in `sys_metadata_history` for `(org, type, name)`,
+     * in event_seq order. Powers the Studio "History" tab and any
+     * client-side audit timeline.
+     *
+     * Returns `[]` for non-overlay-allowed types (the legacy raw-engine
+     * path doesn't record history) instead of throwing — callers can treat
+     * "no history" uniformly.
+     */
+    historyMetaItem(request: {
+        type: string;
+        name: string;
+        organizationId?: string;
+        sinceSeq?: number;
+        limit?: number;
+    }): Promise<{
+        events: _objectstack_metadata_core.MetadataEvent[];
+    }>;
+    /**
+     * Promote the pending draft overlay to the live (`active`) row.
+     * Records a history event with `op='publish'`. 404 (`[no_draft]`)
+     * when there is nothing to publish.
+     */
+    publishMetaItem(request: {
+        type: string;
+        name: string;
+        organizationId?: string;
+        actor?: string;
+        message?: string;
+        /**
+         * INTERNAL — `publishPackageDrafts` publishes many drafts and batch-applies
+         * every seed body in ONE loader pass afterwards (cross-seed references need
+         * multi-pass over the whole set), so it suppresses the per-item apply here.
+         */
+        _skipSeedApply?: boolean;
+    }): Promise<{
+        success: boolean;
+        version: string;
+        seq: number;
+        message?: string;
+        /**
+         * Present when a `seed` draft was published: the result of materializing
+         * its rows. Publishing the metadata ALWAYS succeeds independently — a
+         * seed-load problem is surfaced here, never thrown, so callers (and UIs)
+         * must check `seedApplied.success` instead of assuming data went live.
+         */
+        seedApplied?: {
+            success: boolean;
+            inserted: number;
+            updated: number;
+            error?: string;
+            errors?: unknown[];
+        };
+    }>;
+    /**
+     * Materialize published `seed` bodies into data rows via the SeedLoaderService
+     * (externalId-keyed upsert, multi-pass for cross-seed references). Passing ALL
+     * of a publish's seed bodies in ONE call lets a child seed reference a parent
+     * seed's rows regardless of publish order. Best-effort: any failure is
+     * returned, never thrown — publishing metadata must not be blocked by a data
+     * problem, but the caller surfaces `seedApplied` so the failure is LOUD.
+     */
+    private applySeedBodies;
+    /**
+     * List pending DRAFT metadata (ADR-0033) for the org, optionally narrowed
+     * by `packageId` and/or `type`. The list reads of `getMetaItems` only see
+     * the ACTIVE registry; this exposes what an AI authored but a human hasn't
+     * published yet, so the console can show a "pending changes" surface and a
+     * just-built app package isn't displayed as empty. No body is returned.
+     */
+    listDrafts(request?: {
+        packageId?: string;
+        type?: string;
+        organizationId?: string;
+    }): Promise<{
+        drafts: Array<{
+            type: string;
+            name: string;
+            packageId: string | null;
+            updatedAt: string | null;
+            updatedBy: string | null;
+        }>;
+    }>;
+    /**
+     * Publish every pending DRAFT bound to a package in one shot (ADR-0033) —
+     * the "publish whole app" action. Promotes each draft→active by reusing the
+     * per-item {@link publishMetaItem} primitive (which runs the overridable /
+     * lock guards and refreshes the runtime registry), so this needs NO
+     * `metadata` service (unlike `MetadataService.publishPackage`, which reads
+     * the in-memory registry and 503s when that service is absent). Per-item
+     * failures are collected and do NOT abort the rest.
+     */
+    publishPackageDrafts(request: {
+        packageId: string;
+        organizationId?: string;
+        actor?: string;
+        /** ADR-0067 — commit message (for AI turns: the user's instruction). */
+        message?: string;
+        /** ADR-0067 — AI model that authored the turn (absent for human/CLI). */
+        aiModel?: string;
+    }): Promise<{
+        success: boolean;
+        publishedCount: number;
+        failedCount: number;
+        published: Array<{
+            type: string;
+            name: string;
+            version: string;
+        }>;
+        failed: Array<{
+            type: string;
+            name: string;
+            error: string;
+            code?: string;
+        }>;
+        /** Aggregate result of materializing every published `seed` (absent when no seeds). */
+        seedApplied?: {
+            success: boolean;
+            inserted: number;
+            updated: number;
+            error?: string;
+            errors?: unknown[];
+        };
+        /**
+         * ADR-0038 L3 — post-publish runtime probe report (absent when nothing
+         * was publishable). One real read per published artifact: seeded
+         * objects must have rows, views must be readable, dashboard widgets'
+         * dataset selections must execute and return data. `issues` carries
+         * BuildIssue-shaped findings (layer 'runtime') for the agent / chat
+         * health surfaces; probes never fail the publish itself.
+         */
+        probes?: BuildProbeReport;
+        /** ADR-0067 — id of the commit this publish recorded (absent if nothing published). */
+        commitId?: string;
+    }>;
+    /**
+     * Discard every pending DRAFT bound to a package — the NON-destructive
+     * inverse of {@link publishPackageDrafts}. Drops only `state='draft'` rows
+     * (via the per-item delete primitive), reverting the package to its last
+     * published baseline; active/published metadata and physical tables are
+     * left untouched.
+     *
+     * Use case: "I edited this app for a while and it turned out worse than
+     * before — abandon all my changes." Routes through the sys_metadata path
+     * (no metadata-service dependency, unlike `POST /packages/:id/revert`).
+     */
+    discardPackageDrafts(request: {
+        packageId: string;
+        organizationId?: string;
+        actor?: string;
+    }): Promise<{
+        success: boolean;
+        discardedCount: number;
+        failedCount: number;
+        discarded: Array<{
+            type: string;
+            name: string;
+        }>;
+        failed: Array<{
+            type: string;
+            name: string;
+            error: string;
+            code?: string;
+        }>;
+    }>;
+    /**
+     * Delete an ENTIRE package: every `sys_metadata` row bound to it (active
+     * AND draft) and — by default — the physical table of each object it
+     * defined. DESTRUCTIVE: removes the app and its data. Use case: "I don't
+     * want this package anymore."
+     *
+     * Set `keepData: true` to remove the metadata but preserve object tables.
+     * The `sys_`-table guard in {@link deleteMetaItem} still applies, so
+     * platform storage is never dropped. Drafts are removed before active rows
+     * so each object's table is torn down once. Per-item failures are collected
+     * without aborting the rest.
+     */
+    deletePackage(request: {
+        packageId: string;
+        organizationId?: string;
+        actor?: string;
+        keepData?: boolean;
+    }): Promise<{
+        success: boolean;
+        deletedCount: number;
+        failedCount: number;
+        deleted: Array<{
+            type: string;
+            name: string;
+            state: string;
+        }>;
+        failed: Array<{
+            type: string;
+            name: string;
+            error: string;
+            code?: string;
+        }>;
+    }>;
+    /**
+     * ADR-0070 D4 — duplicate a writable base into a NEW package (the Airtable
+     * "duplicate base" gesture). Clones every ACTIVE item the source owns into
+     * `targetPackageId`, RE-NAMESPACING object names — the blueprint prefixes a
+     * base's object names with its namespace (e.g. `iojn_repair_ticket`), and
+     * `sys_metadata` keys on (type,name,org), so a same-name copy would collide
+     * with the source — and rewriting every intra-package reference (lookup
+     * `reference`, view `object`, expressions, etc.) to the new names. Per-item
+     * best-effort; one failure never aborts the whole clone.
+     */
+    duplicatePackage(request: {
+        sourcePackageId: string;
+        targetPackageId: string;
+        targetName?: string;
+        targetNamespace?: string;
+        organizationId?: string;
+        actor?: string;
+    }): Promise<{
+        success: boolean;
+        copiedCount: number;
+        failedCount: number;
+        targetPackageId: string;
+        copied: Array<{
+            type: string;
+            name: string;
+        }>;
+        failed: Array<{
+            type: string;
+            name: string;
+            error: string;
+        }>;
+    }>;
+    /**
+     * ADR-0070 D5 — adopt orphaned (package-less) metadata into a base. The
+     * pre-package-first stopgaps left runtime-authored items with
+     * `package_id = null` (or the `sys_metadata` sentinel). This bulk-rebinds
+     * every such orphan to `targetPackageId` so the env converges on the
+     * package-first model and the "Local / Custom" migration scope can be
+     * retired. Owned rows (already bound to a real package) are left untouched.
+     * Updates the durable column; the in-memory registry picks the new binding
+     * up on the next metadata reload.
+     */
+    reassignOrphanedMetadata(request: {
+        targetPackageId: string;
+        organizationId?: string;
+        actor?: string;
+    }): Promise<{
+        success: boolean;
+        reassignedCount: number;
+        reassigned: Array<{
+            type: string;
+            name: string;
+        }>;
+        targetPackageId: string;
+    }>;
+    /**
+     * Record one commit row (best-effort) grouping a turn's published
+     * artifacts. Returns the commit id, or null if the commit store is
+     * unavailable (e.g. unit-test stubs) — recording never blocks a publish.
+     */
+    private recordPackageCommit;
+    private parseCommitItems;
+    /**
+     * List the commit timeline for a package, newest-first (ADR-0067). Returns
+     * [] if the commit store is unavailable.
+     */
+    listCommits(request: {
+        packageId: string;
+        organizationId?: string;
+        limit?: number;
+    }): Promise<Array<{
+        id: string;
+        operation: 'apply' | 'revert';
+        message?: string;
+        actor?: string;
+        aiModel?: string;
+        parentCommitId?: string;
+        itemCount: number;
+        items: Array<{
+            type: string;
+            name: string;
+            existedBefore: boolean;
+            prevVersion: number | null;
+        }>;
+        createdAt?: string;
+    }>>;
+    /**
+     * Revert a single commit (ADR-0067): undo exactly the artifacts it touched.
+     * A created-by-this-commit artifact is soft-removed (metadata row deleted;
+     * the data table is NOT dropped — recoverable, per ADR-0067 §5); a modified
+     * artifact is restored to its pre-commit `prevVersion`. The revert is itself
+     * recorded as a NEW commit (operation='revert'), so history stays
+     * append-only and the revert is itself revertible.
+     */
+    revertCommit(request: {
+        commitId: string;
+        organizationId?: string;
+        actor?: string;
+    }): Promise<{
+        success: boolean;
+        revertedCount: number;
+        failedCount: number;
+        reverted: Array<{
+            type: string;
+            name: string;
+            action: 'removed' | 'restored';
+        }>;
+        failed: Array<{
+            type: string;
+            name: string;
+            error: string;
+            code?: string;
+        }>;
+        revertCommitId?: string;
+    }>;
+    /**
+     * Roll a package back THROUGH every `apply` commit newer than `commitId`
+     * (newest first), leaving the package as it was at that commit. Each step is
+     * an individual `revertCommit`, so the whole rollback is itself audited.
+     */
+    rollbackToPackageCommit(request: {
+        commitId: string;
+        organizationId?: string;
+        actor?: string;
+    }): Promise<{
+        success: boolean;
+        revertedCommits: string[];
+        failed: Array<{
+            commitId: string;
+            error: string;
+        }>;
+    }>;
+    /**
+     * Restore the body recorded at history `toVersion` as the new
+     * live row. Writes a history event with `op='revert'`. 404
+     * (`[version_not_found]`) when the target version doesn't exist;
+     * 409 (`[version_not_restorable]`) when the target is a delete
+     * tombstone (no body to bring back).
+     */
+    rollbackMetaItem(request: {
+        type: string;
+        name: string;
+        toVersion: number;
+        organizationId?: string;
+        actor?: string;
+        message?: string;
+    }): Promise<{
+        success: boolean;
+        version: string;
+        seq: number;
+        restoredFromVersion: number;
+        message?: string;
+    }>;
+    /**
+     * Compute a shallow structural diff between two historical
+     * versions of a metadata item. Either side may be omitted: when
+     * `toVersion` is undefined the current active body is used; when
+     * `fromVersion` is undefined the immediately previous history row
+     * is used. Returns `{ added, removed, changed }` keyed by JSON
+     * pointer-style paths for primitive leaves; nested objects/arrays
+     * are reported as a single change record.
+     */
+    diffMetaItem(request: {
+        type: string;
+        name: string;
+        fromVersion?: number;
+        toVersion?: number;
+        organizationId?: string;
+    }): Promise<{
+        type: string;
+        name: string;
+        fromVersion: number | null;
+        toVersion: number | null;
+        added: Array<{
+            path: string;
+            value: unknown;
+        }>;
+        removed: Array<{
+            path: string;
+            value: unknown;
+        }>;
+        changed: Array<{
+            path: string;
+            from: unknown;
+            to: unknown;
+        }>;
+    }>;
+    /**
+     * Remove a customization overlay row for the given metadata item, so the
+     * next read falls through to the artifact-loaded default. Implements the
+     * "Reset to factory default" semantic from ADR-0005. Whitelist is shared
+     * with {@link saveMetaItem}.
+     */
+    deleteMetaItem(request: {
+        type: string;
+        name: string;
+        organizationId?: string;
+        parentVersion?: string | null;
+        actor?: string;
+        state?: 'active' | 'draft';
+        /**
+         * When true, also drop the object's physical table after the metadata
+         * is removed (object + active only; never `sys_`). Default false keeps
+         * delete non-destructive to data. Used by the "discard a previewed
+         * object" flow so a publish-to-preview leaves no orphan table.
+         */
+        dropStorage?: boolean;
+    }): Promise<{
+        success: boolean;
+        message?: string;
+        reset?: boolean;
+        seq?: number;
+    }>;
+    /**
+     * Hydrate SchemaRegistry from the database on startup.
+     * Loads all active metadata records and registers them in the in-memory registry.
+     * Safe to call repeatedly — idempotent (latest DB record wins).
+     *
+     * Per ADR-0005, project-kernel mode ALSO hydrates from sys_metadata —
+     * customization overlay rows must survive restart. Scope filter
+     * (`environment_id = this.environmentId ?? null`) keeps tenants isolated.
+     */
+    loadMetaFromDb(): Promise<{
+        loaded: number;
+        errors: number;
+    }>;
+    /**
+     * Scan all loaded metadata for references pointing at the given
+     * `{type, name}` target. Returns one row per referring artifact with
+     * the path that produced the hit, so the admin UI can render an
+     * "Used by" panel before destructive actions (rename / delete /
+     * type-narrowing).
+     *
+     * Coverage is driven by the hand-curated {@link REFERENCE_PATHS}
+     * registry. Types not present in the registry simply return no hits
+     * — the engine never throws.
+     */
+    findReferencesToMeta(request: {
+        type: string;
+        name: string;
+        organizationId?: string;
+    }): Promise<{
+        references: Array<{
+            type: string;
+            name: string;
+            label?: string;
+            path: string;
+            kind: string;
+        }>;
+    }>;
+    listFeed(request: any): Promise<any>;
+    createFeedItem(request: any): Promise<any>;
+    updateFeedItem(request: any): Promise<any>;
+    deleteFeedItem(request: any): Promise<any>;
+    addReaction(request: any): Promise<any>;
+    removeReaction(request: any): Promise<any>;
+    pinFeedItem(request: any): Promise<any>;
+    unpinFeedItem(request: any): Promise<any>;
+    starFeedItem(request: any): Promise<any>;
+    unstarFeedItem(request: any): Promise<any>;
+    searchFeed(request: any): Promise<any>;
+    getChangelog(request: any): Promise<any>;
+    feedSubscribe(request: any): Promise<any>;
+    feedUnsubscribe(request: any): Promise<any>;
+    /**
+     * Install a package from a manifest — the single canonical write primitive
+     * for the package subsystem (ADR-0033 consolidation).
+     *
+     * It writes BOTH stores that the runtime keeps for packages, so a package
+     * surfaces consistently no matter which read path is used:
+     *   1. the in-memory `SchemaRegistry` (what the dispatcher's
+     *      `/api/v1/packages` list/detail and `getMetaItems({type:'package'})`
+     *      read — i.e. what Studio's package selector shows), and
+     *   2. the durable `sys_packages` table via the optional `package` service
+     *      (so the package survives a restart; that service re-hydrates these
+     *      rows back into the registry on boot).
+     *
+     * The DB write is best-effort and non-fatal: when the `package` service is
+     * absent (e.g. the `marketplace` capability is off) the package is still
+     * registered in-memory and visible for the lifetime of the process.
+     */
+    installPackage(request: InstallPackageRequest): Promise<InstallPackageResponse>;
+}
+
+/**
+ * Overlay-row lifecycle state.
+ *
+ *  - `'active'`  → the published, live overlay. `getMetaItem` (the
+ *    default read path) and runtime loaders observe this row.
+ *  - `'draft'`   → an unpublished pending change. Lives alongside the
+ *    active row (one of each per `(org,type,name)`). Promoted to
+ *    `active` via {@link SysMetadataRepository.promoteDraft}.
+ *
+ * Other lifecycle values defined on `sys_metadata.state` (`'archived'`,
+ * `'deprecated'`) are not yet plumbed through the overlay write path;
+ * they remain reserved for future flows (item retirement, freeze).
+ */
+type OverlayState = 'active' | 'draft';
+/**
+ * Extended history operation tag. The base `'create' | 'update' |
+ * 'delete'` operations are emitted by the canonical put/delete paths.
+ * `'publish'` is recorded when a draft is promoted, `'revert'` when a
+ * historical version is restored. Both are surfaced as MetadataEvent
+ * `.op` values via `history()`.
+ */
+type ExtendedOperation = 'create' | 'update' | 'publish' | 'revert' | 'delete';
+/**
+ * Sub-set of the ObjectQL engine shape we depend on. Kept narrow so
+ * tests can stub it with a plain mock. Mirrors the real engine's
+ * `options.context` pattern so transactions can thread through.
+ */
+interface SysMetadataEngine {
+    find(table: string, options: {
+        where: Record<string, unknown>;
+        limit?: number;
+        orderBy?: any;
+        context?: any;
+    }): Promise<any[]>;
+    findOne(table: string, options: {
+        where: Record<string, unknown>;
+        context?: any;
+    }): Promise<any | null>;
+    insert(table: string, data: Record<string, unknown>, options?: {
+        context?: any;
+    }): Promise<{
+        id: string;
+    }>;
+    update(table: string, data: Record<string, unknown>, options: {
+        where: Record<string, unknown>;
+        context?: any;
+    }): Promise<{
+        id: string;
+    }>;
+    delete(table: string, options: {
+        where: Record<string, unknown>;
+        context?: any;
+    }): Promise<{
+        deleted: number;
+    }>;
+    /**
+     * Optional. Falls through to direct callback invocation if the
+     * underlying driver lacks ACID support (matches the real
+     * `ObjectQL.transaction` semantics). Repository code must not rely on
+     * rollback for correctness against in-memory drivers.
+     */
+    transaction?<T>(callback: (trxCtx: any) => Promise<T>, baseContext?: any): Promise<T>;
+}
+interface SysMetadataRepositoryOptions {
+    engine: SysMetadataEngine;
+    /**
+     * Tenancy scope. `null` writes to env-wide overlay rows; a string
+     * scopes to one organization (the supported shared-DB tenant model
+     * — see ADR-0005 amendment).
+     */
+    organizationId?: string | null;
+    /** Org label embedded in returned MetaRefs. Defaults to organizationId or `"system"`. */
+    orgLabel?: string;
+}
+/** Test hook — clear the memoised env-writable cache. */
+declare function resetEnvWritableMetadataTypes(): void;
+declare class SysMetadataRepository implements MetadataRepository {
+    private readonly engine;
+    private readonly organizationId;
+    private readonly orgLabel;
+    /**
+     * Local seq counter for in-memory watch() event broadcasts. Mirrors
+     * the durable `event_seq` we write into `sys_metadata_history` on
+     * each successful put/delete — assigned AFTER the transaction commits
+     * so we never broadcast events that got rolled back.
+     */
+    private seqCounter;
+    private readonly watchers;
+    private closed;
+    /** Table name for the durable event log. */
+    private readonly historyTable;
+    constructor(opts: SysMetadataRepositoryOptions);
+    /**
+     * Run `cb` inside `engine.transaction(...)` if the engine supports it,
+     * otherwise fall through to a direct call. Matches the real
+     * `ObjectQL.transaction` semantics — in-memory drivers (and our test
+     * fakes) get no rollback, which is acceptable because production
+     * always runs on a SQL driver with real ACID.
+     */
+    private withTxn;
+    /**
+     * Read the current overlay row. Returns null if no row exists —
+     * callers (e.g. LayeredRepository) fall through to lower layers.
+     *
+     * `opts.state` selects which lifecycle row to read: defaults to the
+     * live published row (`'active'`). Pass `'draft'` to read the pending
+     * unpublished revision (if any).
+     */
+    get(ref: MetaRef, opts?: {
+        state?: OverlayState;
+        packageId?: string | null;
+    }): Promise<MetadataItem | null>;
+    /**
+     * Resolve a historical version by content hash (ADR-0009).
+     *
+     * Looks up `sys_metadata_history` by `(organization_id, type, name,
+     * checksum)`. Returns null if no row matches. `executionPinned` types
+     * are guaranteed to find their body here because history GC skips
+     * them.
+     */
+    getByHash(ref: MetaRef, hash: string): Promise<MetadataItem | null>;
+    put(ref: MetaRef, spec: unknown, opts: PutOptions & {
+        state?: OverlayState;
+        opType?: ExtendedOperation;
+    }): Promise<PutResult>;
+    delete(ref: MetaRef, opts: DeleteOptions & {
+        state?: OverlayState;
+    }): Promise<DeleteResult>;
+    /**
+     * Promote the pending draft row for `ref` into the live (`active`)
+     * overlay. Atomic: reads the draft inside the same transaction, runs
+     * the canonical `put` to upsert the active row (which appends a
+     * history event with `operation_type='publish'`), then deletes the
+     * draft row.
+     *
+     * Errors if no draft exists (callers should 404). The active row's
+     * `parentVersion` is computed from the current active hash so this
+     * also surfaces optimistic-lock conflicts when something else has
+     * published in between (e.g. another admin reverted to an older
+     * version since the draft was authored).
+     */
+    promoteDraft(ref: MetaRef, opts: {
+        actor: string;
+        source?: string;
+        message?: string;
+        intent?: MetadataWriteIntent;
+    }): Promise<{
+        version: string;
+        seq: number;
+        item: MetadataItem;
+    }>;
+    /**
+     * Restore the body recorded in history at `targetVersion` (per-org
+     * lineage counter) as the new active row. Writes a history event
+     * with `operation_type='revert'` so the audit trail captures the
+     * intent. Does NOT touch any draft row.
+     *
+     * Throws `[version_not_found]` (404) if the target version row is
+     * missing or is a delete tombstone (no body to restore).
+     */
+    restoreVersion(ref: MetaRef, targetVersion: number, opts: {
+        actor: string;
+        source?: string;
+        message?: string;
+        intent?: MetadataWriteIntent;
+    }): Promise<{
+        version: string;
+        seq: number;
+        item: MetadataItem;
+    }>;
+    list(filter: ListFilter): AsyncIterable<MetadataItemHeader>;
+    /**
+     * List pending DRAFT rows (ADR-0033) for this org, optionally narrowed by
+     * `type` and/or `packageId`. Unlike {@link list} (which is hard-scoped to
+     * `state='active'`), this reads `state='draft'` so the console can surface
+     * what an AI authored but a human hasn't published yet. Returns a light
+     * header projection (no body) suitable for a "pending changes" list.
+     */
+    listDrafts(filter?: {
+        type?: string;
+        packageId?: string;
+    }): Promise<Array<{
+        type: string;
+        name: string;
+        packageId: string | null;
+        updatedAt: string | null;
+        updatedBy: string | null;
+    }>>;
+    /**
+     * Yield every history event for `(org, type?, name?)` from the
+     * durable log, ordered by per-(type,name) `version` ascending. When
+     * `filter.type`/`filter.name` are unset the consumer gets the full
+     * org-scoped event stream — still ordered by version within each
+     * (type,name) bucket, then by `recorded_at` across buckets (we sort
+     * client-side because the test engine doesn't honor `orderBy`).
+     */
+    history(ref: MetaRef, opts?: HistoryOptions): AsyncIterable<MetadataEvent>;
+    /**
+     * Live event stream. Fires for every successful put/delete on THIS
+     * instance — cross-replica fan-out is M1. Manual AsyncIterator (not
+     * an async generator) so we can deterministically tear down via
+     * `iter.return()`, matching the pattern used by InMemoryRepository.
+     */
+    watch(filter: WatchFilter, since?: number): AsyncIterable<MetadataEvent>;
+    /** Shut down all watch iterators. */
+    close(): void;
+    private assertOpen;
+    /**
+     * Defense-in-depth authorization gate.
+     *
+     * `intent` defaults to `'override-artifact'` (the historical strict
+     * behavior). The protocol layer passes `'runtime-only'` after it has
+     * verified — via the schema registry — that no artifact item exists
+     * at `(type, name)`. In that case we accept types with
+     * `allowRuntimeCreate: true`, even when `allowOrgOverride` is false.
+     *
+     * The env-var escape hatch (`OS_METADATA_WRITABLE`) still
+     * applies to BOTH intents, so operators can opt into artifact
+     * overrides at runtime for emergency fixes.
+     */
+    private assertAllowed;
+    private whereFor;
+    private fullRef;
+    private rowToItem;
+    private broadcast;
+    private matchesFilter;
+    /**
+     * Per-org monotonic event sequence. Reads `MAX(event_seq) + 1` from
+     * `sys_metadata_history` scoped by `organization_id`. MUST be called
+     * inside a transaction (the only caller is the put/delete txn body) —
+     * concurrent writers in the same org race otherwise.
+     */
+    private nextEventSeq;
+    /**
+     * Per-(org,type,name) lineage counter. Reads from history (not from
+     * `sys_metadata.version`) so delete + recreate continues incrementing
+     * instead of restarting at 1.
+     */
+    private nextItemVersion;
+    /** Lightweight UUID-ish id for history rows; sufficient for an audit log. */
+    private uuid;
+}
+
+/**
+ * The engine surface the metadata protocol needs from its host (ADR-0076).
+ *
+ * The protocol uses the data engine purely as storage + a schema registry; it
+ * is injected a concrete engine at runtime (today `@objectstack/objectql`'s
+ * `ObjectQL`). Typing against this interface — instead of the concrete class —
+ * is what lets `@objectstack/metadata-protocol` avoid a dependency on
+ * `@objectstack/objectql` (which would otherwise form a cycle, since the
+ * ObjectQL plugin constructs the protocol).
+ */
+interface MetadataHostEngine extends IDataEngine {
+    /** Schema registry (listItems/getItem/registerItem/getObject/registerObject/installPackage/...). */
+    registry: any;
+    /** DDL: create/sync the physical table for an object schema. */
+    syncObjectSchema(...args: any[]): Promise<any>;
+    /** DDL: drop the physical table for an object schema. */
+    dropObjectSchema(...args: any[]): Promise<any>;
+    [key: string]: any;
+}
+
+interface Logger {
+    info(message: string, meta?: Record<string, any>): void;
+    warn(message: string, meta?: Record<string, any>): void;
+    error(message: string, error?: Error, meta?: Record<string, any>): void;
+    debug(message: string, meta?: Record<string, any>): void;
+}
+/**
+ * SeedLoaderService — Runtime implementation of ISeedLoaderService
+ *
+ * Provides metadata-driven seed data loading with:
+ * - Automatic lookup/master_detail reference resolution via externalId
+ * - Topological dependency ordering (parents before children)
+ * - Multi-pass loading for circular references
+ * - Dry-run validation mode
+ * - Upsert support honoring SeedSchema mode
+ * - Actionable error reporting
+ */
+declare class SeedLoaderService implements ISeedLoaderService {
+    private engine;
+    private metadata;
+    private logger;
+    /**
+     * Tenant org to stamp BUSINESS seed rows with when the caller pinned no
+     * explicit `config.organizationId` (resolved per {@link resolveSoleOrganizationId}).
+     * Set once per {@link load}; never applied to `sys_`/`cloud_`/`ai_` platform
+     * seeds (those stay intentionally global/cross-tenant).
+     */
+    private fallbackOrgId?;
+    constructor(engine: IDataEngine$1, metadata: IMetadataService, logger: Logger);
+    load(request: SeedLoaderRequest): Promise<SeedLoaderResult>;
+    buildDependencyGraph(objectNames: string[]): Promise<ObjectDependencyGraph>;
+    validate(datasets: Seed[], config?: SeedLoaderConfigInput): Promise<SeedLoaderResult>;
+    private loadDataset;
+    /**
+     * Best-effort resolve the tenant's SOLE organization id — used to stamp
+     * business seed rows when the caller pinned no `config.organizationId` (an
+     * in-process publish has no active user session). A fresh env has exactly one
+     * org, so its seeds should carry it like a normal write instead of landing
+     * org-less (→ invisible under strict org-scoping). Returns undefined when
+     * there are zero or several orgs (genuinely ambiguous — keep the historical
+     * global/cross-tenant NULL) or when `sys_organization` is absent.
+     */
+    private resolveSoleOrganizationId;
+    private resolveFromDatabase;
+    private resolveDeferredUpdates;
+    /**
+     * Seed writes always run as a privileged system context. This bypasses
+     * RBAC checks (so seeds can target system tables like `sys_*`) and
+     * disables the SecurityPlugin's auto-injection of `organization_id` /
+     * `owner_id` — seeds either declare those fields explicitly per
+     * record, or are intentionally cross-tenant / global.
+     */
+    private static readonly SEED_OPTIONS;
+    private writeRecord;
+    /**
+     * Kahn's algorithm for topological sort with cycle detection.
+     */
+    private topologicalSort;
+    private findCycles;
+    private filterByEnv;
+    private orderDatasets;
+    private buildReferenceMap;
+    private loadExistingRecords;
+    private looksLikeInternalId;
+    private extractId;
+    private buildEmptyResult;
+    private buildResult;
+}
+
+export { type BuildProbeReport, ConcurrentUpdateError, type ExtendedOperation, type MetadataDiagnostics, type MetadataHostEngine, ObjectStackProtocolImplementation, type OverlayState, type ProbeAnalytics, type ProbeEngine, type RunBuildProbesOptions, type RuntimeBuildIssue, SeedLoaderService, type SysMetadataEngine, SysMetadataRepository, type SysMetadataRepositoryOptions, computeMetadataDiagnostics, computeViewReferenceDiagnostics, decorateMetadataItem, decorateMetadataItems, normalizeViewMetadata, resetEnvWritableMetadataTypes, runBuildProbes };