@objectstack/objectql 7.8.0 → 8.0.0

package/dist/index.d.mts

@@ -5,6 +5,7 @@ import { MetadataRepository, MetaRef, MetadataItem, PutOptions, PutResult, Delet
 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';
+import { Expression } from '@objectstack/spec';
 
 /**
  * Reserved namespaces that do not get FQN prefix applied.
@@ -525,7 +526,18 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                 } | undefined;
                 shortcut?: string | undefined;
                 bulkEnabled?: boolean | undefined;
-                aiExposed?: boolean | undefined;
+                ai?: {
+                    exposed: boolean;
+                    description?: string | undefined;
+                    category?: "data" | "flow" | "analytics" | "action" | "integration" | "vector_search" | "utility" | undefined;
+                    paramHints?: Record<string, {
+                        description?: string | undefined;
+                        enum?: (string | number)[] | undefined;
+                        examples?: unknown[] | undefined;
+                    }> | undefined;
+                    outputSchema?: Record<string, unknown> | undefined;
+                    requiresConfirmation?: boolean | undefined;
+                } | undefined;
                 recordIdParam?: string | undefined;
                 recordIdField?: string | undefined;
                 bodyShape?: "flat" | {
@@ -627,6 +639,17 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                         } | undefined;
                     } | undefined;
                 }[] | undefined;
+                subforms?: {
+                    childObject: string;
+                    relationshipField?: string | undefined;
+                    columns?: any[] | undefined;
+                    amountField?: string | undefined;
+                    totalField?: string | undefined;
+                    title?: string | undefined;
+                    addLabel?: string | undefined;
+                    minRows?: number | undefined;
+                    maxRows?: number | undefined;
+                }[] | undefined;
                 defaultSort?: {
                     field: string;
                     order: "asc" | "desc";
@@ -665,7 +688,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
             supportsVersioning: boolean;
             executionPinned: boolean;
             loadOrder: number;
-            domain: "system" | "data" | "ui" | "automation" | "ai" | "security";
+            domain: "system" | "data" | "ai" | "ui" | "automation" | "security";
             description?: string | undefined;
         }[];
     }>;
@@ -719,6 +742,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         type: string;
         packageId?: string;
         organizationId?: string;
+        previewDrafts?: boolean;
     }): Promise<{
         type: string;
         items: any[];
@@ -729,10 +753,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;
@@ -1155,6 +1180,23 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      * 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;
@@ -1263,6 +1305,69 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
             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
@@ -1331,6 +1436,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;
@@ -1690,15 +1802,16 @@ interface ObjectQLHostContext {
     logger: Logger;
     [key: string]: any;
 }
-/**
- * ObjectQL Engine
- *
- * Implements the IDataEngine interface for data persistence.
- * Acts as the reference implementation for:
- * - CoreServiceName.data (CRUD)
- * - CoreServiceName.metadata (Schema Registry)
- */
 declare class ObjectQL implements IDataEngine {
+    /**
+     * Ambient transaction store (ADR-0034). While a `transaction()` callback
+     * runs, the active transaction handle lives here so that EVERY data
+     * operation — including internal reads done during a write (reference
+     * checks, hooks, expand) — automatically binds to the same connection
+     * instead of asking the pool for another one and deadlocking on the
+     * single-connection SQLite pool.
+     */
+    private readonly txStore;
     private drivers;
     private defaultDriver;
     private logger;
@@ -1876,6 +1989,26 @@ declare class ObjectQL implements IDataEngine {
      * declarative `defaultValue: cel\`today()\``.
      */
     private applyFieldDefaults;
+    /**
+     * Generate values for empty `autonumber` fields on insert — ONLY for drivers
+     * that do not generate them natively (memory, mongodb). For SQL-backed objects
+     * the driver owns a persistent, atomic `_objectstack_sequences` table and
+     * advertises `supports.autonumber === true`; the engine then defers entirely
+     * and never pre-fills (so the persistent sequence is the single source of
+     * truth — see #1603). Required-validation exempts `autonumber` either way, so
+     * a `required` record number is never rejected for "missing" — the runtime
+     * owns the value, not the client.
+     *
+     * In the fallback path the next value is `max(existing) + 1`, seeded once per
+     * `object.field` from the store then incremented in memory (monotonic within
+     * the process, resilient to deletions). `autonumberFormat` is honored, e.g.
+     * `CASE-{0000}` → `CASE-0042`. NOTE: this in-memory seeding is single-instance.
+     */
+    private applyAutonumbers;
+    /** Seed the autonumber counter from the current max numeric value in store. */
+    private seedAutonumber;
+    /** Apply an autonumber format like `CASE-{0000}`; default to the bare number. */
+    private formatAutonumber;
     /**
      * Register contribution (Manifest)
      *
@@ -2042,6 +2175,27 @@ declare class ObjectQL implements IDataEngine {
     destroy(): Promise<void>;
     /** Maximum depth for recursive expand to prevent infinite loops */
     private static readonly MAX_EXPAND_DEPTH;
+    private static readonly MAX_CASCADE_DEPTH;
+    /** In-memory next-value cache per `object.field` for autonumber generation,
+     *  lazily seeded from the current max in the store. */
+    private readonly autonumberCounters;
+    /** Lazily-built index: child object name → roll-up summary descriptors on
+     *  parent objects that aggregate it. Invalidated when packages register. */
+    private summaryIndex;
+    /** Invalidate the cached roll-up summary index (call when metadata changes). */
+    private invalidateSummaryIndex;
+    /** Scan all registered objects for `summary` fields and index them by the
+     *  child object they aggregate, resolving the child→parent FK field. */
+    private buildSummaryIndex;
+    private getSummaryDescriptors;
+    /**
+     * Recompute roll-up `summary` fields on parent records after a child write.
+     * For each affected parent (the FK value on the changed/old child record), it
+     * aggregates the child collection and writes the result onto the parent's
+     * summary field. Runs in the caller's execution context so it joins the same
+     * transaction (e.g. the cross-object batch) when one is open.
+     */
+    private recomputeSummaries;
     /**
      * Post-process expand: resolve lookup/master_detail fields by batch-loading related records.
      *
@@ -2059,6 +2213,19 @@ declare class ObjectQL implements IDataEngine {
     findOne(objectName: string, query?: EngineQueryOptions): Promise<any>;
     insert(object: string, data: any | any[], options?: DataEngineInsertOptions): Promise<any>;
     update(object: string, data: any, options?: EngineUpdateOptions): Promise<any>;
+    /**
+     * Apply referential delete behavior for relations pointing AT this record,
+     * before it is removed. For every registered object with a `master_detail`
+     * or `lookup` field referencing `object`, honor the field's `deleteBehavior`:
+     *   - `cascade`  → delete the dependent rows (recursively, so grandchildren
+     *                  are handled by each child's own delete),
+     *   - `set_null` → clear the foreign key,
+     *   - `restrict` → refuse the delete when dependents exist.
+     * `master_detail` defaults to `cascade` (the parent owns the child
+     * lifecycle); `lookup` defaults to `set_null`. Only runs for single-id
+     * deletes — multi/predicate deletes skip cascade (logged).
+     */
+    private cascadeDeleteRelations;
     delete(object: string, options?: EngineDeleteOptions): Promise<any>;
     count(object: string, query?: EngineCountOptions): Promise<number>;
     aggregate(object: string, query: EngineAggregateOptions): Promise<any[]>;
@@ -2163,6 +2330,16 @@ declare class ObjectQL implements IDataEngine {
      * 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.
@@ -2544,7 +2721,15 @@ interface EvaluateRulesOptions {
  */
 declare function needsPriorRecord(objectSchema: {
     validations?: unknown[];
+    fields?: Record<string, ConditionalFieldDef>;
 } | undefined | null): boolean;
+/** Field-level conditional rules (B2): a field is required / read-only when its
+ *  CEL predicate is TRUE over the record. */
+interface ConditionalFieldDef {
+    requiredWhen?: string | Expression;
+    conditionalRequired?: string | Expression;
+    readonlyWhen?: string | Expression;
+}
 /**
  * Evaluate an object's declared validation rules against an incoming write.
  *
@@ -2554,6 +2739,7 @@ declare function needsPriorRecord(objectSchema: {
  */
 declare function evaluateValidationRules(objectSchema: {
     validations?: unknown[];
+    fields?: Record<string, ConditionalFieldDef>;
 } | undefined | null, data: Record<string, unknown> | undefined | null, mode: Mode, opts?: EvaluateRulesOptions): void;
 /**
  * Introspection helper (ADR-0020 D3.3): given an object's schema, a state

package/dist/index.d.ts

@@ -5,6 +5,7 @@ import { MetadataRepository, MetaRef, MetadataItem, PutOptions, PutResult, Delet
 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';
+import { Expression } from '@objectstack/spec';
 
 /**
  * Reserved namespaces that do not get FQN prefix applied.
@@ -525,7 +526,18 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                 } | undefined;
                 shortcut?: string | undefined;
                 bulkEnabled?: boolean | undefined;
-                aiExposed?: boolean | undefined;
+                ai?: {
+                    exposed: boolean;
+                    description?: string | undefined;
+                    category?: "data" | "flow" | "analytics" | "action" | "integration" | "vector_search" | "utility" | undefined;
+                    paramHints?: Record<string, {
+                        description?: string | undefined;
+                        enum?: (string | number)[] | undefined;
+                        examples?: unknown[] | undefined;
+                    }> | undefined;
+                    outputSchema?: Record<string, unknown> | undefined;
+                    requiresConfirmation?: boolean | undefined;
+                } | undefined;
                 recordIdParam?: string | undefined;
                 recordIdField?: string | undefined;
                 bodyShape?: "flat" | {
@@ -627,6 +639,17 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                         } | undefined;
                     } | undefined;
                 }[] | undefined;
+                subforms?: {
+                    childObject: string;
+                    relationshipField?: string | undefined;
+                    columns?: any[] | undefined;
+                    amountField?: string | undefined;
+                    totalField?: string | undefined;
+                    title?: string | undefined;
+                    addLabel?: string | undefined;
+                    minRows?: number | undefined;
+                    maxRows?: number | undefined;
+                }[] | undefined;
                 defaultSort?: {
                     field: string;
                     order: "asc" | "desc";
@@ -665,7 +688,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
             supportsVersioning: boolean;
             executionPinned: boolean;
             loadOrder: number;
-            domain: "system" | "data" | "ui" | "automation" | "ai" | "security";
+            domain: "system" | "data" | "ai" | "ui" | "automation" | "security";
             description?: string | undefined;
         }[];
     }>;
@@ -719,6 +742,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         type: string;
         packageId?: string;
         organizationId?: string;
+        previewDrafts?: boolean;
     }): Promise<{
         type: string;
         items: any[];
@@ -729,10 +753,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;
@@ -1155,6 +1180,23 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      * 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;
@@ -1263,6 +1305,69 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
             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
@@ -1331,6 +1436,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;
@@ -1690,15 +1802,16 @@ interface ObjectQLHostContext {
     logger: Logger;
     [key: string]: any;
 }
-/**
- * ObjectQL Engine
- *
- * Implements the IDataEngine interface for data persistence.
- * Acts as the reference implementation for:
- * - CoreServiceName.data (CRUD)
- * - CoreServiceName.metadata (Schema Registry)
- */
 declare class ObjectQL implements IDataEngine {
+    /**
+     * Ambient transaction store (ADR-0034). While a `transaction()` callback
+     * runs, the active transaction handle lives here so that EVERY data
+     * operation — including internal reads done during a write (reference
+     * checks, hooks, expand) — automatically binds to the same connection
+     * instead of asking the pool for another one and deadlocking on the
+     * single-connection SQLite pool.
+     */
+    private readonly txStore;
     private drivers;
     private defaultDriver;
     private logger;
@@ -1876,6 +1989,26 @@ declare class ObjectQL implements IDataEngine {
      * declarative `defaultValue: cel\`today()\``.
      */
     private applyFieldDefaults;
+    /**
+     * Generate values for empty `autonumber` fields on insert — ONLY for drivers
+     * that do not generate them natively (memory, mongodb). For SQL-backed objects
+     * the driver owns a persistent, atomic `_objectstack_sequences` table and
+     * advertises `supports.autonumber === true`; the engine then defers entirely
+     * and never pre-fills (so the persistent sequence is the single source of
+     * truth — see #1603). Required-validation exempts `autonumber` either way, so
+     * a `required` record number is never rejected for "missing" — the runtime
+     * owns the value, not the client.
+     *
+     * In the fallback path the next value is `max(existing) + 1`, seeded once per
+     * `object.field` from the store then incremented in memory (monotonic within
+     * the process, resilient to deletions). `autonumberFormat` is honored, e.g.
+     * `CASE-{0000}` → `CASE-0042`. NOTE: this in-memory seeding is single-instance.
+     */
+    private applyAutonumbers;
+    /** Seed the autonumber counter from the current max numeric value in store. */
+    private seedAutonumber;
+    /** Apply an autonumber format like `CASE-{0000}`; default to the bare number. */
+    private formatAutonumber;
     /**
      * Register contribution (Manifest)
      *
@@ -2042,6 +2175,27 @@ declare class ObjectQL implements IDataEngine {
     destroy(): Promise<void>;
     /** Maximum depth for recursive expand to prevent infinite loops */
     private static readonly MAX_EXPAND_DEPTH;
+    private static readonly MAX_CASCADE_DEPTH;
+    /** In-memory next-value cache per `object.field` for autonumber generation,
+     *  lazily seeded from the current max in the store. */
+    private readonly autonumberCounters;
+    /** Lazily-built index: child object name → roll-up summary descriptors on
+     *  parent objects that aggregate it. Invalidated when packages register. */
+    private summaryIndex;
+    /** Invalidate the cached roll-up summary index (call when metadata changes). */
+    private invalidateSummaryIndex;
+    /** Scan all registered objects for `summary` fields and index them by the
+     *  child object they aggregate, resolving the child→parent FK field. */
+    private buildSummaryIndex;
+    private getSummaryDescriptors;
+    /**
+     * Recompute roll-up `summary` fields on parent records after a child write.
+     * For each affected parent (the FK value on the changed/old child record), it
+     * aggregates the child collection and writes the result onto the parent's
+     * summary field. Runs in the caller's execution context so it joins the same
+     * transaction (e.g. the cross-object batch) when one is open.
+     */
+    private recomputeSummaries;
     /**
      * Post-process expand: resolve lookup/master_detail fields by batch-loading related records.
      *
@@ -2059,6 +2213,19 @@ declare class ObjectQL implements IDataEngine {
     findOne(objectName: string, query?: EngineQueryOptions): Promise<any>;
     insert(object: string, data: any | any[], options?: DataEngineInsertOptions): Promise<any>;
     update(object: string, data: any, options?: EngineUpdateOptions): Promise<any>;
+    /**
+     * Apply referential delete behavior for relations pointing AT this record,
+     * before it is removed. For every registered object with a `master_detail`
+     * or `lookup` field referencing `object`, honor the field's `deleteBehavior`:
+     *   - `cascade`  → delete the dependent rows (recursively, so grandchildren
+     *                  are handled by each child's own delete),
+     *   - `set_null` → clear the foreign key,
+     *   - `restrict` → refuse the delete when dependents exist.
+     * `master_detail` defaults to `cascade` (the parent owns the child
+     * lifecycle); `lookup` defaults to `set_null`. Only runs for single-id
+     * deletes — multi/predicate deletes skip cascade (logged).
+     */
+    private cascadeDeleteRelations;
     delete(object: string, options?: EngineDeleteOptions): Promise<any>;
     count(object: string, query?: EngineCountOptions): Promise<number>;
     aggregate(object: string, query: EngineAggregateOptions): Promise<any[]>;
@@ -2163,6 +2330,16 @@ declare class ObjectQL implements IDataEngine {
      * 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.
@@ -2544,7 +2721,15 @@ interface EvaluateRulesOptions {
  */
 declare function needsPriorRecord(objectSchema: {
     validations?: unknown[];
+    fields?: Record<string, ConditionalFieldDef>;
 } | undefined | null): boolean;
+/** Field-level conditional rules (B2): a field is required / read-only when its
+ *  CEL predicate is TRUE over the record. */
+interface ConditionalFieldDef {
+    requiredWhen?: string | Expression;
+    conditionalRequired?: string | Expression;
+    readonlyWhen?: string | Expression;
+}
 /**
  * Evaluate an object's declared validation rules against an incoming write.
  *
@@ -2554,6 +2739,7 @@ declare function needsPriorRecord(objectSchema: {
  */
 declare function evaluateValidationRules(objectSchema: {
     validations?: unknown[];
+    fields?: Record<string, ConditionalFieldDef>;
 } | undefined | null, data: Record<string, unknown> | undefined | null, mode: Mode, opts?: EvaluateRulesOptions): void;
 /**
  * Introspection helper (ADR-0020 D3.3): given an object's schema, a state