@objectstack/objectql 4.0.3 → 4.0.5

package/dist/index.d.mts

@@ -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, 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.
  *
- * @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
+ * 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 (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,75 @@ 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).
+ */
+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,1084 +154,116 @@ 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;
-            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;
-        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);
+    /**
+     * 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;
@@ -1264,7 +288,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;
@@ -1333,7 +357,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;
                 }[];
             }[];
@@ -1343,6 +367,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     findData(request: {
         object: string;
         query?: any;
+        context?: any;
     }): Promise<{
         object: string;
         records: any[];
@@ -1354,6 +379,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         id: string;
         expand?: string | string[];
         select?: string | string[];
+        context?: any;
     }): Promise<{
         object: string;
         id: string;
@@ -1362,6 +388,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     createData(request: {
         object: string;
         data: any;
+        context?: any;
     }): Promise<{
         object: string;
         id: any;
@@ -1371,6 +398,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         object: string;
         id: string;
         data: any;
+        context?: any;
     }): Promise<{
         object: string;
         id: string;
@@ -1379,6 +407,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     deleteData(request: {
         object: string;
         id: string;
+        context?: any;
     }): Promise<{
         object: string;
         id: string;
@@ -1450,6 +479,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
@@ -1487,11 +524,15 @@ declare class ObjectQL implements IDataEngine {
     private drivers;
     private defaultDriver;
     private logger;
+    private datasourceMapping;
+    private manifests;
     private hooks;
     private middlewares;
     private actions;
+    private functions;
     private hostContext;
     private realtimeService?;
+    private _registry;
     constructor(hostContext?: Record<string, any>);
     /**
      * Service Status Report
@@ -1504,9 +545,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
      */
@@ -1521,7 +565,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.
@@ -1558,6 +662,26 @@ declare class ObjectQL implements IDataEngine {
      * Build a HookContext.session from ExecutionContext
      */
     private buildSession;
+    /**
+     * 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)
      *
@@ -1569,6 +693,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.)
      *
@@ -1597,20 +727,47 @@ declare class ObjectQL implements IDataEngine {
      */
     getSchema(objectName: string): ServiceObject | undefined;
     /**
-     * Resolve an object name to its Fully Qualified Name (FQN).
-     *
-     * 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).
+     * Resolve any object identifier to the physical storage name used by drivers.
      *
-     * 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;
     /**
      * Helper to get the target driver
+     *
+     * Resolution priority (first match wins):
+     * 1. Object's explicit `datasource` field (if not 'default')
+     * 2. DatasourceMapping rules (namespace/package/pattern matching)
+     * 3. Package's `defaultDatasource` from manifest
+     * 4. Global default driver
      */
     private getDriver;
+    /**
+     * Resolve datasource from mapping rules
+     *
+     * Rules are evaluated in order (or by priority if specified).
+     * First matching rule wins.
+     */
+    private resolveDatasourceFromMapping;
+    /**
+     * Simple glob pattern matching
+     * Supports * (any chars) and ? (single char)
+     */
+    private matchPattern;
+    /**
+     * Set datasource mapping rules
+     * Called by ObjectQLPlugin during bootstrap
+     */
+    setDatasourceMapping(rules: Array<{
+        namespace?: string;
+        package?: string;
+        objectPattern?: string;
+        default?: boolean;
+        datasource: string;
+        priority?: number;
+    }>): void;
     /**
      * Initialize the engine and all registered drivers
      */
@@ -1678,6 +835,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.
@@ -1800,6 +964,198 @@ declare class ScopedContext {
     get transactionHandle(): unknown;
 }
 
+/**
+ * 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;
+
 /**
  * MetadataFacade
  *
@@ -1809,8 +1165,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
      */
@@ -1853,25 +1215,52 @@ 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;
+}
 declare class ObjectQLPlugin implements Plugin {
     name: string;
     type: string;
     version: string;
     private ql;
     private hostContext?;
-    constructor(ql?: ObjectQL, hostContext?: Record<string, any>);
+    private projectId?;
+    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.
      *
@@ -2033,4 +1422,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 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, type WrapDeclarativeOptions, applySystemFields, bindHooksToEngine, computeFQN, convertIntrospectedSchemaToObjects, createObjectQLKernel, noopHookMetricsRecorder, parseFQN, toTitleCase, wrapDeclarativeHook };