@objectstack/objectql 7.1.0 → 7.2.1

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { ServiceObject, ObjectOwnership, HookContext, QueryAST, EngineQueryOptions, DataEngineInsertOptions, EngineUpdateOptions, EngineDeleteOptions, EngineCountOptions, EngineAggregateOptions, DateGranularityValue, Hook } from '@objectstack/spec/data';
-import { ObjectStackManifest, InstalledPackage, MetadataValidationResult, 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, MetadataWriteIntent, ListFilter, MetadataItemHeader, HistoryOptions, MetadataEvent, WatchFilter } from '@objectstack/metadata-core';
 import { ObjectStackProtocol, MetadataCacheRequest, MetadataCacheResponse, BatchUpdateRequest, BatchUpdateResponse, UpdateManyDataRequest, DeleteManyDataRequest } from '@objectstack/spec/api';
@@ -528,6 +528,17 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         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;
@@ -544,9 +555,23 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         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;
+        lockDocsUrl?: string | 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
@@ -583,6 +608,50 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
          * 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;
@@ -799,7 +868,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      */
     private static readonly OVERLAY_ALLOWED_TYPES;
     /**
-     * Phase 3a-env-writable: parse `OBJECTSTACK_METADATA_WRITABLE` once.
+     * 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
@@ -851,6 +920,43 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      * "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
@@ -1243,7 +1349,7 @@ declare class SysMetadataRepository implements MetadataRepository {
      * 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
+     * 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.
      */

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ServiceObject, ObjectOwnership, HookContext, QueryAST, EngineQueryOptions, DataEngineInsertOptions, EngineUpdateOptions, EngineDeleteOptions, EngineCountOptions, EngineAggregateOptions, DateGranularityValue, Hook } from '@objectstack/spec/data';
-import { ObjectStackManifest, InstalledPackage, MetadataValidationResult, 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, MetadataWriteIntent, ListFilter, MetadataItemHeader, HistoryOptions, MetadataEvent, WatchFilter } from '@objectstack/metadata-core';
 import { ObjectStackProtocol, MetadataCacheRequest, MetadataCacheResponse, BatchUpdateRequest, BatchUpdateResponse, UpdateManyDataRequest, DeleteManyDataRequest } from '@objectstack/spec/api';
@@ -528,6 +528,17 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         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;
@@ -544,9 +555,23 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         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;
+        lockDocsUrl?: string | 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
@@ -583,6 +608,50 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
          * 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;
@@ -799,7 +868,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      */
     private static readonly OVERLAY_ALLOWED_TYPES;
     /**
-     * Phase 3a-env-writable: parse `OBJECTSTACK_METADATA_WRITABLE` once.
+     * 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
@@ -851,6 +920,43 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      * "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
@@ -1243,7 +1349,7 @@ declare class SysMetadataRepository implements MetadataRepository {
      * 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
+     * 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.
      */