@objectstack/objectql 7.0.0 → 7.2.0

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { ServiceObject, ObjectOwnership, HookContext, QueryAST, EngineQueryOptions, DataEngineInsertOptions, EngineUpdateOptions, EngineDeleteOptions, EngineCountOptions, EngineAggregateOptions, DateGranularityValue, Hook } from '@objectstack/spec/data';
-import { ObjectStackManifest, InstalledPackage, ExecutionContext } from '@objectstack/spec/kernel';
+import { ObjectStackManifest, InstalledPackage, MetadataValidationResult, MetadataLock, MetadataProvenance, ExecutionContext } from '@objectstack/spec/kernel';
 import * as _objectstack_metadata_core from '@objectstack/metadata-core';
-import { MetadataRepository, MetaRef, MetadataItem, PutOptions, PutResult, DeleteOptions, DeleteResult, ListFilter, MetadataItemHeader, HistoryOptions, MetadataEvent, WatchFilter } 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 } from '@objectstack/spec/api';
 import { IDataEngine, DriverInterface, Logger, Plugin, PluginContext, ObjectKernel } from '@objectstack/core';
 import { IFeedService, IRealtimeService } from '@objectstack/spec/contracts';
@@ -270,6 +270,12 @@ declare class SchemaRegistry {
     reset(): void;
 }
 
+/**
+ * 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;
+
 declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     private engine;
     private getServicesRegistry?;
@@ -488,23 +494,82 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
             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;
+            packages: string[];
+        }>;
+    }>;
     getMetaItems(request: {
         type: string;
         packageId?: string;
         organizationId?: string;
     }): Promise<{
         type: string;
-        items: unknown[];
+        items: any[];
     }>;
     getMetaItem(request: {
         type: string;
         name: string;
         packageId?: string;
         organizationId?: string;
+        state?: 'active' | 'draft';
     }): Promise<{
+        type: string;
+        name: string;
+        item: {} | null;
+    } | {
+        editable: boolean;
+        deletable: boolean;
+        resettable: boolean;
+        packageVersion?: string | undefined;
+        packageId?: string | undefined;
+        provenance?: "package" | "env-forced" | "org" | undefined;
+        lockSource?: "artifact" | "package" | "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
@@ -532,6 +597,58 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         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';
+        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;
@@ -565,7 +682,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                     label: string | undefined;
                     required: boolean;
                     readonly: boolean;
-                    type: "number" | "boolean" | "tags" | "date" | "file" | "code" | "datetime" | "signature" | "progress" | "url" | "text" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "currency" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "avatar" | "video" | "audio" | "formula" | "summary" | "autonumber" | "composite" | "repeater" | "location" | "address" | "json" | "color" | "rating" | "slider" | "qrcode" | "vector";
+                    type: "number" | "boolean" | "tags" | "date" | "record" | "file" | "code" | "datetime" | "signature" | "progress" | "url" | "text" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "currency" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "avatar" | "video" | "audio" | "formula" | "summary" | "autonumber" | "composite" | "repeater" | "location" | "address" | "json" | "color" | "rating" | "slider" | "qrcode" | "vector";
                     colSpan: number;
                 }[];
             }[];
@@ -762,8 +879,81 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     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;
+    /**
+     * 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
@@ -783,16 +973,19 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         parentVersion?: string | null;
         actor?: string;
         force?: boolean;
+        mode?: 'draft' | 'publish';
     }): 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
@@ -813,6 +1006,78 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     }): 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;
+    }): Promise<{
+        success: boolean;
+        version: string;
+        seq: number;
+        message?: 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
@@ -825,6 +1090,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         organizationId?: string;
         parentVersion?: string | null;
         actor?: string;
+        state?: 'active' | 'draft';
     }): Promise<{
         success: boolean;
         message?: string;
@@ -884,6 +1150,28 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     feedUnsubscribe(request: any): Promise<any>;
 }
 
+/**
+ * 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
@@ -963,8 +1251,14 @@ declare class SysMetadataRepository implements MetadataRepository {
     /**
      * 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): Promise<MetadataItem | null>;
+    get(ref: MetaRef, opts?: {
+        state?: OverlayState;
+    }): Promise<MetadataItem | null>;
     /**
      * Resolve a historical version by content hash (ADR-0009).
      *
@@ -974,8 +1268,55 @@ declare class SysMetadataRepository implements MetadataRepository {
      * them.
      */
     getByHash(ref: MetaRef, hash: string): Promise<MetadataItem | null>;
-    put(ref: MetaRef, spec: unknown, opts: PutOptions): Promise<PutResult>;
-    delete(ref: MetaRef, opts: DeleteOptions): Promise<DeleteResult>;
+    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>;
     /**
      * Yield every history event for `(org, type?, name?)` from the
@@ -996,6 +1337,19 @@ declare class SysMetadataRepository implements MetadataRepository {
     /** 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 (`OBJECTSTACK_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;