@objectstack/objectql 4.0.4 → 4.1.0

package/dist/index.d.ts

@@ -1,61 +1,12 @@
-import { z } from 'zod';
-import * as _objectstack_spec_data from '@objectstack/spec/data';
-import { ObjectOwnership, ServiceObject, QueryAST, HookContext, EngineQueryOptions, DataEngineInsertOptions, EngineUpdateOptions, EngineDeleteOptions, EngineCountOptions, EngineAggregateOptions } from '@objectstack/spec/data';
+import { ServiceObject, ObjectOwnership, HookContext, QueryAST, EngineQueryOptions, DataEngineInsertOptions, EngineUpdateOptions, EngineDeleteOptions, EngineCountOptions, EngineAggregateOptions, DateGranularityValue, Hook } from '@objectstack/spec/data';
 import { ObjectStackManifest, InstalledPackage, ExecutionContext } from '@objectstack/spec/kernel';
 import { ObjectStackProtocol, MetadataCacheRequest, MetadataCacheResponse, BatchUpdateRequest, BatchUpdateResponse, UpdateManyDataRequest, DeleteManyDataRequest } from '@objectstack/spec/api';
 import { IDataEngine, DriverInterface, Logger, Plugin, PluginContext, ObjectKernel } from '@objectstack/core';
 import { IFeedService, IRealtimeService } from '@objectstack/spec/contracts';
 
-/**
- * XState-inspired State Machine Protocol
- * Used to define strict business logic constraints and lifecycle management.
- * Prevent AI "hallucinations" by enforcing valid valid transitions.
- */
-/**
- * References a named action (side effect)
- * Can be a script, a webhook, or a field update.
- */
-declare const ActionRefSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-    type: z.ZodString;
-    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$strip>]>;
-/**
- * State Transition Definition
- * "When EVENT happens, if GUARD is true, go to TARGET and run ACTIONS"
- */
-declare const TransitionSchema: z.ZodObject<{
-    target: z.ZodOptional<z.ZodString>;
-    cond: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-        type: z.ZodString;
-        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    }, z.core.$strip>]>>;
-    actions: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-        type: z.ZodString;
-        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    }, z.core.$strip>]>>>;
-    description: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-type ActionRef = z.infer<typeof ActionRefSchema>;
-type Transition = z.infer<typeof TransitionSchema>;
-type StateNodeConfig = {
-    type?: 'atomic' | 'compound' | 'parallel' | 'final' | 'history';
-    entry?: ActionRef[];
-    exit?: ActionRef[];
-    on?: Record<string, string | Transition | Transition[]>;
-    always?: Transition[];
-    initial?: string;
-    states?: Record<string, StateNodeConfig>;
-    meta?: {
-        label?: string;
-        description?: string;
-        color?: string;
-        aiInstructions?: string;
-    };
-};
-
 /**
  * Reserved namespaces that do not get FQN prefix applied.
- * Objects in these namespaces keep their short names (e.g., "user" not "base__user").
+ * Objects in these namespaces keep their short names (e.g., "user" — short name IS the canonical key).
  */
 declare const RESERVED_NAMESPACES: Set<string>;
 /**
@@ -75,22 +26,25 @@ interface ObjectContributor {
     definition: ServiceObject;
 }
 /**
- * Compute Fully Qualified Name (FQN) for an object.
+ * Compute canonical registry key for an object.
+ *
+ * Under the current naming convention, object names are canonical identifiers
+ * and are used as-is (no namespace__ prefix). The namespace parameter is
+ * retained for backward compatibility but no longer affects the returned key.
  *
- * @param namespace - The package namespace (e.g., "crm", "todo")
- * @param shortName - The object's short name (e.g., "task", "account")
- * @returns FQN string (e.g., "crm__task") or just shortName for reserved namespaces
+ * @param namespace - The package namespace (unused, kept for API compatibility)
+ * @param shortName - The object's name (already the canonical identifier)
+ * @returns The object name unchanged
  *
  * @example
- * computeFQN('crm', 'account')  // => 'crm__account'
- * computeFQN('base', 'user')    // => 'user' (reserved, no prefix)
- * computeFQN(undefined, 'task') // => 'task' (legacy, no namespace)
+ * computeFQN('crm', 'account')  // => 'account'
+ * computeFQN(undefined, 'task') // => 'task'
  */
