@objectstack/objectql 7.6.0 → 7.8.0

package/dist/index.d.mts

@@ -2,7 +2,7 @@ import { ServiceObject, ObjectOwnership, HookContext, QueryAST, EngineQueryOptio
 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';
+import { ObjectStackProtocol, MetadataCacheRequest, MetadataCacheResponse, BatchUpdateRequest, BatchUpdateResponse, UpdateManyDataRequest, DeleteManyDataRequest, InstallPackageRequest, InstallPackageResponse } from '@objectstack/spec/api';
 import { IDataEngine, DriverInterface, Logger, Plugin, PluginContext, ObjectKernel } from '@objectstack/core';
 import { IFeedService, IRealtimeService, ICryptoProvider } from '@objectstack/spec/contracts';
 
@@ -81,11 +81,13 @@ type RegistryLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
  */
 interface SchemaRegistryOptions {
     /**
-     * Whether the host kernel runs in multi-tenant mode. When `true`, the
-     * registry auto-injects `organization_id` (lookup → sys_organization)
-     * into every registered user object that doesn't already declare it and
-     * isn't `managedBy` an external subsystem or explicitly opted-out via
-     * `systemFields: false`.
+     * Whether the host kernel runs in multi-tenant mode. The `organization_id`
+     * column itself is auto-injected regardless of this flag (lookup →
+     * sys_organization, on every registered object that doesn't already declare
+     * it, isn't `managedBy` an external subsystem, and hasn't opted out via
+     * `systemFields`/`tenancy.enabled:false`). When `true` the injected column
+     * is additionally INDEXED — single-tenant stacks skip the index since
+     * nothing ever filters by organization.
      *
      * Sourced from the `OS_MULTI_TENANT` env var when not explicitly set —
      * matches how the SecurityPlugin and CLI startup banner pick the mode.
@@ -107,9 +109,12 @@ interface SchemaRegistryOptions {
  * via the natural `{ ...sys, ...authored }` merge.
  *
  * Currently injects:
- *   - `organization_id` — multi-tenant deployments. Required-false (the
- *     SecurityPlugin populates it on insert; nullable rows are still
- *     filtered out by the `tenant_isolation` RLS USING clause).
+ *   - `organization_id` — always provisioned (unless the object opts out via
+ *     `systemFields`/`tenancy.enabled:false` or is `better-auth` managed) so
+ *     the column never depends on the global multi-tenant flag. Required-false;
+ *     org-scoping populates it on insert in multi-tenant mode, and it stays
+ *     NULL on single-tenant stacks. Only the column's INDEX is gated on
+ *     `multiTenant` (no per-tenant filtering exists single-tenant).
  *   - `created_at` / `created_by` / `updated_at` / `updated_by` — audit
  *     fields. Marked `system: true, readonly: true` so detail views can
  *     surface them in a dedicated "System Information" section while
@@ -855,7 +860,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                     label: string | undefined;
                     required: boolean;
                     readonly: boolean;
-                    type: "number" | "boolean" | "tags" | "date" | "record" | "file" | "code" | "datetime" | "signature" | "progress" | "url" | "currency" | "percent" | "password" | "secret" | "email" | "time" | "text" | "textarea" | "phone" | "markdown" | "html" | "richtext" | "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" | "lookup" | "master_detail" | "currency" | "percent" | "password" | "secret" | "email" | "time" | "text" | "textarea" | "phone" | "markdown" | "html" | "richtext" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "tree" | "image" | "avatar" | "video" | "audio" | "formula" | "summary" | "autonumber" | "composite" | "repeater" | "location" | "address" | "json" | "color" | "rating" | "slider" | "qrcode" | "vector";
                     colSpan: number;
                 }[];
             }[];
@@ -1139,6 +1144,17 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      * stale schema into the registry.
      */
     private applyObjectRegistryMutation;
+    /**
+     * 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;
     saveMetaItem(request: {
         type: string;
         name: string;
@@ -1198,6 +1214,55 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         seq: number;
         message?: string;
     }>;
+    /**
+     * 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;
+    }): 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;
+        }>;
+    }>;
     /**
      * Restore the body recorded at history `toVersion` as the new
      * live row. Writes a history event with `op='revert'`. 404
@@ -1323,6 +1388,24 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     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>;
 }
 
 /**
@@ -1493,6 +1576,23 @@ declare class SysMetadataRepository implements MetadataRepository {
         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
@@ -2053,6 +2153,16 @@ declare class ObjectQL implements IDataEngine {
      * before inserting seed data.
      */
     syncSchemas(): Promise<void>;
+    /**
+     * Sync a SINGLE object's physical storage (create/alter its table) on
+     * demand. Boot-time {@link syncSchemas} runs once at startup, so an object
+     * that becomes live at runtime (e.g. publishing a drafted object) has a
+     * registry entry but no table — data CRUD then fails with "no such table"
+     * until the next restart. Calling this right after the object is registered
+     * makes it immediately usable. Idempotent: the SQL driver only creates the
+     * table when absent (and alters to add new columns).
+     */
+    syncObjectSchema(objectName: string): Promise<void>;
     /**
      * Get a registered driver by datasource name.
      * Alias matching @objectql/core datasource() API.

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { ServiceObject, ObjectOwnership, HookContext, QueryAST, EngineQueryOptio
 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';
+import { ObjectStackProtocol, MetadataCacheRequest, MetadataCacheResponse, BatchUpdateRequest, BatchUpdateResponse, UpdateManyDataRequest, DeleteManyDataRequest, InstallPackageRequest, InstallPackageResponse } from '@objectstack/spec/api';
 import { IDataEngine, DriverInterface, Logger, Plugin, PluginContext, ObjectKernel } from '@objectstack/core';
 import { IFeedService, IRealtimeService, ICryptoProvider } from '@objectstack/spec/contracts';
 
@@ -81,11 +81,13 @@ type RegistryLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
  */
 interface SchemaRegistryOptions {
     /**
-     * Whether the host kernel runs in multi-tenant mode. When `true`, the
-     * registry auto-injects `organization_id` (lookup → sys_organization)
-     * into every registered user object that doesn't already declare it and
-     * isn't `managedBy` an external subsystem or explicitly opted-out via
-     * `systemFields: false`.
+     * Whether the host kernel runs in multi-tenant mode. The `organization_id`
+     * column itself is auto-injected regardless of this flag (lookup →
+     * sys_organization, on every registered object that doesn't already declare
+     * it, isn't `managedBy` an external subsystem, and hasn't opted out via
+     * `systemFields`/`tenancy.enabled:false`). When `true` the injected column
+     * is additionally INDEXED — single-tenant stacks skip the index since
+     * nothing ever filters by organization.
      *
      * Sourced from the `OS_MULTI_TENANT` env var when not explicitly set —
      * matches how the SecurityPlugin and CLI startup banner pick the mode.
@@ -107,9 +109,12 @@ interface SchemaRegistryOptions {
  * via the natural `{ ...sys, ...authored }` merge.
  *
  * Currently injects:
- *   - `organization_id` — multi-tenant deployments. Required-false (the
- *     SecurityPlugin populates it on insert; nullable rows are still
- *     filtered out by the `tenant_isolation` RLS USING clause).
+ *   - `organization_id` — always provisioned (unless the object opts out via
+ *     `systemFields`/`tenancy.enabled:false` or is `better-auth` managed) so
+ *     the column never depends on the global multi-tenant flag. Required-false;
+ *     org-scoping populates it on insert in multi-tenant mode, and it stays
+ *     NULL on single-tenant stacks. Only the column's INDEX is gated on
+ *     `multiTenant` (no per-tenant filtering exists single-tenant).
  *   - `created_at` / `created_by` / `updated_at` / `updated_by` — audit
  *     fields. Marked `system: true, readonly: true` so detail views can
  *     surface them in a dedicated "System Information" section while
@@ -855,7 +860,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                     label: string | undefined;
                     required: boolean;
                     readonly: boolean;
-                    type: "number" | "boolean" | "tags" | "date" | "record" | "file" | "code" | "datetime" | "signature" | "progress" | "url" | "currency" | "percent" | "password" | "secret" | "email" | "time" | "text" | "textarea" | "phone" | "markdown" | "html" | "richtext" | "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" | "lookup" | "master_detail" | "currency" | "percent" | "password" | "secret" | "email" | "time" | "text" | "textarea" | "phone" | "markdown" | "html" | "richtext" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "tree" | "image" | "avatar" | "video" | "audio" | "formula" | "summary" | "autonumber" | "composite" | "repeater" | "location" | "address" | "json" | "color" | "rating" | "slider" | "qrcode" | "vector";
                     colSpan: number;
                 }[];
             }[];
@@ -1139,6 +1144,17 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      * stale schema into the registry.
      */
     private applyObjectRegistryMutation;
+    /**
+     * 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;
     saveMetaItem(request: {
         type: string;
         name: string;
@@ -1198,6 +1214,55 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         seq: number;
         message?: string;
     }>;
+    /**
+     * 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;
+    }): 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;
+        }>;
+    }>;
     /**
      * Restore the body recorded at history `toVersion` as the new
      * live row. Writes a history event with `op='revert'`. 404
@@ -1323,6 +1388,24 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     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>;
 }
 
 /**
@@ -1493,6 +1576,23 @@ declare class SysMetadataRepository implements MetadataRepository {
         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
@@ -2053,6 +2153,16 @@ declare class ObjectQL implements IDataEngine {
      * before inserting seed data.
      */
     syncSchemas(): Promise<void>;
+    /**
+     * Sync a SINGLE object's physical storage (create/alter its table) on
+     * demand. Boot-time {@link syncSchemas} runs once at startup, so an object
+     * that becomes live at runtime (e.g. publishing a drafted object) has a
+     * registry entry but no table — data CRUD then fails with "no such table"
+     * until the next restart. Calling this right after the object is registered
+     * makes it immediately usable. Idempotent: the SQL driver only creates the
+     * table when absent (and alters to add new columns).
+     */
+    syncObjectSchema(objectName: string): Promise<void>;
     /**
      * Get a registered driver by datasource name.
      * Alias matching @objectql/core datasource() API.

package/dist/index.js

@@ -110,7 +110,7 @@ function applySystemFields(schema, opts) {
   if (schema.managedBy === "better-auth") return schema;
   const sf = typeof schema.systemFields === "object" && schema.systemFields !== null ? schema.systemFields : void 0;
   const tenancyDisabled = schema.tenancy?.enabled === false;
-  const wantTenant = opts.multiTenant && sf?.tenant !== false && !tenancyDisabled;
+  const wantTenant = sf?.tenant !== false && !tenancyDisabled;
   const wantAudit = sf?.audit !== false;
   const additions = {};
   if (wantTenant && !schema.fields?.organization_id) {
@@ -119,11 +119,11 @@ function applySystemFields(schema, opts) {
       reference: "sys_organization",
       label: "Organization",
       required: false,
-      indexed: true,
+      indexed: opts.multiTenant,
       hidden: true,
       readonly: true,
       system: true,
-      description: "Tenant scope (auto-populated by SecurityPlugin on insert)."
+      description: "Tenant scope (auto-populated by org-scoping on insert; NULL on single-tenant stacks)."
     };
   }
   if (wantAudit) {
@@ -1288,6 +1288,30 @@ var SysMetadataRepository = class {
       yield header;
     }
   }
+  /**
+   * 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.
+   */
+  async listDrafts(filter) {
+    this.assertOpen();
+    const where = {
+      organization_id: this.organizationId,
+      state: "draft"
+    };
+    if (filter?.type) where.type = filter.type;
+    if (filter?.packageId) where.package_id = filter.packageId;
+    const rows = await this.engine.find("sys_metadata", { where });
+    return rows.map((row) => ({
+      type: row.type,
+      name: row.name,
+      packageId: row.package_id ?? null,
+      updatedAt: row.updated_at ?? row.created_at ?? null,
+      updatedBy: row.updated_by ?? row.created_by ?? null
+    }));
+  }
   /**
    * Yield every history event for `(org, type?, name?)` from the
    * durable log, ordered by per-(type,name) `version` ascending. When
@@ -1797,6 +1821,13 @@ function resolveOverlaySchema(type, _item) {
   const singular = import_shared4.PLURAL_TO_SINGULAR[type] ?? type;
   return (0, import_kernel4.getMetadataTypeSchema)(singular) ?? null;
 }
+function normalizeViewMetadata(type, item, saveName) {
+  const singular = import_shared4.PLURAL_TO_SINGULAR[type] ?? type;
+  if (singular !== "view") return item;
+  if (!item || typeof item !== "object" || Array.isArray(item)) return item;
+  const it = item;
+  return it.name ? it : { ...it, name: saveName };
+}
 function mergeArtifactProtection(item, artifactItem) {
   if (item === void 0 || item === null) return item;
   if (artifactItem === void 0 || artifactItem === null) return item;
@@ -3833,6 +3864,24 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       );
     }
   }
+  /**
+   * 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.
+   */
+  async ensureObjectStorage(type, name) {
+    if (type !== "object" && type !== "objects") return;
+    try {
+      await this.engine.syncObjectSchema(name);
+    } catch (err) {
+      console.warn(`[Protocol] table sync failed for object '${name}': ${err?.message ?? err}`);
+    }
+  }
   async saveMetaItem(request) {
     if (!request.item) {
       throw new Error("Item data is required");
@@ -3906,6 +3955,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         throw err;
       }
     }
+    request.item = normalizeViewMetadata(request.type, request.item, request.name);
     {
       const schema = resolveOverlaySchema(request.type, request.item);
       if (schema) {
@@ -3960,6 +4010,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         });
         if (mode === "publish") {
           this.applyObjectRegistryMutation(request);
+          await this.ensureObjectStorage(request.type, request.name);
         }
         await this.recordMetadataAudit({
           type: request.type,
@@ -4130,6 +4181,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         name: request.name,
         item: result.item.body
       });
+      await this.ensureObjectStorage(request.type, request.name);
       return {
         success: true,
         version: result.version,
@@ -4150,6 +4202,66 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       throw err;
     }
   }
+  /**
+   * 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.
+   */
+  async listDrafts(request) {
+    await this.ensureOverlayIndex();
+    const orgId = request?.organizationId ?? null;
+    const repo = this.getOverlayRepo(orgId);
+    const drafts = await repo.listDrafts({
+      ...request?.type ? { type: import_shared4.PLURAL_TO_SINGULAR[request.type] ?? request.type } : {},
+      ...request?.packageId ? { packageId: request.packageId } : {}
+    });
+    return { drafts };
+  }
+  /**
+   * 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.
+   */
+  async publishPackageDrafts(request) {
+    await this.ensureOverlayIndex();
+    const orgId = request.organizationId ?? null;
+    const repo = this.getOverlayRepo(orgId);
+    const drafts = await repo.listDrafts({ packageId: request.packageId });
+    const published = [];
+    const failed = [];
+    for (const d of drafts) {
+      try {
+        const r = await this.publishMetaItem({
+          type: d.type,
+          name: d.name,
+          ...request.organizationId ? { organizationId: request.organizationId } : {},
+          ...request.actor ? { actor: request.actor } : {},
+          message: `publish app package '${request.packageId}'`
+        });
+        published.push({ type: d.type, name: d.name, version: r.version });
+      } catch (e) {
+        failed.push({
+          type: d.type,
+          name: d.name,
+          error: e?.message ?? "publish failed",
+          ...e?.code ? { code: e.code } : {}
+        });
+      }
+    }
+    return {
+      success: failed.length === 0 && published.length > 0,
+      publishedCount: published.length,
+      failedCount: failed.length,
+      published,
+      failed
+    };
+  }
   /**
    * Restore the body recorded at history `toVersion` as the new
    * live row. Writes a history event with `op='revert'`. 404
@@ -4687,6 +4799,39 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     const unsubscribed = await svc.unsubscribe(request.object, request.recordId, "current_user");
     return { success: true, data: { object: request.object, recordId: request.recordId, unsubscribed } };
   }
+  /**
+   * 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.
+   */
+  async installPackage(request) {
+    const manifest = request.manifest;
+    const pkg = this.engine.registry.installPackage(manifest, request.settings);
+    try {
+      const services = this.getServicesRegistry?.();
+      const pkgSvc = services?.get("package");
+      if (pkgSvc?.publish && manifest?.version) {
+        await pkgSvc.publish({ manifest, metadata: {} });
+      }
+    } catch (e) {
+      console.warn(
+        `[protocol.installPackage] sys_packages persist skipped for '${manifest?.id}': ${e?.message}`
+      );
+    }
+    return { package: pkg, message: `Installed package: ${manifest?.id}` };
+  }
 };
 /**
  * Metadata types that are customer-overridable via {@link saveMetaItem}/
@@ -7078,7 +7223,11 @@ var _ObjectQL = class _ObjectQL {
     const driver = this.getDriver(object);
     let id = data.id;
     if (!id && options?.where && typeof options.where === "object" && "id" in options.where) {
-      id = options.where.id;
+      const whereId = options.where.id;
+      const t = typeof whereId;
+      if (whereId !== null && (t === "string" || t === "number" || t === "bigint")) {
+        id = whereId;
+      }
     }
     const opCtx = {
       object,
@@ -7477,6 +7626,23 @@ var _ObjectQL = class _ObjectQL {
       }
     }
   }
+  /**
+   * Sync a SINGLE object's physical storage (create/alter its table) on
+   * demand. Boot-time {@link syncSchemas} runs once at startup, so an object
+   * that becomes live at runtime (e.g. publishing a drafted object) has a
+   * registry entry but no table — data CRUD then fails with "no such table"
+   * until the next restart. Calling this right after the object is registered
+   * makes it immediately usable. Idempotent: the SQL driver only creates the
+   * table when absent (and alters to add new columns).
+   */
+  async syncObjectSchema(objectName) {
+    const obj = this._registry.getObject(objectName);
+    if (!obj) return;
+    const driver = this.getDriverForObject(objectName);
+    if (!driver || typeof driver.syncSchema !== "function") return;
+    const tableName = import_system2.StorageNameMapping.resolveTableName(obj);
+    await driver.syncSchema(tableName, obj);
+  }
   /**
    * Get a registered driver by datasource name.
    * Alias matching @objectql/core datasource() API.
@@ -7803,6 +7969,7 @@ var MetadataFacade = class {
 
 // src/plugin.ts
 var import_system3 = require("@objectstack/spec/system");
+var import_metadata_core3 = require("@objectstack/metadata-core");
 function hasLoadMetaFromDb(service) {
   return typeof service === "object" && service !== null && typeof service["loadMetaFromDb"] === "function";
 }
@@ -7839,6 +8006,21 @@ var ObjectQLPlugin = class {
       ctx.logger.info("ObjectQL engine registered", {
         services: ["objectql", "data", "manifest"]
       });
+      if (this.environmentId === void 0) {
+        this.ql.registerApp({
+          id: "com.objectstack.metadata-objects",
+          name: "Metadata Platform Objects",
+          version: "1.0.0",
+          type: "plugin",
+          scope: "system",
+          objects: [
+            import_metadata_core3.SysMetadataObject,
+            import_metadata_core3.SysMetadataHistoryObject,
+            import_metadata_core3.SysMetadataAuditObject,
+            import_metadata_core3.SysViewDefinitionObject
+          ]
+        });
+      }
       const protocolShim = new ObjectStackProtocolImplementation(
         this.ql,
         () => ctx.getServices ? ctx.getServices() : /* @__PURE__ */ new Map(),