@objectstack/objectql 7.7.0 → 7.9.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';
 
@@ -719,6 +719,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         type: string;
         packageId?: string;
         organizationId?: string;
+        previewDrafts?: boolean;
     }): Promise<{
         type: string;
         items: any[];
@@ -729,10 +730,11 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         packageId?: string;
         organizationId?: string;
         state?: 'active' | 'draft';
+        previewDrafts?: boolean;
     }): Promise<{
         type: string;
         name: string;
-        item: {} | null;
+        item: any;
     } | {
         editable: boolean;
         deletable: boolean;
@@ -860,7 +862,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;
                 }[];
             }[];
@@ -1144,6 +1146,34 @@ 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;
+    /**
+     * 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;
@@ -1203,6 +1233,118 @@ 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;
+        }>;
+    }>;
+    /**
+     * 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;
+        }>;
+    }>;
     /**
      * Restore the body recorded at history `toVersion` as the new
      * live row. Writes a history event with `op='revert'`. 404
@@ -1271,6 +1413,13 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         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;
@@ -1328,6 +1477,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>;
 }
 
 /**
@@ -1498,6 +1665,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
@@ -2058,6 +2242,26 @@ 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>;
+    /**
+     * Drop the physical storage (table/collection) backing an object — the
+     * inverse of {@link syncObjectSchema}. DESTRUCTIVE: deletes all rows in the
+     * table. Used by the protocol delete path when the caller explicitly opts
+     * into storage teardown (e.g. discarding an object that was published only
+     * to preview it). No-op when the object's driver does not expose `dropTable`.
+     * Resolves the physical table name from the registered definition, falling
+     * back to the bare name if the def was already removed.
+     */
+    dropObjectSchema(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';
 
@@ -719,6 +719,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         type: string;
         packageId?: string;
         organizationId?: string;
+        previewDrafts?: boolean;
     }): Promise<{
         type: string;
         items: any[];
@@ -729,10 +730,11 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         packageId?: string;
         organizationId?: string;
         state?: 'active' | 'draft';
+        previewDrafts?: boolean;
     }): Promise<{
         type: string;
         name: string;
-        item: {} | null;
+        item: any;
     } | {
         editable: boolean;
         deletable: boolean;
@@ -860,7 +862,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;
                 }[];
             }[];
@@ -1144,6 +1146,34 @@ 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;
+    /**
+     * 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;
@@ -1203,6 +1233,118 @@ 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;
+        }>;
+    }>;
+    /**
+     * 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;
+        }>;
+    }>;
     /**
      * Restore the body recorded at history `toVersion` as the new
      * live row. Writes a history event with `op='revert'`. 404
@@ -1271,6 +1413,13 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         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;
@@ -1328,6 +1477,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>;
 }
 
 /**
@@ -1498,6 +1665,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
@@ -2058,6 +2242,26 @@ 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>;
+    /**
+     * Drop the physical storage (table/collection) backing an object — the
+     * inverse of {@link syncObjectSchema}. DESTRUCTIVE: deletes all rows in the
+     * table. Used by the protocol delete path when the caller explicitly opts
+     * into storage teardown (e.g. discarding an object that was published only
+     * to preview it). No-op when the object's driver does not expose `dropTable`.
+     * Resolves the physical table name from the registered definition, falling
+     * back to the bare name if the def was already removed.
+     */
+    dropObjectSchema(objectName: string): Promise<void>;
     /**
      * Get a registered driver by datasource name.
      * Alias matching @objectql/core datasource() API.