-declare function computeFQN(namespace: string | undefined, shortName: string): string;
+declare function computeFQN(_namespace: string | undefined, shortName: string): string;
 /**
  * Parse FQN back to namespace and short name.
  *
- * @param fqn - Fully qualified name (e.g., "crm__account" or "user")
+ * @param fqn - Object name (e.g., "account" or legacy "crm__account" for backward compat)
  * @returns { namespace, shortName } - namespace is undefined for unprefixed names
  */
 declare function parseFQN(fqn: string): {
@@ -105,7 +59,7 @@ declare function parseFQN(fqn: string): {
  *
  * Objects use a namespace-based FQN system:
  * - `namespace`: Short identifier from package manifest (e.g., "crm", "todo")
- * - `FQN`: `{namespace}__{short_name}` (e.g., "crm__account")
+ * - `name`: canonical object name (e.g., "account", "sys_user")
  * - Reserved namespaces (`base`, `system`) don't get prefixed
  *
  * Ownership modes:
@@ -120,37 +74,82 @@ declare function parseFQN(fqn: string): {
  * - A package may contain 0, 1, or many apps.
  */
 type RegistryLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * Construction options for {@link SchemaRegistry}.
+ */
+interface SchemaRegistryOptions {
+    /**
+     * Whether the host kernel runs in multi-tenant mode. When `true` (default),
+     * 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`.
+     *
+     * Sourced from the `OS_MULTI_TENANT` env var when not explicitly set —
+     * matches how the SecurityPlugin and CLI startup banner pick the mode.
+     * Pass an explicit boolean to override (useful in tests).
+     */
+    multiTenant?: boolean;
+}
+/**
+ * Augment a registered object with implicit system fields.
+ *
+ * Returns a *new* schema object when fields are added; returns the input
+ * unchanged when nothing applies (the cheap path for system tables).
+ *
+ * Author-declared fields always win — we splice the system fields at the
+ * front of the field map, so any same-named author field overwrites them
+ * 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).
+ *   - `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
+ *     edit forms / drawers filter them out. The driver populates the
+ *     timestamps; the `*_by` lookups are filled by the runtime when an
+ *     authenticated session is present (NULL otherwise — e.g. seeded
+ *     rows).
+ */
+declare function applySystemFields(schema: ServiceObject, opts: {
+    multiTenant: boolean;
+}): ServiceObject;
 declare class SchemaRegistry {
     /** Controls verbosity of registry console messages. Default: 'info'. */
-    private static _logLevel;
-    static get logLevel(): RegistryLogLevel;
-    static set logLevel(level: RegistryLogLevel);
-    private static log;
+    private _logLevel;
+    /** Whether to auto-inject multi-tenant system fields. */
+    private readonly multiTenant;
+    constructor(options?: SchemaRegistryOptions);
+    get logLevel(): RegistryLogLevel;
+    set logLevel(level: RegistryLogLevel);
+    private log;
     /** FQN → Contributor[] (all packages that own/extend this object) */
-    private static objectContributors;
+    private objectContributors;
     /** FQN → Merged ServiceObject (cached, invalidated on changes) */
-    private static mergedObjectCache;
+    private mergedObjectCache;
     /** Namespace → Set<PackageId> (multiple packages can share a namespace) */
-    private static namespaceRegistry;
+    private namespaceRegistry;
     /** Type → Name/ID → MetadataItem */
-    private static metadata;
+    private metadata;
     /**
      * Register a namespace for a package.
      * Multiple packages can share the same namespace (e.g. 'sys').
      */
-    static registerNamespace(namespace: string, packageId: string): void;
+    registerNamespace(namespace: string, packageId: string): void;
     /**
      * Unregister a namespace when a package is uninstalled.
      */
-    static unregisterNamespace(namespace: string, packageId: string): void;
+    unregisterNamespace(namespace: string, packageId: string): void;
     /**
      * Get the packages that use a namespace.
      */
-    static getNamespaceOwner(namespace: string): string | undefined;
+    getNamespaceOwner(namespace: string): string | undefined;
     /**
      * Get all packages that share a namespace.
      */
-    static getNamespaceOwners(namespace: string): string[];
+    getNamespaceOwners(namespace: string): string[];
     /**
      * Register an object with ownership semantics.
      *
@@ -162,1086 +161,127 @@ declare class SchemaRegistry {
      *
      * @throws Error if trying to 'own' an object that already has an owner
      */
-    static registerObject(schema: ServiceObject, packageId: string, namespace?: string, ownership?: ObjectOwnership, priority?: number): string;
+    registerObject(schema: ServiceObject, packageId: string, namespace?: string, ownership?: ObjectOwnership, priority?: number): string;
     /**
      * Resolve an object by FQN, merging all contributions.
      * Returns the merged object or undefined if not found.
      */
-    static resolveObject(fqn: string): ServiceObject | undefined;
+    resolveObject(fqn: string): ServiceObject | undefined;
     /**
-     * Get object by name (FQN, short name, or physical table name).
+     * Get object by name (short name canonical, FQN supported for disambiguation).
+     *
+     * Short names are canonical for user code, AI generation, and most lookups.
+     * FQN is accepted as an explicit fallback for cross-package disambiguation
+     * when two packages contribute objects with the same short name.
      *
      * Resolution order:
-     * 1. Exact FQN match (e.g., 'crm__account')
-     * 2. Short name fallback (e.g., 'account' → 'crm__account')
-     * 3. Physical table name match (e.g., 'sys_user' → 'sys__user')
-     *    ObjectSchema.create() auto-derives tableName as {namespace}_{name},
-     *    which uses a single underscore — different from the FQN double underscore.
+     * 1. Exact name match — the name IS the canonical key.
+     *    If multiple packages contribute the same short name, a warning is logged
+     *    and the first match wins — disambiguate by passing the FQN explicitly.
+     * 2. Legacy FQN match (e.g., 'crm__account') — backward compat.
      */
-    static getObject(name: string): ServiceObject | undefined;
+    getObject(name: string): ServiceObject | undefined;
     /**
      * Get all registered objects (merged).
      *
      * @param packageId - Optional filter: only objects contributed by this package
      */
-    static getAllObjects(packageId?: string): ServiceObject[];
+    getAllObjects(packageId?: string): ServiceObject[];
     /**
      * Get all contributors for an object.
      */
-    static getObjectContributors(fqn: string): ObjectContributor[];
+    getObjectContributors(fqn: string): ObjectContributor[];
     /**
      * Get the owner contributor for an object.
      */
-    static getObjectOwner(fqn: string): ObjectContributor | undefined;
+    getObjectOwner(fqn: string): ObjectContributor | undefined;
     /**
      * Unregister all objects contributed by a package.
      *
      * @throws Error if trying to uninstall an owner that has extenders
      */
-    static unregisterObjectsByPackage(packageId: string, force?: boolean): void;
+    unregisterObjectsByPackage(packageId: string, force?: boolean): void;
     /**
      * Universal Register Method for non-object metadata.
      */
-    static registerItem<T>(type: string, item: T, keyField?: keyof T, packageId?: string): void;
+    registerItem<T>(type: string, item: T, keyField?: keyof T, packageId?: string): void;
     /**
      * Validate Metadata against Spec Zod Schemas
      */
-    static validate(type: string, item: any): true | {
-        name: string;
-        active: boolean;
-        isSystem: boolean;
-        abstract: boolean;
-        datasource: string;
-        fields: Record<string, {
-            type: "number" | "boolean" | "tags" | "date" | "lookup" | "file" | "url" | "json" | "text" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "currency" | "percent" | "datetime" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "master_detail" | "tree" | "image" | "avatar" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "code" | "color" | "rating" | "slider" | "signature" | "qrcode" | "progress" | "vector";
-            required: boolean;
-            searchable: boolean;
-            multiple: boolean;
-            unique: boolean;
-            deleteBehavior: "set_null" | "cascade" | "restrict";
-            auditTrail: boolean;
-            hidden: boolean;
-            readonly: boolean;
-            sortable: boolean;
-            index: boolean;
-            externalId: boolean;
-            name?: string | undefined;
-            label?: string | undefined;
-            description?: string | undefined;
-            format?: string | undefined;
-            columnName?: string | undefined;
-            defaultValue?: unknown;
-            maxLength?: number | undefined;
-            minLength?: number | undefined;
-            precision?: number | undefined;
-            scale?: number | undefined;
-            min?: number | undefined;
-            max?: number | undefined;
-            options?: {
-                label: string;
-                value: string;
-                color?: string | undefined;
-                default?: boolean | undefined;
-            }[] | undefined;
-            reference?: string | undefined;
-            referenceFilters?: string[] | undefined;
-            writeRequiresMasterRead?: boolean | undefined;
-            expression?: string | undefined;
-            summaryOperations?: {
-                object: string;
-                field: string;
-                function: "min" | "max" | "count" | "sum" | "avg";
-            } | undefined;
-            language?: string | undefined;
-            theme?: string | undefined;
-            lineNumbers?: boolean | undefined;
-            maxRating?: number | undefined;
-            allowHalf?: boolean | undefined;
-            displayMap?: boolean | undefined;
-            allowGeocoding?: boolean | undefined;
-            addressFormat?: "us" | "uk" | "international" | undefined;
-            colorFormat?: "hex" | "rgb" | "rgba" | "hsl" | undefined;
-            allowAlpha?: boolean | undefined;
-            presetColors?: string[] | undefined;
-            step?: number | undefined;
-            showValue?: boolean | undefined;
-            marks?: Record<string, string> | undefined;
-            barcodeFormat?: "qr" | "ean13" | "ean8" | "code128" | "code39" | "upca" | "upce" | undefined;
-            qrErrorCorrection?: "L" | "M" | "Q" | "H" | undefined;
-            displayValue?: boolean | undefined;
-            allowScanning?: boolean | undefined;
-            currencyConfig?: {
-                precision: number;
-                currencyMode: "dynamic" | "fixed";
-                defaultCurrency: string;
-            } | undefined;
-            vectorConfig?: {
-                dimensions: number;
-                distanceMetric: "cosine" | "euclidean" | "dotProduct" | "manhattan";
-                normalized: boolean;
-                indexed: boolean;
-                indexType?: "hnsw" | "ivfflat" | "flat" | undefined;
-            } | undefined;
-            fileAttachmentConfig?: {
-                virusScan: boolean;
-                virusScanOnUpload: boolean;
-                quarantineOnThreat: boolean;
-                allowMultiple: boolean;
-                allowReplace: boolean;
-                allowDelete: boolean;
-                requireUpload: boolean;
-                extractMetadata: boolean;
-                extractText: boolean;
-                versioningEnabled: boolean;
-                publicRead: boolean;
-                presignedUrlExpiry: number;
-                minSize?: number | undefined;
-                maxSize?: number | undefined;
-                allowedTypes?: string[] | undefined;
-                blockedTypes?: string[] | undefined;
-                allowedMimeTypes?: string[] | undefined;
-                blockedMimeTypes?: string[] | undefined;
-                virusScanProvider?: "custom" | "clamav" | "virustotal" | "metadefender" | undefined;
-                storageProvider?: string | undefined;
-                storageBucket?: string | undefined;
-                storagePrefix?: string | undefined;
-                imageValidation?: {
-                    generateThumbnails: boolean;
-                    preserveMetadata: boolean;
-                    autoRotate: boolean;
-                    minWidth?: number | undefined;
-                    maxWidth?: number | undefined;
-                    minHeight?: number | undefined;
-                    maxHeight?: number | undefined;
-                    aspectRatio?: string | undefined;
-                    thumbnailSizes?: {
-                        name: string;
-                        width: number;
-                        height: number;
-                        crop: boolean;
-                    }[] | undefined;
-                } | undefined;
-                maxVersions?: number | undefined;
-            } | undefined;
-            encryptionConfig?: {
-                enabled: boolean;
-                algorithm: "aes-256-gcm" | "aes-256-cbc" | "chacha20-poly1305";
-                keyManagement: {
-                    provider: "local" | "aws-kms" | "azure-key-vault" | "gcp-kms" | "hashicorp-vault";
-                    keyId?: string | undefined;
-                    rotationPolicy?: {
-                        enabled: boolean;
-                        frequencyDays: number;
-                        retainOldVersions: number;
-                        autoRotate: boolean;
-                    } | undefined;
-                };
-                scope: "field" | "table" | "record" | "database";
-                deterministicEncryption: boolean;
-                searchableEncryption: boolean;
-            } | undefined;
-            maskingRule?: {
-                field: string;
-                strategy: "redact" | "partial" | "hash" | "tokenize" | "randomize" | "nullify" | "substitute";
-                preserveFormat: boolean;
-                preserveLength: boolean;
-                pattern?: string | undefined;
-                roles?: string[] | undefined;
-                exemptRoles?: string[] | undefined;
-            } | undefined;
-            dependencies?: string[] | undefined;
-            cached?: {
-                enabled: boolean;
-                ttl: number;
-                invalidateOn: string[];
-            } | undefined;
-            dataQuality?: {
-                uniqueness: boolean;
-                completeness: number;
-                accuracy?: {
-                    source: string;
-                    threshold: number;
-                } | undefined;
-            } | undefined;
-            group?: string | undefined;
-            conditionalRequired?: string | undefined;
-            inlineHelpText?: string | undefined;
-            trackFeedHistory?: boolean | undefined;
-            caseSensitive?: boolean | undefined;
-            autonumberFormat?: string | undefined;
-        }>;
-        label?: string | undefined;
-        pluralLabel?: string | undefined;
-        description?: string | undefined;
-        icon?: string | undefined;
-        namespace?: string | undefined;
-        tags?: string[] | undefined;
-        tableName?: string | undefined;
-        indexes?: {
-            fields: string[];
-            type: "hash" | "btree" | "gin" | "gist" | "fulltext";
-            unique: boolean;
-            name?: string | undefined;
-            partial?: string | undefined;
-        }[] | undefined;
-        tenancy?: {
-            enabled: boolean;
-            strategy: "shared" | "isolated" | "hybrid";
-            tenantField: string;
-            crossTenantAccess: boolean;
-        } | undefined;
-        softDelete?: {
-            enabled: boolean;
-            field: string;
-            cascadeDelete: boolean;
-        } | undefined;
-        versioning?: {
-            enabled: boolean;
-            strategy: "snapshot" | "delta" | "event-sourcing";
-            versionField: string;
-            retentionDays?: number | undefined;
-        } | undefined;
-        partitioning?: {
-            enabled: boolean;
-            strategy: "hash" | "range" | "list";
-            key: string;
-            interval?: string | undefined;
-        } | undefined;
-        cdc?: {
-            enabled: boolean;
-            events: ("update" | "delete" | "insert")[];
-            destination: string;
-        } | undefined;
-        validations?: _objectstack_spec_data.BaseValidationRuleShape[] | undefined;
-        stateMachines?: Record<string, {
-            id: string;
-            initial: string;
-            states: Record<string, StateNodeConfig>;
-            description?: string | undefined;
-            contextSchema?: Record<string, unknown> | undefined;
-            on?: Record<string, string | {
-                target?: string | undefined;
-                cond?: string | {
-                    type: string;
-                    params?: Record<string, unknown> | undefined;
-                } | undefined;
-                actions?: (string | {
-                    type: string;
-                    params?: Record<string, unknown> | undefined;
-                })[] | undefined;
-                description?: string | undefined;
-            } | {
-                target?: string | undefined;
-                cond?: string | {
-                    type: string;
-                    params?: Record<string, unknown> | undefined;
-                } | undefined;
-                actions?: (string | {
-                    type: string;
-                    params?: Record<string, unknown> | undefined;
-                })[] | undefined;
-                description?: string | undefined;
-            }[]> | undefined;
-        }> | undefined;
-        displayNameField?: string | undefined;
-        recordName?: {
-            type: "text" | "autonumber";
-            displayFormat?: string | undefined;
-            startNumber?: number | undefined;
-        } | undefined;
-        titleFormat?: string | undefined;
-        compactLayout?: string[] | undefined;
-        search?: {
-            fields: string[];
-            displayFields?: string[] | undefined;
-            filters?: string[] | undefined;
-        } | undefined;
-        enable?: {
-            trackHistory: boolean;
-            searchable: boolean;
-            apiEnabled: boolean;
-            files: boolean;
-            feeds: boolean;
-            activities: boolean;
-            trash: boolean;
-            mru: boolean;
-            clone: boolean;
-            apiMethods?: ("search" | "list" | "update" | "delete" | "upsert" | "history" | "get" | "create" | "bulk" | "aggregate" | "restore" | "purge" | "import" | "export")[] | undefined;
-        } | undefined;
-        recordTypes?: string[] | undefined;
-        sharingModel?: "full" | "private" | "read" | "read_write" | undefined;
-        keyPrefix?: string | undefined;
-        actions?: {
-            name: string;
-            label: string;
-            type: "url" | "flow" | "api" | "script" | "modal";
-            refreshAfter: boolean;
-            objectName?: string | undefined;
-            icon?: string | undefined;
-            locations?: ("list_toolbar" | "list_item" | "record_header" | "record_more" | "record_related" | "global_nav")[] | undefined;
-            component?: "action:button" | "action:icon" | "action:menu" | "action:group" | undefined;
-            target?: string | undefined;
-            execute?: string | undefined;
-            params?: {
-                name: string;
-                label: string;
-                type: "number" | "boolean" | "date" | "lookup" | "file" | "url" | "json" | "text" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "currency" | "percent" | "datetime" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "master_detail" | "tree" | "image" | "avatar" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "code" | "color" | "rating" | "slider" | "signature" | "qrcode" | "progress" | "tags" | "vector";
-                required: boolean;
-                options?: {
-                    label: string;
-                    value: string;
-                }[] | undefined;
-            }[] | undefined;
-            variant?: "link" | "primary" | "secondary" | "danger" | "ghost" | undefined;
-            confirmText?: string | undefined;
-            successMessage?: string | undefined;
-            visible?: string | undefined;
-            disabled?: string | boolean | undefined;
-            shortcut?: string | undefined;
-            bulkEnabled?: boolean | undefined;
-            timeout?: number | undefined;
-            aria?: {
-                ariaLabel?: string | undefined;
-                ariaDescribedBy?: string | undefined;
-                role?: string | undefined;
-            } | undefined;
-        }[] | undefined;
-    } | {
-        name: string;
-        label: string;
-        active: boolean;
-        isDefault: boolean;
-        version?: string | undefined;
-        description?: string | undefined;
-        icon?: string | undefined;
-        branding?: {
-            primaryColor?: string | undefined;
-            logo?: string | undefined;
-            favicon?: string | undefined;
-        } | undefined;
-        navigation?: any[] | undefined;
-        areas?: {
-            id: string;
-            label: string;
-            navigation: any[];
-            icon?: string | undefined;
-            order?: number | undefined;
-            description?: string | undefined;
-            visible?: string | undefined;
-            requiredPermissions?: string[] | undefined;
-        }[] | undefined;
-        homePageId?: string | undefined;
-        requiredPermissions?: string[] | undefined;
-        objects?: unknown[] | undefined;
-        apis?: unknown[] | undefined;
-        sharing?: {
-            enabled: boolean;
-            allowAnonymous: boolean;
-            publicLink?: string | undefined;
-            password?: string | undefined;
-            allowedDomains?: string[] | undefined;
-            expiresAt?: string | undefined;
-        } | undefined;
-        embed?: {
-            enabled: boolean;
-            width: string;
-            height: string;
-            showHeader: boolean;
-            showNavigation: boolean;
-            responsive: boolean;
-            allowedOrigins?: string[] | undefined;
-        } | undefined;
-        mobileNavigation?: {
-            mode: "drawer" | "bottom_nav" | "hamburger";
-            bottomNavItems?: string[] | undefined;
-        } | undefined;
-        aria?: {
-            ariaLabel?: string | undefined;
-            ariaDescribedBy?: string | undefined;
-            role?: string | undefined;
-        } | undefined;
-    } | {
-        manifest: {
-            id: string;
-            defaultDatasource: string;
-            version: string;
-            type: "theme" | "app" | "agent" | "driver" | "server" | "ui" | "module" | "objectql" | "plugin" | "gateway" | "adapter";
-            name: string;
-            namespace?: string | undefined;
-            description?: string | undefined;
-            permissions?: string[] | undefined;
-            objects?: string[] | undefined;
-            datasources?: string[] | undefined;
-            dependencies?: Record<string, string> | undefined;
-            configuration?: {
-                properties: Record<string, {
-                    type: "string" | "number" | "boolean" | "object" | "array";
-                    default?: unknown;
-                    description?: string | undefined;
-                    required?: boolean | undefined;
-                    secret?: boolean | undefined;
-                    enum?: string[] | undefined;
-                }>;
-                title?: string | undefined;
-            } | undefined;
-            contributes?: {
-                kinds?: {
-                    id: string;
-                    globs: string[];
-                    description?: string | undefined;
-                }[] | undefined;
-                events?: string[] | undefined;
-                menus?: Record<string, {
-                    id: string;
-                    label: string;
-                    command?: string | undefined;
-                }[]> | undefined;
-                themes?: {
-                    id: string;
-                    label: string;
-                    path: string;
-                }[] | undefined;
-                translations?: {
-                    locale: string;
-                    path: string;
-                }[] | undefined;
-                actions?: {
-                    name: string;
-                    label?: string | undefined;
-                    description?: string | undefined;
-                    input?: unknown;
-                    output?: unknown;
-                }[] | undefined;
-                drivers?: {
-                    id: string;
-                    label: string;
-                    description?: string | undefined;
-                }[] | undefined;
-                fieldTypes?: {
-                    name: string;
-                    label: string;
-                    description?: string | undefined;
-                }[] | undefined;
-                functions?: {
-                    name: string;
-                    description?: string | undefined;
-                    args?: string[] | undefined;
-                    returnType?: string | undefined;
-                }[] | undefined;
-                routes?: {
-                    prefix: string;
-                    service: string;
-                    methods?: string[] | undefined;
-                }[] | undefined;
-                commands?: {
-                    name: string;
-                    description?: string | undefined;
-                    module?: string | undefined;
-                }[] | undefined;
-            } | undefined;
-            data?: {
-                object: string;
-                externalId: string;
-                mode: "update" | "upsert" | "insert" | "replace" | "ignore";
-                env: ("prod" | "dev" | "test")[];
-                records: Record<string, unknown>[];
-            }[] | undefined;
-            capabilities?: {
-                implements?: {
-                    protocol: {
-                        id: string;
-                        label: string;
-                        version: {
-                            major: number;
-                            minor: number;
-                            patch: number;
-                        };
-                        specification?: string | undefined;
-                        description?: string | undefined;
-                    };
-                    conformance: "partial" | "full" | "deprecated" | "experimental";
-                    certified: boolean;
-                    implementedFeatures?: string[] | undefined;
-                    features?: {
-                        name: string;
-                        enabled: boolean;
-                        description?: string | undefined;
-                        sinceVersion?: string | undefined;
-                        deprecatedSince?: string | undefined;
-                    }[] | undefined;
-                    metadata?: Record<string, unknown> | undefined;
-                    certificationDate?: string | undefined;
-                }[] | undefined;
-                provides?: {
-                    id: string;
-                    name: string;
-                    version: {
-                        major: number;
-                        minor: number;
-                        patch: number;
-                    };
-                    methods: {
-                        name: string;
-                        async: boolean;
-                        description?: string | undefined;
-                        parameters?: {
-                            name: string;
-                            type: string;
-                            required: boolean;
-                            description?: string | undefined;
-                        }[] | undefined;
-                        returnType?: string | undefined;
-                    }[];
-                    stability: "experimental" | "alpha" | "stable" | "beta";
-                    description?: string | undefined;
-                    events?: {
-                        name: string;
-                        description?: string | undefined;
-                        payload?: string | undefined;
-                    }[] | undefined;
-                }[] | undefined;
-                requires?: {
-                    pluginId: string;
-                    version: string;
-                    optional: boolean;
-                    reason?: string | undefined;
-                    requiredCapabilities?: string[] | undefined;
-                }[] | undefined;
-                extensionPoints?: {
-                    id: string;
-                    name: string;
-                    type: "provider" | "action" | "hook" | "widget" | "transformer" | "validator" | "decorator";
-                    cardinality: "multiple" | "single";
-                    description?: string | undefined;
-                    contract?: {
-                        input?: string | undefined;
-                        output?: string | undefined;
-                        signature?: string | undefined;
-                    } | undefined;
-                }[] | undefined;
-                extensions?: {
-                    targetPluginId: string;
-                    extensionPointId: string;
-                    implementation: string;
-                    priority: number;
-                }[] | undefined;
-            } | undefined;
-            extensions?: Record<string, unknown> | undefined;
-            loading?: {
-                strategy: "lazy" | "parallel" | "eager" | "deferred" | "on-demand";
-                preload?: {
-                    enabled: boolean;
-                    priority: number;
-                    resources?: ("dependencies" | "code" | "metadata" | "assets" | "services")[] | undefined;
-                    conditions?: {
-                        routes?: string[] | undefined;
-                        roles?: string[] | undefined;
-                        deviceType?: ("desktop" | "mobile" | "tablet")[] | undefined;
-                        minNetworkSpeed?: "slow-2g" | "2g" | "3g" | "4g" | undefined;
-                    } | undefined;
-                } | undefined;
-                codeSplitting?: {
-                    enabled: boolean;
-                    strategy: "custom" | "size" | "route" | "feature";
-                    chunkNaming: "hashed" | "sequential" | "named";
-                    maxChunkSize?: number | undefined;
-                    sharedDependencies?: {
-                        enabled: boolean;
-                        minChunks: number;
-                    } | undefined;
-                } | undefined;
-                dynamicImport?: {
-                    enabled: boolean;
-                    mode: "lazy" | "eager" | "async" | "sync";
-                    prefetch: boolean;
-                    preload: boolean;
-                    timeout: number;
-                    webpackChunkName?: string | undefined;
-                    retry?: {
-                        enabled: boolean;
-                        maxAttempts: number;
-                        backoffMs: number;
-                    } | undefined;
-                } | undefined;
-                initialization?: {
-                    mode: "parallel" | "sequential" | "async" | "sync";
-                    timeout: number;
-                    priority: number;
-                    critical: boolean;
-                    retry?: {
-                        enabled: boolean;
-                        maxAttempts: number;
-                        backoffMs: number;
-                    } | undefined;
-                    healthCheckInterval?: number | undefined;
-                } | undefined;
-                dependencyResolution?: {
-                    strategy: "strict" | "pinned" | "latest" | "compatible";
-                    conflictResolution: "latest" | "manual" | "fail" | "oldest";
-                    circularDependencies: "warn" | "error" | "allow";
-                    peerDependencies?: {
-                        resolve: boolean;
-                        onMissing: "warn" | "error" | "ignore";
-                        onMismatch: "warn" | "error" | "ignore";
-                    } | undefined;
-                    optionalDependencies?: {
-                        load: boolean;
-                        onFailure: "warn" | "ignore";
-                    } | undefined;
-                } | undefined;
-                hotReload?: {
-                    enabled: boolean;
-                    environment: "development" | "production" | "staging";
-                    strategy: "partial" | "full" | "state-preserve";
-                    debounceMs: number;
-                    preserveState: boolean;
-                    watchPatterns?: string[] | undefined;
-                    ignorePatterns?: string[] | undefined;
-                    stateSerialization?: {
-                        enabled: boolean;
-                        handler?: string | undefined;
-                    } | undefined;
-                    hooks?: {
-                        beforeReload?: string | undefined;
-                        afterReload?: string | undefined;
-                        onError?: string | undefined;
-                    } | undefined;
-                    productionSafety?: {
-                        healthValidation: boolean;
-                        rollbackOnFailure: boolean;
-                        healthTimeout: number;
-                        drainConnections: boolean;
-                        drainTimeout: number;
-                        maxConcurrentReloads: number;
-                        minReloadInterval: number;
-                    } | undefined;
-                } | undefined;
-                caching?: {
-                    enabled: boolean;
-                    storage: "hybrid" | "indexeddb" | "memory" | "disk";
-                    keyStrategy: "hash" | "version" | "timestamp";
-                    ttl?: number | undefined;
-                    maxSize?: number | undefined;
-                    invalidateOn?: ("error" | "manual" | "version-change" | "dependency-change")[] | undefined;
-                    compression?: {
-                        enabled: boolean;
-                        algorithm: "gzip" | "brotli" | "deflate";
-                    } | undefined;
-                } | undefined;
-                sandboxing?: {
-                    enabled: boolean;
-                    scope: "automation-only" | "untrusted-only" | "all-plugins";
-                    isolationLevel: "none" | "process" | "vm" | "iframe" | "web-worker";
-                    allowedCapabilities?: string[] | undefined;
-                    resourceQuotas?: {
-                        maxMemoryMB?: number | undefined;
-                        maxCpuTimeMs?: number | undefined;
-                        maxFileDescriptors?: number | undefined;
-                        maxNetworkKBps?: number | undefined;
-                    } | undefined;
-                    permissions?: {
-                        allowedAPIs?: string[] | undefined;
-                        allowedPaths?: string[] | undefined;
-                        allowedEndpoints?: string[] | undefined;
-                        allowedEnvVars?: string[] | undefined;
-                    } | undefined;
-                    ipc?: {
-                        enabled: boolean;
-                        transport: "memory" | "message-port" | "unix-socket" | "tcp";
-                        maxMessageSize: number;
-                        timeout: number;
-                        allowedServices?: string[] | undefined;
-                    } | undefined;
-                } | undefined;
-                monitoring?: {
-                    enabled: boolean;
-                    samplingRate: number;
-                    reportingInterval: number;
-                    onBudgetViolation: "warn" | "error" | "ignore";
-                    metrics?: ("load-time" | "init-time" | "memory-usage" | "cpu-usage" | "api-calls" | "error-rate" | "cache-hit-rate")[] | undefined;
-                    budgets?: {
-                        maxLoadTimeMs?: number | undefined;
-                        maxInitTimeMs?: number | undefined;
-                        maxMemoryMB?: number | undefined;
-                    } | undefined;
-                } | undefined;
-            } | undefined;
-            engine?: {
-                objectstack: string;
-            } | undefined;
-        };
-        status: "disabled" | "error" | "installed" | "installing" | "upgrading" | "uninstalling";
-        enabled: boolean;
-        installedAt?: string | undefined;
-        updatedAt?: string | undefined;
-        installedVersion?: string | undefined;
-        previousVersion?: string | undefined;
-        statusChangedAt?: string | undefined;
-        errorMessage?: string | undefined;
-        settings?: Record<string, unknown> | undefined;
-        upgradeHistory?: {
-            fromVersion: string;
-            toVersion: string;
-            upgradedAt: string;
-            status: "success" | "failed" | "rolled_back";
-            migrationLog?: string[] | undefined;
-        }[] | undefined;
-        registeredNamespaces?: string[] | undefined;
-    } | {
-        id: string;
-        defaultDatasource: string;
-        version: string;
-        type: "theme" | "app" | "agent" | "driver" | "server" | "ui" | "module" | "objectql" | "plugin" | "gateway" | "adapter";
-        name: string;
-        namespace?: string | undefined;
-        description?: string | undefined;
-        permissions?: string[] | undefined;
-        objects?: string[] | undefined;
-        datasources?: string[] | undefined;
-        dependencies?: Record<string, string> | undefined;
-        configuration?: {
-            properties: Record<string, {
-                type: "string" | "number" | "boolean" | "object" | "array";
-                default?: unknown;
-                description?: string | undefined;
-                required?: boolean | undefined;
-                secret?: boolean | undefined;
-                enum?: string[] | undefined;
-            }>;
-            title?: string | undefined;
-        } | undefined;
-        contributes?: {
-            kinds?: {
-                id: string;
-                globs: string[];
-                description?: string | undefined;
-            }[] | undefined;
-            events?: string[] | undefined;
-            menus?: Record<string, {
-                id: string;
-                label: string;
-                command?: string | undefined;
-            }[]> | undefined;
-            themes?: {
-                id: string;
-                label: string;
-                path: string;
-            }[] | undefined;
-            translations?: {
-                locale: string;
-                path: string;
-            }[] | undefined;
-            actions?: {
-                name: string;
-                label?: string | undefined;
-                description?: string | undefined;
-                input?: unknown;
-                output?: unknown;
-            }[] | undefined;
-            drivers?: {
-                id: string;
-                label: string;
-                description?: string | undefined;
-            }[] | undefined;
-            fieldTypes?: {
-                name: string;
-                label: string;
-                description?: string | undefined;
-            }[] | undefined;
-            functions?: {
-                name: string;
-                description?: string | undefined;
-                args?: string[] | undefined;
-                returnType?: string | undefined;
-            }[] | undefined;
-            routes?: {
-                prefix: string;
-                service: string;
-                methods?: string[] | undefined;
-            }[] | undefined;
-            commands?: {
-                name: string;
-                description?: string | undefined;
-                module?: string | undefined;
-            }[] | undefined;
-        } | undefined;
-        data?: {
-            object: string;
-            externalId: string;
-            mode: "update" | "upsert" | "insert" | "replace" | "ignore";
-            env: ("prod" | "dev" | "test")[];
-            records: Record<string, unknown>[];
-        }[] | undefined;
-        capabilities?: {
-            implements?: {
-                protocol: {
-                    id: string;
-                    label: string;
-                    version: {
-                        major: number;
-                        minor: number;
-                        patch: number;
-                    };
-                    specification?: string | undefined;
-                    description?: string | undefined;
-                };
-                conformance: "partial" | "full" | "deprecated" | "experimental";
-                certified: boolean;
-                implementedFeatures?: string[] | undefined;
-                features?: {
-                    name: string;
-                    enabled: boolean;
-                    description?: string | undefined;
-                    sinceVersion?: string | undefined;
-                    deprecatedSince?: string | undefined;
-                }[] | undefined;
-                metadata?: Record<string, unknown> | undefined;
-                certificationDate?: string | undefined;
-            }[] | undefined;
-            provides?: {
-                id: string;
-                name: string;
-                version: {
-                    major: number;
-                    minor: number;
-                    patch: number;
-                };
-                methods: {
-                    name: string;
-                    async: boolean;
-                    description?: string | undefined;
-                    parameters?: {
-                        name: string;
-                        type: string;
-                        required: boolean;
-                        description?: string | undefined;
-                    }[] | undefined;
-                    returnType?: string | undefined;
-                }[];
-                stability: "experimental" | "alpha" | "stable" | "beta";
-                description?: string | undefined;
-                events?: {
-                    name: string;
-                    description?: string | undefined;
-                    payload?: string | undefined;
-                }[] | undefined;
-            }[] | undefined;
-            requires?: {
-                pluginId: string;
-                version: string;
-                optional: boolean;
-                reason?: string | undefined;
-                requiredCapabilities?: string[] | undefined;
-            }[] | undefined;
-            extensionPoints?: {
-                id: string;
-                name: string;
-                type: "provider" | "action" | "hook" | "widget" | "transformer" | "validator" | "decorator";
-                cardinality: "multiple" | "single";
-                description?: string | undefined;
-                contract?: {
-                    input?: string | undefined;
-                    output?: string | undefined;
-                    signature?: string | undefined;
-                } | undefined;
-            }[] | undefined;
-            extensions?: {
-                targetPluginId: string;
-                extensionPointId: string;
-                implementation: string;
-                priority: number;
-            }[] | undefined;
-        } | undefined;
-        extensions?: Record<string, unknown> | undefined;
-        loading?: {
-            strategy: "lazy" | "parallel" | "eager" | "deferred" | "on-demand";
-            preload?: {
-                enabled: boolean;
-                priority: number;
-                resources?: ("dependencies" | "code" | "metadata" | "assets" | "services")[] | undefined;
-                conditions?: {
-                    routes?: string[] | undefined;
-                    roles?: string[] | undefined;
-                    deviceType?: ("desktop" | "mobile" | "tablet")[] | undefined;
-                    minNetworkSpeed?: "slow-2g" | "2g" | "3g" | "4g" | undefined;
-                } | undefined;
-            } | undefined;
-            codeSplitting?: {
-                enabled: boolean;
-                strategy: "custom" | "size" | "route" | "feature";
-                chunkNaming: "hashed" | "sequential" | "named";
-                maxChunkSize?: number | undefined;
-                sharedDependencies?: {
-                    enabled: boolean;
-                    minChunks: number;
-                } | undefined;
-            } | undefined;
-            dynamicImport?: {
-                enabled: boolean;
-                mode: "lazy" | "eager" | "async" | "sync";
-                prefetch: boolean;
-                preload: boolean;
-                timeout: number;
-                webpackChunkName?: string | undefined;
-                retry?: {
-                    enabled: boolean;
-                    maxAttempts: number;
-                    backoffMs: number;
-                } | undefined;
-            } | undefined;
-            initialization?: {
-                mode: "parallel" | "sequential" | "async" | "sync";
-                timeout: number;
-                priority: number;
-                critical: boolean;
-                retry?: {
-                    enabled: boolean;
-                    maxAttempts: number;
-                    backoffMs: number;
-                } | undefined;
-                healthCheckInterval?: number | undefined;
-            } | undefined;
-            dependencyResolution?: {
-                strategy: "strict" | "pinned" | "latest" | "compatible";
-                conflictResolution: "latest" | "manual" | "fail" | "oldest";
-                circularDependencies: "warn" | "error" | "allow";
-                peerDependencies?: {
-                    resolve: boolean;
-                    onMissing: "warn" | "error" | "ignore";
-                    onMismatch: "warn" | "error" | "ignore";
-                } | undefined;
-                optionalDependencies?: {
-                    load: boolean;
-                    onFailure: "warn" | "ignore";
-                } | undefined;
-            } | undefined;
-            hotReload?: {
-                enabled: boolean;
-                environment: "development" | "production" | "staging";
-                strategy: "partial" | "full" | "state-preserve";
-                debounceMs: number;
-                preserveState: boolean;
-                watchPatterns?: string[] | undefined;
-                ignorePatterns?: string[] | undefined;
-                stateSerialization?: {
-                    enabled: boolean;
-                    handler?: string | undefined;
-                } | undefined;
-                hooks?: {
-                    beforeReload?: string | undefined;
-                    afterReload?: string | undefined;
-                    onError?: string | undefined;
-                } | undefined;
-                productionSafety?: {
-                    healthValidation: boolean;
-                    rollbackOnFailure: boolean;
-                    healthTimeout: number;
-                    drainConnections: boolean;
-                    drainTimeout: number;
-                    maxConcurrentReloads: number;
-                    minReloadInterval: number;
-                } | undefined;
-            } | undefined;
-            caching?: {
-                enabled: boolean;
-                storage: "hybrid" | "indexeddb" | "memory" | "disk";
-                keyStrategy: "hash" | "version" | "timestamp";
-                ttl?: number | undefined;
-                maxSize?: number | undefined;
-                invalidateOn?: ("error" | "manual" | "version-change" | "dependency-change")[] | undefined;
-                compression?: {
-                    enabled: boolean;
-                    algorithm: "gzip" | "brotli" | "deflate";
-                } | undefined;
-            } | undefined;
-            sandboxing?: {
-                enabled: boolean;
-                scope: "automation-only" | "untrusted-only" | "all-plugins";
-                isolationLevel: "none" | "process" | "vm" | "iframe" | "web-worker";
-                allowedCapabilities?: string[] | undefined;
-                resourceQuotas?: {
-                    maxMemoryMB?: number | undefined;
-                    maxCpuTimeMs?: number | undefined;
-                    maxFileDescriptors?: number | undefined;
-                    maxNetworkKBps?: number | undefined;
-                } | undefined;
-                permissions?: {
-                    allowedAPIs?: string[] | undefined;
-                    allowedPaths?: string[] | undefined;
-                    allowedEndpoints?: string[] | undefined;
-                    allowedEnvVars?: string[] | undefined;
-                } | undefined;
-                ipc?: {
-                    enabled: boolean;
-                    transport: "memory" | "message-port" | "unix-socket" | "tcp";
-                    maxMessageSize: number;
-                    timeout: number;
-                    allowedServices?: string[] | undefined;
-                } | undefined;
-            } | undefined;
-            monitoring?: {
-                enabled: boolean;
-                samplingRate: number;
-                reportingInterval: number;
-                onBudgetViolation: "warn" | "error" | "ignore";
-                metrics?: ("load-time" | "init-time" | "memory-usage" | "cpu-usage" | "api-calls" | "error-rate" | "cache-hit-rate")[] | undefined;
-                budgets?: {
-                    maxLoadTimeMs?: number | undefined;
-                    maxInitTimeMs?: number | undefined;
-                    maxMemoryMB?: number | undefined;
-                } | undefined;
-            } | undefined;
-        } | undefined;
-        engine?: {
-            objectstack: string;
-        } | undefined;
-    };
+    validate(type: string, item: any): unknown;
     /**
      * Universal Unregister Method
      */
-    static unregisterItem(type: string, name: string): void;
+    unregisterItem(type: string, name: string): void;
     /**
      * Universal Get Method
      */
-    static getItem<T>(type: string, name: string): T | undefined;
+    getItem<T>(type: string, name: string): T | undefined;
     /**
      * Universal List Method
      */
-    static listItems<T>(type: string, packageId?: string): T[];
+    listItems<T>(type: string, packageId?: string): T[];
     /**
      * Get all registered metadata types (Kinds)
      */
-    static getRegisteredTypes(): string[];
-    static installPackage(manifest: ObjectStackManifest, settings?: Record<string, any>): InstalledPackage;
-    static uninstallPackage(id: string): boolean;
-    static getPackage(id: string): InstalledPackage | undefined;
-    static getAllPackages(): InstalledPackage[];
-    static enablePackage(id: string): InstalledPackage | undefined;
-    static disablePackage(id: string): InstalledPackage | undefined;
-    static registerApp(app: any, packageId?: string): void;
-    static getApp(name: string): any;
-    static getAllApps(): any[];
-    static registerPlugin(manifest: ObjectStackManifest): void;
-    static getAllPlugins(): ObjectStackManifest[];
-    static registerKind(kind: {
+    getRegisteredTypes(): string[];
+    installPackage(manifest: ObjectStackManifest, settings?: Record<string, any>): InstalledPackage;
+    uninstallPackage(id: string): boolean;
+    getPackage(id: string): InstalledPackage | undefined;
+    getAllPackages(): InstalledPackage[];
+    enablePackage(id: string): InstalledPackage | undefined;
+    disablePackage(id: string): InstalledPackage | undefined;
+    registerApp(app: any, packageId?: string): void;
+    getApp(name: string): any;
+    getAllApps(): any[];
+    registerPlugin(manifest: ObjectStackManifest): void;
+    getAllPlugins(): ObjectStackManifest[];
+    registerKind(kind: {
         id: string;
         globs: string[];
     }): void;
-    static getAllKinds(): {
+    getAllKinds(): {
         id: string;
         globs: string[];
     }[];
     /**
      * Clear all registry state. Use only for testing.
      */
-    static reset(): void;
+    reset(): void;
 }
 
 declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     private engine;
     private getServicesRegistry?;
     private getFeedService?;
-    constructor(engine: IDataEngine, getServicesRegistry?: () => Map<string, any>, getFeedService?: () => IFeedService | undefined);
+    /**
+     * Project scope applied to sys_metadata reads/writes. When undefined
+     * (single-kernel deployments), rows land in / come from the
+     * platform-global bucket (`project_id IS NULL`). When set, every
+     * saveMetaItem insert/update and loadMetaFromDb query is filtered by
+     * `project_id = projectId`, so per-project kernels see only their own
+     * metadata even if several projects share the same physical database.
+     */
+    private projectId?;
+    constructor(engine: IDataEngine, getServicesRegistry?: () => Map<string, any>, getFeedService?: () => IFeedService | undefined, projectId?: string);
+    /**
+     * One-time guard for ensuring the overlay-uniqueness UNIQUE INDEX exists
+     * on `sys_metadata`. ADR-0005: scopes overlays by
+     * `(type, name, organization_id, project_id, scope)` for active rows only.
+     * Idempotent SQL — safe to attempt on every protocol instance.
+     *
+     * Inlined here (rather than importing from @objectstack/metadata/migrations)
+     * to avoid a circular dependency: metadata already depends on objectql.
+     */
+    private overlayIndexEnsured;
+    private ensureOverlayIndex;
+    /**
+     * Exposes the project scope the protocol is bound to. Consumers like
+     * the HTTP dispatcher use this to decide whether to trust the process-
+     * wide SchemaRegistry or whether they must route a read through the
+     * protocol's project_id-filtered lookup.
+     */
+    getProjectId(): string | undefined;
     private requireFeedService;
     getDiscovery(): Promise<{
         version: string;
@@ -1266,7 +306,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         };
         services: Record<string, {
             enabled: boolean;
-            status: "degraded" | "stub" | "available" | "registered" | "unavailable";
+            status: "available" | "registered" | "unavailable" | "degraded" | "stub";
             handlerReady?: boolean | undefined;
             route?: string | undefined;
             provider?: string | undefined;
@@ -1290,6 +330,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     getMetaItems(request: {
         type: string;
         packageId?: string;
+        organizationId?: string;
     }): Promise<{
         type: string;
         items: unknown[];
@@ -1298,6 +339,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         type: string;
         name: string;
         packageId?: string;
+        organizationId?: string;
     }): Promise<{
         type: string;
         name: string;
@@ -1335,7 +377,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                     label: string | undefined;
                     required: boolean;
                     readonly: boolean;
-                    type: "number" | "boolean" | "tags" | "date" | "lookup" | "file" | "url" | "json" | "text" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "currency" | "percent" | "datetime" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "master_detail" | "tree" | "image" | "avatar" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "code" | "color" | "rating" | "slider" | "signature" | "qrcode" | "progress" | "vector";
+                    type: "number" | "boolean" | "tags" | "date" | "file" | "code" | "datetime" | "signature" | "progress" | "url" | "text" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "currency" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "avatar" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "json" | "color" | "rating" | "slider" | "qrcode" | "vector";
                     colSpan: number;
                 }[];
             }[];
@@ -1345,6 +387,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     findData(request: {
         object: string;
         query?: any;
+        context?: any;
     }): Promise<{
         object: string;
         records: any[];
@@ -1356,6 +399,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         id: string;
         expand?: string | string[];
         select?: string | string[];
+        context?: any;
     }): Promise<{
         object: string;
         id: string;
@@ -1364,6 +408,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     createData(request: {
         object: string;
         data: any;
+        context?: any;
     }): Promise<{
         object: string;
         id: any;
@@ -1373,6 +418,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         object: string;
         id: string;
         data: any;
+        context?: any;
     }): Promise<{
         object: string;
         id: string;
@@ -1381,11 +427,86 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     deleteData(request: {
         object: string;
         id: string;
+        context?: any;
     }): Promise<{
         object: string;
         id: string;
         success: boolean;
     }>;
+    /**
+     * Cross-object substring search across all registered objects that opt in
+     * via `enable.searchable !== false` and `enable.apiEnabled !== false`.
+     * Searches text-like fields (text/textarea/email/url/phone/markdown/html/string)
+     * whose `searchable: true` flag is set, falling back to the object's
+     * `displayNameField` (or `name`) when no fields are explicitly searchable.
+     *
+     * The query is split into whitespace-separated terms; each term must match
+     * (case-insensitive LIKE) at least one searchable field. RBAC/RLS is
+     * enforced by forwarding the caller's `context` to `engine.find` so users
+     * only see records they are entitled to read.
+     */
+    searchAll(request: {
+        q: string;
+        objects?: string[];
+        limit?: number;
+        perObject?: number;
+        context?: any;
+    }): Promise<{
+        query: string;
+        hits: Array<{
+            object: string;
+            id: string;
+            title: string;
+            snippet?: string;
+            record: any;
+        }>;
+        totalObjects: number;
+        totalHits: number;
+        truncated: boolean;
+    }>;
+    /**
+     * Convert a qualified Lead into an Account + Contact (+ optional
+     * Opportunity) and mark the Lead as converted. Mirrors the Salesforce
+     * lead-conversion model:
+     *
+     *   - If `accountId` is provided, the lead's company info is NOT used
+     *     to create a new account; the new contact and opportunity link to
+     *     the existing account instead.
+     *   - If `contactId` is provided, no new contact is created either —
+     *     useful when the lead is a new contact at an existing account.
+     *   - `createOpportunity` defaults to true; pass `false` to convert
+     *     without producing an opportunity (some teams convert "logos
+     *     only" first).
+     *   - Lead is updated atomically: `is_converted=true`,
+     *     `converted_account`/`converted_contact`/`converted_opportunity`
+     *     pointers, `converted_date`, and `status='converted'`.
+     *
+     * Atomicity is enforced via the default driver's transaction support
+     * when available; otherwise a best-effort compensation (delete
+     * already-created child records on failure) is attempted. Permission
+     * checks on each child object are inherited from the caller's
+     * execution context so SecurityPlugin still gates account/contact/
+     * opportunity creates.
+     */
+    convertLead(request: {
+        leadId: string;
+        accountId?: string;
+        contactId?: string;
+        createOpportunity?: boolean;
+        opportunity?: {
+            name?: string;
+            amount?: number;
+            close_date?: string;
+            stage?: string;
+        };
+        convertedStatus?: string;
+        context?: any;
+    }): Promise<{
+        lead: any;
+        account: any;
+        contact: any;
+        opportunity: any | null;
+    }>;
     getMetaItemCached(request: {
         type: string;
         name: string;
@@ -1405,23 +526,51 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     private mapAnalyticsOperator;
     triggerAutomation(_request: any): Promise<any>;
     deleteManyData(request: DeleteManyDataRequest): Promise<any>;
+    /**
+     * Metadata types that are customer-overridable via {@link saveMetaItem}/
+     * {@link deleteMetaItem} in project-kernel mode. Derived from the canonical
+     * registry in {@link DEFAULT_METADATA_TYPE_REGISTRY}: a type opts in by
+     * setting `allowOrgOverride: true` on its registry entry. The set is
+     * augmented with the plural form of every singular so callers using REST
+     * conventions (`/api/v1/meta/views/...`) get the same gate. See ADR-0005
+     * §"Whitelist enforcement" for the rationale and the per-type rollout
+     * checklist.
+     */
+    private static readonly OVERLAY_ALLOWED_TYPES;
+    /** Normalize plural→singular before consulting the allow-list. */
+    private static isOverlayAllowed;
     saveMetaItem(request: {
         type: string;
         name: string;
         item?: any;
+        organizationId?: string;
     }): Promise<{
         success: boolean;
         message: string;
-        warning?: undefined;
-    } | {
+    }>;
+    /**
+     * Remove a customization overlay row for the given metadata item, so the
+     * next read falls through to the artifact-loaded default. Implements the
+     * "Reset to factory default" semantic from ADR-0005. Whitelist is shared
+     * with {@link saveMetaItem}.
+     */
+    deleteMetaItem(request: {
+        type: string;
+        name: string;
+        organizationId?: string;
+    }): Promise<{
         success: boolean;
-        message: string;
-        warning: any;
+        message?: string;
+        reset?: boolean;
     }>;
     /**
      * Hydrate SchemaRegistry from the database on startup.
      * Loads all active metadata records and registers them in the in-memory registry.
      * Safe to call repeatedly — idempotent (latest DB record wins).
+     *
+     * Per ADR-0005, project-kernel mode ALSO hydrates from sys_metadata —
+     * customization overlay rows must survive restart. Scope filter
+     * (`project_id = this.projectId ?? null`) keeps tenants isolated.
      */
     loadMetaFromDb(): Promise<{
         loaded: number;
@@ -1452,6 +601,14 @@ interface HookEntry {
     object?: string | string[];
     priority: number;
     packageId?: string;
+    /**
+     * Original metadata-form `Hook` definition this entry was bound from
+     * (when registered via `bindHooksToEngine`). Pure code-paths that call
+     * `engine.registerHook` directly leave this undefined.
+     */
+    meta?: any;
+    /** Hook `name` from metadata; used for diagnostics & deduplication. */
+    hookName?: string;
 }
 /**
  * Operation Context for Middleware Chain
@@ -1494,8 +651,10 @@ declare class ObjectQL implements IDataEngine {
     private hooks;
     private middlewares;
     private actions;
+    private functions;
     private hostContext;
     private realtimeService?;
+    private _registry;
     constructor(hostContext?: Record<string, any>);
     /**
      * Service Status Report
@@ -1508,9 +667,12 @@ declare class ObjectQL implements IDataEngine {
         features: string[];
     };
     /**
-     * Expose the SchemaRegistry for plugins to register metadata
+     * Expose the SchemaRegistry for plugins to register metadata.
+     *
+     * Returns the per-engine instance, NOT the class. Each ObjectQL engine
+     * owns its registry so multi-project kernels remain isolated.
      */
-    get registry(): typeof SchemaRegistry;
+    get registry(): SchemaRegistry;
     /**
      * Load and Register a Plugin
      */
@@ -1525,7 +687,67 @@ declare class ObjectQL implements IDataEngine {
         object?: string | string[];
         priority?: number;
         packageId?: string;
+        /** Original metadata Hook definition (set by `bindHooksToEngine`). */
+        meta?: any;
+        /** Stable name from metadata (set by `bindHooksToEngine`). */
+        hookName?: string;
+    }): void;
+    /**
+     * Remove all hooks registered under a given `packageId`. Used by
+     * `bindHooksToEngine` to make re-binding (hot reload, app reinstall)
+     * idempotent, and by app uninstall flows.
+     */
+    unregisterHooksByPackage(packageId: string): number;
+    /**
+     * Register a named function handler that can later be referenced by
+     * string from a `Hook.handler` field. This is the JSON-safe form of
+     * handler binding — declarative metadata persisted to disk or shipped
+     * over the wire only carries the name.
+     */
+    registerFunction(name: string, handler: HookHandler, packageId?: string): void;
+    /** Look up a registered function by name. */
+    resolveFunction(name: string): HookHandler | undefined;
+    /** Remove all functions registered under a given `packageId`. */
+    unregisterFunctionsByPackage(packageId: string): number;
+    /**
+     * Bind a list of declarative `Hook` metadata definitions to this engine.
+     *
+     * Convenience proxy to the canonical `bindHooksToEngine` so callers do
+     * not need a separate import. Use `import { bindHooksToEngine } from
+     * '@objectstack/objectql'` directly when you want the result object.
+     */
+    bindHooks(hooks: any[] | undefined, opts?: {
+        packageId?: string;
+        functions?: Record<string, HookHandler>;
+        bodyRunner?: any;
+        strict?: boolean;
+        warnLegacyHandler?: boolean;
+        metrics?: any;
     }): void;
+    /**
+     * Install a default body-runner used when `bindHooks` is called without
+     * an explicit one. The runtime layer sets this once on each per-project
+     * engine so every binding path (template seed, metadata sync, AppPlugin)
+     * can execute hook `body.source` consistently.
+     */
+    setDefaultBodyRunner(runner: any): void;
+    /**
+     * Toggle strict hook-binding mode for this engine. When enabled, every
+     * subsequent `bindHooks` call rejects on the first unresolved hook
+     * instead of silently warning. Production runtimes should enable this.
+     */
+    setStrictHookBinding(strict: boolean): void;
+    /** Toggle deprecation warnings for hooks still using legacy `handler` ref. */
+    setWarnLegacyHandler(warn: boolean): void;
+    /**
+     * Install a metrics recorder used by every subsequent `bindHooks` call.
+     * The recorder's methods are invoked per-execution to count outcomes
+     * (success / error / timeout / capability_rejected), skips, and retries.
+     * Defaults to no-op so the engine pays zero cost when nobody is observing.
+     */
+    setHookMetricsRecorder(recorder: any): void;
+    /** Read the engine's installed metrics recorder, if any. */
+    getHookMetricsRecorder(): any;
     triggerHooks(event: string, context: HookContext): Promise<void>;
     /**
      * Register a named action on an object.
@@ -1562,6 +784,40 @@ declare class ObjectQL implements IDataEngine {
      * Build a HookContext.session from ExecutionContext
      */
     private buildSession;
+    /**
+     * Build the DriverOptions blob passed to every IDataDriver call.
+     *
+     * Always carries `tenantId` from the active ExecutionContext so the
+     * driver can enforce per-tenant isolation (SQL driver auto-scopes reads
+     * and auto-injects the tenant column on writes). Existing user-supplied
+     * shapes (transactions, AST extras) are preserved by spreading them
+     * first.
+     *
+     * System / isSystem callers may still cross tenants by clearing
+     * `tenantId` themselves on the resulting object; this helper does not
+     * mask the system path.
+     */
+    private buildDriverOptions;
+    /**
+     * Build a HookContext.api: a ScopedContext that hooks can use to
+     * read/write other objects within the same execution context.
+     * Falls back to a system-elevated empty context when no execCtx
+     * is supplied (e.g. system-triggered hooks).
+     */
+    private buildHookApi;
+    /**
+     * Apply field defaults to an incoming insert payload. Defaults that are
+     * Expression envelopes (e.g. `{ dialect: 'cel', source: 'today()' }`,
+     * `{ dialect: 'cel', source: 'os.user.id' }`) are evaluated via
+     * `ExpressionEngine` against the calling user/org/now snapshot. Static
+     * defaults are applied verbatim. Records that already supplied a value for a
+     * field are left untouched.
+     *
+     * Implements ROADMAP §M9.9b — `defaultValue` accepts Expression so authors
+     * can replace "write a hook to default to today/current-user" with a
+     * declarative `defaultValue: cel\`today()\``.
+     */
+    private applyFieldDefaults;
     /**
      * Register contribution (Manifest)
      *
@@ -1573,6 +829,12 @@ declare class ObjectQL implements IDataEngine {
      * the manifest contains UI navigation definitions (AppSchema).
      */
     registerApp(manifest: any): void;
+    /**
+     * Deep-clone an app definition, resolving objectName references in navigation
+     * items via the registry. Object names are canonical identifiers — no FQN
+     * expansion is applied.
+     */
+    private resolveNavObjectNames;
     /**
      * Register a nested plugin's metadata (objects, actions, views, etc.)
      *
@@ -1601,14 +863,11 @@ declare class ObjectQL implements IDataEngine {
      */
     getSchema(objectName: string): ServiceObject | undefined;
     /**
-     * Resolve an object name to its Fully Qualified Name (FQN).
+     * Resolve any object identifier to the physical storage name used by drivers.
      *
-     * Short names like 'task' are resolved to FQN like 'todo__task'
-     * via SchemaRegistry lookup. If no match is found, the name is
-     * returned as-is (for ad-hoc / unregistered objects).
-     *
-     * This ensures that all driver operations use a consistent key
-     * regardless of whether the caller uses the short name or FQN.
+     * Accepts the canonical short name (e.g., 'account') or, for explicit
+     * cross-package disambiguation, the canonical object name (e.g., 'account'). The result is
+     * the physical table name derived via `StorageNameMapping.resolveTableName`.
      */
     private resolveObjectName;
     /**
@@ -1672,7 +931,40 @@ declare class ObjectQL implements IDataEngine {
     delete(object: string, options?: EngineDeleteOptions): Promise<any>;
     count(object: string, query?: EngineCountOptions): Promise<number>;
     aggregate(object: string, query: EngineAggregateOptions): Promise<any[]>;
+    /**
+     * Run raw driver-specific commands (SQL for SqlDriver, REST for RestDriver, …).
+     *
+     * ⚠️ **Tenant isolation bypass.** Raw `execute()` does NOT thread the
+     * caller's `ExecutionContext.tenantId` into a `WHERE organization_id`
+     * predicate — drivers see the command verbatim. Callers MUST inline the
+     * tenant filter themselves, or restrict raw execution to genuinely global
+     * statements (schema migrations, sys_* / control-plane tables).
+     *
+     * Prefer the typed entry points (`find`, `update`, `delete`, `count`, …)
+     * whenever feasible — they auto-apply tenancy + soft-delete + audit warnings.
+     */
     execute(command: any, options?: Record<string, any>): Promise<any>;
+    /**
+     * Execute a callback inside a database transaction.
+     *
+     * The callback receives a context object that should be passed to all
+     * downstream `engine.insert/update/delete/find/findOne` calls (as
+     * `{ context: trxCtx }`). The transaction handle threads through
+     * `OperationContext.context.transaction` and the SQL driver's per-builder
+     * `.transacting(trx)` call.
+     *
+     * - If the default driver does not support `beginTransaction`, the callback
+     *   runs directly with the supplied base context (no rollback). This keeps
+     *   the API safe to call on drivers without ACID support (e.g. the
+     *   in-memory driver in tests).
+     * - On callback success the transaction is committed; on any thrown error
+     *   it is rolled back and the original error is re-thrown.
+     *
+     * Use case: multi-step operations that must be atomic (e.g. CRM
+     * `convertLead`, which creates an account + contact + opportunity + flips
+     * the lead in a single unit of work).
+     */
+    transaction<T>(callback: (trxCtx: any) => Promise<T>, baseContext?: any): Promise<T>;
     /**
      * Register a single object definition.
      *
@@ -1712,6 +1004,13 @@ declare class ObjectQL implements IDataEngine {
      * @returns The resolved DriverInterface, or undefined if no driver is available.
      */
     getDriverForObject(objectName: string): DriverInterface | undefined;
+    /**
+     * Sync all registered object schemas to their respective drivers.
+     * Call this after dynamically registering new objects at runtime
+     * (e.g. after template seeding) to ensure tables/collections exist
+     * before inserting seed data.
+     */
+    syncSchemas(): Promise<void>;
     /**
      * Get a registered driver by datasource name.
      * Alias matching @objectql/core datasource() API.
@@ -1834,6 +1133,249 @@ declare class ScopedContext {
     get transactionHandle(): unknown;
 }
 
+/**
+ * Group + aggregate raw rows according to the AST's `groupBy` /
+ * `aggregations`. When neither is present, returns the rows unchanged.
+ */
+declare function applyInMemoryAggregation(rows: any[], ast: Pick<QueryAST, 'groupBy' | 'aggregations'>): any[];
+/**
+ * Bucket a date-like value into an ISO-formatted period label. Weeks start
+ * Monday and use ISO week numbering.
+ */
+declare function bucketDateValue(value: unknown, granularity: DateGranularityValue): string;
+
+/**
+ * Hook Execution Metrics
+ *
+ * Lightweight, transport-agnostic recorder interface for per-hook execution
+ * counters and latencies. The default implementation is a no-op so the
+ * engine pays zero cost when nobody is observing.
+ *
+ * Wire a real recorder by calling `engine.setHookMetricsRecorder(recorder)`.
+ * The runtime / kernel can adapt this to Otel, Prometheus, StatsD, or
+ * whatever telemetry pipeline ships with the deployment.
+ *
+ * Recorded events:
+ *   - `recordExecution(label, outcome, durationMs)`
+ *       outcome ∈ 'success' | 'error' | 'timeout' | 'capability_rejected'
+ *   - `recordSkip(label, reason)`
+ *       reason ∈ 'condition' | 'fire_and_forget'
+ *   - `recordRetry(label, attempt)`
+ */
+type HookMetricOutcome = 'success' | 'error' | 'timeout' | 'capability_rejected';
+type HookSkipReason = 'condition' | 'fire_and_forget';
+interface HookMetricLabel {
+    /** Hook name (stable id from metadata). */
+    hook: string;
+    /** Object name the hook is bound to. May be undefined for global hooks. */
+    object?: string;
+    /** Lifecycle event (`beforeInsert`, `afterUpdate`, etc.). */
+    event?: string;
+    /** True when the handler comes from a metadata `body` (sandboxed JS). */
+    body?: boolean;
+}
+interface HookMetricsRecorder {
+    recordExecution(label: HookMetricLabel, outcome: HookMetricOutcome, durationMs: number): void;
+    recordSkip(label: HookMetricLabel, reason: HookSkipReason): void;
+    recordRetry(label: HookMetricLabel, attempt: number): void;
+}
+declare const noopHookMetricsRecorder: HookMetricsRecorder;
+/**
+ * In-memory recorder useful for tests, dev-mode dashboards, and as a
+ * starting point for adapter implementations. Aggregates counts + a
+ * rolling sum of latency per (hook, outcome).
+ */
+declare class InMemoryHookMetricsRecorder implements HookMetricsRecorder {
+    private executions;
+    private skips;
+    private retries;
+    recordExecution(label: HookMetricLabel, outcome: HookMetricOutcome, durationMs: number): void;
+    recordSkip(label: HookMetricLabel, reason: HookSkipReason): void;
+    recordRetry(label: HookMetricLabel, _attempt: number): void;
+    snapshot(): {
+        executions: Array<{
+            hook: string;
+            outcome: HookMetricOutcome;
+            count: number;
+            totalMs: number;
+        }>;
+        skips: Array<{
+            hook: string;
+            reason: HookSkipReason;
+            count: number;
+        }>;
+        retries: Array<{
+            hook: string;
+            count: number;
+        }>;
+    };
+    reset(): void;
+}
+
+/**
+ * Hook Binder
+ *
+ * Single, canonical entry point that turns declarative `Hook` metadata into
+ * runtime registrations on the `ObjectQL` engine. Every metadata source —
+ * `defineStack({ hooks })` (consumed by `AppPlugin`), the per-project
+ * template seeder (`MultiProjectPlugin`), and the metadata service
+ * (`ObjectQLPlugin.loadMetadataFromService`) — funnels through here so
+ * that:
+ *
+ * - Inline function handlers and string-named handlers share one resolver.
+ * - Declarative fields (`condition`, `async`, `retryPolicy`, `timeout`,
+ *   `onError`) are honoured uniformly via `wrapDeclarativeHook`.
+ * - Hooks can be unregistered as a unit via `packageId`, enabling clean
+ *   hot-reload and app uninstall.
+ *
+ * The ObjectQL engine itself stays simple — it knows how to store and
+ * trigger handlers, but knows nothing about declarative semantics. All
+ * metadata-aware behaviour lives in this binder + the wrapper module.
+ */
+
+interface BindHooksOptions {
+    /** Owning package / app id — used for `unregisterHooksByPackage`. */
+    packageId?: string;
+    /**
+     * Optional name → function map for resolving string `handler` references.
+     * Typically supplied by `defineStack({ functions })` and merged with any
+     * functions previously registered on the engine.
+     */
+    functions?: Record<string, HookHandler>;
+    /**
+     * Optional factory that converts a metadata-only `Hook.body` (L1 expression
+     * or L2 sandboxed JS source) into an executable `HookHandler`. The runtime
+     * package wires this up using `QuickJSScriptRunner`; objectql itself stays
+     * sandbox-free so it can run in lightweight environments.
+     *
+     * If `hook.body` is set and this factory is missing, the hook is skipped
+     * with a clear error.
+     */
+    bodyRunner?: (hook: Hook) => HookHandler | undefined;
+    /**
+     * When true, treat unresolved hooks (body present but no runner, or handler
+     * string with no implementation) as fatal errors instead of warnings. Used
+     * by production runtimes to fail fast on misconfiguration. Defaults false.
+     */
+    strict?: boolean;
+    /**
+     * When true, emit a deprecation warning for every hook that still relies
+     * on a `handler` ref string instead of the metadata-only `body`. Used by
+     * the CLI (compile time) and runtime (boot time) to nudge users away from
+     * the legacy `.mjs` runtime bundle path. Defaults false.
+     */
+    warnLegacyHandler?: boolean;
+    /** Per-hook execution metrics sink. Defaults to no-op. */
+    metrics?: HookMetricsRecorder;
+    /** Logger; defaults to a silent no-op. */
+    logger?: {
+        debug: (msg: string, meta?: any) => void;
+        info: (msg: string, meta?: any) => void;
+        warn: (msg: string, meta?: any) => void;
+        error: (msg: string, meta?: any) => void;
+    };
+}
+/** Counter for stats. */
+interface BindHooksResult {
+    registered: number;
+    skipped: number;
+    errors: Array<{
+        hook: string;
+        reason: string;
+    }>;
+}
+/**
+ * Bind a list of declarative `Hook` definitions to a running ObjectQL engine.
+ *
+ * Idempotent on `(packageId, hook.name, event, object)`: re-binding the
+ * same set after a hot reload first calls `unregisterHooksByPackage`
+ * (when `packageId` is provided).
+ */
+declare function bindHooksToEngine(engine: ObjectQL, hooks: Hook[] | undefined, opts?: BindHooksOptions): BindHooksResult;
+
+/**
+ * Declarative Hook Wrappers
+ *
+ * Turns a raw `HookHandler` into one that honours the declarative metadata
+ * fields defined on `HookSchema` (`condition`, `async`, `retryPolicy`,
+ * `timeout`, `onError`). This lives outside the engine's `triggerHooks`
+ * loop so the engine stays minimal and the semantics are unit-testable in
+ * isolation.
+ *
+ * The resulting wrapped handler keeps the original `(ctx) => Promise<void>`
+ * signature, so `engine.registerHook` does not need to know anything about
+ * the metadata-driven behaviours.
+ */
+
+interface WrapDeclarativeOptions {
+    /** Logger for declarative-layer diagnostics (timeouts, retries, swallowed errors). */
+    logger?: {
+        debug: (msg: string, meta?: any) => void;
+        info: (msg: string, meta?: any) => void;
+        warn: (msg: string, meta?: any) => void;
+        error: (msg: string, meta?: any) => void;
+    };
+    /** Optional per-execution metrics sink. Defaults to no-op. */
+    metrics?: HookMetricsRecorder;
+}
+/**
+ * Wrap a hook handler so it honours the declarative fields defined on
+ * `HookSchema`. The wrapping order, from outermost to innermost, is:
+ *
+ *   1. condition  → skip when formula evaluates falsy
+ *   2. async      → fire-and-forget (after* events only)
+ *   3. retry      → repeat on throw with backoff
+ *   4. timeout    → abort if handler runs too long
+ *   5. onError    → swallow when set to 'log'
+ *
+ * The condition formula is evaluated against the most useful record-shaped
+ * payload available on the context (write payloads first, then `previous`,
+ * then a flat merge of input). Read events typically have no record yet,
+ * so a condition on a `beforeFind` will simply skip when no data is
+ * present.
+ */
+declare function wrapDeclarativeHook(meta: Hook, handler: HookHandler, opts?: WrapDeclarativeOptions): HookHandler;
+
+interface FieldValidationError {
+    field: string;
+    code: 'required' | 'min_length' | 'max_length' | 'min_value' | 'max_value' | 'invalid_email' | 'invalid_url' | 'invalid_phone' | 'invalid_number' | 'invalid_boolean' | 'invalid_date' | 'invalid_option';
+    message: string;
+    /** Allowed values for select/multiselect, when applicable. */
+    options?: string[];
+}
+declare class ValidationError extends Error {
+    readonly code = "VALIDATION_FAILED";
+    readonly fields: FieldValidationError[];
+    constructor(fields: FieldValidationError[]);
+}
+type Mode = 'insert' | 'update';
+interface FieldDef {
+    name?: string;
+    type: string;
+    required?: boolean;
+    readonly?: boolean;
+    system?: boolean;
+    multiple?: boolean;
+    maxLength?: number;
+    minLength?: number;
+    min?: number;
+    max?: number;
+    options?: Array<{
+        value: string | number;
+        label?: string;
+    } | string | number>;
+}
+/**
+ * Validate a payload against a list of declared fields. `objectSchema`
+ * comes from `ObjectQL.getRegistry().getObject(name)` and exposes a
+ * `fields` map of `{ [fieldName]: FieldDef }`.
+ *
+ * Returns void on success; throws `ValidationError` on failure.
+ */
+declare function validateRecord(objectSchema: {
+    fields?: Record<string, FieldDef>;
+} | undefined | null, data: Record<string, unknown> | undefined | null, mode: Mode): void;
+
 /**
  * MetadataFacade
  *
@@ -1843,8 +1385,14 @@ declare class ScopedContext {
  *
  * Implements the async IMetadataService interface.
  * Internally delegates to SchemaRegistry (in-memory) with Promise wrappers.
+ *
+ * Each facade is bound to a specific SchemaRegistry instance — passed in the
+ * constructor — so that multi-kernel servers can give every kernel its own
+ * metadata surface without leaking state across tenants.
  */
 declare class MetadataFacade {
+    private registry;
+    constructor(registry: SchemaRegistry);
     /**
      * Register a metadata item
      */
@@ -1887,25 +1435,86 @@ declare class MetadataFacade {
     listObjects(): Promise<any[]>;
 }
 
+/**
+ * Options for ObjectQLPlugin.
+ *
+ * `projectId` scopes all metadata writes + reads to a specific project.
+ * When set, `protocol.saveMetaItem` stamps `project_id = <projectId>` on
+ * new sys_metadata rows, and `protocol.loadMetaFromDb` filters by the same
+ * column. Leave undefined in single-kernel / self-hosted mode — rows land
+ * in the platform-global scope (project_id IS NULL).
+ */
+interface ObjectQLPluginOptions {
+    /** Optional pre-built engine. When absent, one is lazily created in init. */
+    ql?: ObjectQL;
+    /** Passed to `new ObjectQL(...)` when `ql` is not supplied. */
+    hostContext?: Record<string, any>;
+    /** Scope sys_metadata reads/writes to this project. */
+    projectId?: string;
+    /**
+     * Override the kernel's default plugin-start timeout for this plugin.
+     * Defaults to 120000 (120s). Schema sync to a remote SQL backend
+     * (Neon/Postgres/Turso) is latency-bound — the SQL driver currently
+     * does NOT support `batchSchemaSync`, so it issues one round-trip per
+     * registered object × twice (Phase 1 + Phase 3 in `start()`). On a
+     * cold remote DB with N tables this can blow past the kernel's
+     * default 30s easily, even though everything is healthy.
+     */
+    startupTimeout?: number;
+    /**
+     * Skip both `syncRegisteredSchemas()` calls inside `start()` and
+     * assume DDL is managed out-of-band (e.g. an `apps/cloud/scripts/migrate.ts`
+     * run before deploy that connects directly to the database and creates
+     * all `sys_*` + custom tables once).
+     *
+     * Use this on cold-start-sensitive runtimes (Cloudflare Containers,
+     * Lambda) where the platform's inbound-request budget is shorter than
+     * a fresh remote-DB schema sync. The plugin still hydrates the
+     * SchemaRegistry from `sys_metadata` (Phase 2), so custom user
+     * objects come up — they just aren't re-DDL'd on every cold boot.
+     *
+     * Falls back to `process.env.OS_SKIP_SCHEMA_SYNC === '1'` when the
+     * option is unset, so containers can flip it via their env without a
+     * code change.
+     */
+    skipSchemaSync?: boolean;
+}
 declare class ObjectQLPlugin implements Plugin {
     name: string;
     type: string;
     version: string;
+    /**
+     * Schema sync to remote SQL DBs is latency-bound (one round-trip per
+     * table × 2 phases). Default to 120s instead of the kernel's 30s so
+     * cold Neon/Turso starts don't get killed mid-sync.
+     */
+    startupTimeout: number;
     private ql;
     private hostContext?;
-    constructor(ql?: ObjectQL, hostContext?: Record<string, any>);
+    private projectId?;
+    private skipSchemaSync;
+    constructor(qlOrOptions?: ObjectQL | ObjectQLPluginOptions, hostContext?: Record<string, any>);
     init: (ctx: PluginContext) => Promise<void>;
     start: (ctx: PluginContext) => Promise<void>;
     /**
      * Register built-in audit hooks for auto-stamping created_by/updated_by
-     * and fetching previousData for update/delete operations.
+     * and fetching previousData for update/delete operations. These are
+     * declared as canonical `Hook` metadata and bound through the same
+     * `bindHooksToEngine` path used by `defineStack({ hooks })`, so the
+     * engine's built-ins flow through the same rails as user code
+     * (dogfooding the protocol).
      */
     private registerAuditHooks;
     /**
-     * Register tenant isolation middleware that auto-injects tenant_id filter
-     * for multi-tenant operations.
+     * Tenant isolation moved to `@objectstack/plugin-security`'s
+     * `member_default` permission set RLS
+     * (`organization_id = current_user.organization_id`, with
+     * field-existence guards). The legacy `registerTenantMiddleware`
+     * method was removed because it (a) collided with SecurityPlugin's
+     * RLS pipeline and (b) blindly filtered tables that don't have a
+     * `tenant_id` column (e.g. `sys_organization`), returning 0 rows
+     * instead of all rows.
      */
-    private registerTenantMiddleware;
     /**
      * Synchronize all registered object schemas to the database.
      *
@@ -2067,4 +1676,4 @@ declare function convertIntrospectedSchemaToObjects(introspectedSchema: Introspe
     skipSystemColumns?: boolean;
 }): ServiceObject[];
 
-export { DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type HookEntry, type HookHandler, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, type ObjectQLKernelOptions, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SchemaRegistry, ScopedContext, computeFQN, convertIntrospectedSchemaToObjects, createObjectQLKernel, parseFQN, toTitleCase };
+export { type BindHooksOptions, type BindHooksResult, DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type FieldValidationError, type HookEntry, type HookHandler, type HookMetricLabel, type HookMetricOutcome, type HookMetricsRecorder, type HookSkipReason, InMemoryHookMetricsRecorder, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, type ObjectQLKernelOptions, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SchemaRegistry, type SchemaRegistryOptions, ScopedContext, ValidationError, type WrapDeclarativeOptions, applyInMemoryAggregation, applySystemFields, bindHooksToEngine, bucketDateValue, computeFQN, convertIntrospectedSchemaToObjects, createObjectQLKernel, noopHookMetricsRecorder, parseFQN, toTitleCase, validateRecord, wrapDeclarativeHook };