@objectstack/objectql 1.0.11 → 1.0.12

package/dist/index.d.mts

@@ -1,21 +1,238 @@
-import { ServiceObject, HookContext, DataEngineQueryOptions, DataEngineInsertOptions, DataEngineUpdateOptions, DataEngineDeleteOptions, DataEngineCountOptions, DataEngineAggregateOptions } from '@objectstack/spec/data';
-import { ObjectStackManifest } from '@objectstack/spec/kernel';
+import { z } from 'zod';
+import { ServiceObject, ObjectOwnership, HookContext, DataEngineQueryOptions, DataEngineInsertOptions, DataEngineUpdateOptions, DataEngineDeleteOptions, DataEngineCountOptions, DataEngineAggregateOptions } from '@objectstack/spec/data';
+import { ObjectStackManifest, InstalledPackage } from '@objectstack/spec/kernel';
 import { ObjectStackProtocol, MetadataCacheRequest, MetadataCacheResponse, BatchUpdateRequest, BatchUpdateResponse, UpdateManyDataRequest, DeleteManyDataRequest } from '@objectstack/spec/api';
 import { IDataEngine, DriverInterface, Logger, Plugin, PluginContext } from '@objectstack/core';
 
+/**
+ * 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<[z.ZodString, z.ZodObject<{
+    type: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    params?: Record<string, any> | undefined;
+}, {
+    type: string;
+    params?: Record<string, any> | undefined;
+}>]>;
+/**
+ * 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<[z.ZodString, z.ZodObject<{
+        type: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        params?: Record<string, any> | undefined;
+    }, {
+        type: string;
+        params?: Record<string, any> | undefined;
+    }>]>>;
+    actions: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
+        type: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        params?: Record<string, any> | undefined;
+    }, {
+        type: string;
+        params?: Record<string, any> | undefined;
+    }>]>, "many">>;
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    target?: string | undefined;
+    description?: string | undefined;
+    cond?: string | {
+        type: string;
+        params?: Record<string, any> | undefined;
+    } | undefined;
+    actions?: (string | {
+        type: string;
+        params?: Record<string, any> | undefined;
+    })[] | undefined;
+}, {
+    target?: string | undefined;
+    description?: string | undefined;
+    cond?: string | {
+        type: string;
+        params?: Record<string, any> | undefined;
+    } | undefined;
+    actions?: (string | {
+        type: string;
+        params?: Record<string, any> | undefined;
+    })[] | undefined;
+}>;
+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").
+ */
+declare const RESERVED_NAMESPACES: Set<string>;
+/**
+ * Default priorities for ownership types.
+ */
+declare const DEFAULT_OWNER_PRIORITY = 100;
+declare const DEFAULT_EXTENDER_PRIORITY = 200;
+/**
+ * Contributor Record
+ * Tracks how a package contributes to an object (own or extend).
+ */
+interface ObjectContributor {
+    packageId: string;
+    namespace: string;
+    ownership: ObjectOwnership;
+    priority: number;
+    definition: ServiceObject;
+}
+/**
+ * Compute Fully Qualified Name (FQN) 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
+ *
+ * @example
+ * computeFQN('crm', 'account')  // => 'crm__account'
+ * computeFQN('base', 'user')    // => 'user' (reserved, no prefix)
+ * computeFQN(undefined, 'task') // => 'task' (legacy, no namespace)
+ */
+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")
+ * @returns { namespace, shortName } - namespace is undefined for unprefixed names
+ */
+declare function parseFQN(fqn: string): {
+    namespace: string | undefined;
+    shortName: string;
+};
 /**
  * Global Schema Registry
  * Unified storage for all metadata types (Objects, Apps, Flows, Layouts, etc.)
+ *
+ * ## Namespace & Ownership Model
+ *
+ * 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")
+ * - Reserved namespaces (`base`, `system`) don't get prefixed
+ *
+ * Ownership modes:
+ * - `own`: One package owns the object (creates the table, defines base schema)
+ * - `extend`: Multiple packages can extend an object (add fields, merge by priority)
+ *
+ * ## Package vs App Distinction
+ * - **Package**: The unit of installation, stored under type 'package'.
+ *   Each InstalledPackage wraps a ManifestSchema with lifecycle state.
+ * - **App**: A UI navigation shell (AppSchema), registered under type 'apps'.
+ *   Apps are extracted from packages during registration.
+ * - A package may contain 0, 1, or many apps.
  */
+type RegistryLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
 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;
+    /** FQN → Contributor[] (all packages that own/extend this object) */
+    private static objectContributors;
+    /** FQN → Merged ServiceObject (cached, invalidated on changes) */
+    private static mergedObjectCache;
+    /** Namespace → PackageId (ensures namespace uniqueness) */
+    private static namespaceRegistry;
+    /** Type → Name/ID → MetadataItem */
     private static metadata;
     /**
-     * Universal Register Method
-     * @param type The category of metadata (e.g., 'object', 'app', 'plugin')
-     * @param item The metadata item itself
-     * @param keyField The property to use as the unique key (default: 'name')
+     * Register a namespace for a package.
+     * Enforces namespace uniqueness within the instance.
+     *
+     * @throws Error if namespace is already registered to a different package
+     */
+    static registerNamespace(namespace: string, packageId: string): void;
+    /**
+     * Unregister a namespace when a package is uninstalled.
+     */
+    static unregisterNamespace(namespace: string, packageId: string): void;
+    /**
+     * Get the package that owns a namespace.
+     */
+    static getNamespaceOwner(namespace: string): string | undefined;
+    /**
+     * Register an object with ownership semantics.
+     *
+     * @param schema - The object definition
+     * @param packageId - The owning package ID
+     * @param namespace - The package namespace (for FQN computation)
+     * @param ownership - 'own' (single owner) or 'extend' (additive merge)
+     * @param priority - Merge priority (lower applied first, higher wins on conflict)
+     *
+     * @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;
+    /**
+     * Resolve an object by FQN, merging all contributions.
+     * Returns the merged object or undefined if not found.
+     */
+    static resolveObject(fqn: string): ServiceObject | undefined;
+    /**
+     * Get object by name (FQN or short name with fallback scan).
+     * For compatibility, tries exact match first, then scans for suffix match.
+     */
+    static 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[];
+    /**
+     * Get all contributors for an object.
+     */
+    static getObjectContributors(fqn: string): ObjectContributor[];
+    /**
+     * Get the owner contributor for an object.
      */
-    static registerItem<T>(type: string, item: T, keyField?: keyof T): void;
+    static 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;
+    /**
+     * Universal Register Method for non-object metadata.
+     */
+    static registerItem<T>(type: string, item: T, keyField?: keyof T, packageId?: string): void;
     /**
      * Validate Metadata against Spec Zod Schemas
      */
@@ -224,6 +441,66 @@ declare class SchemaRegistry {
             destination: string;
         } | undefined;
         validations?: any[] | undefined;
+        stateMachine?: {
+            initial: string;
+            states: Record<string, StateNodeConfig>;
+            id: string;
+            on?: Record<string, string | {
+                target?: string | undefined;
+                description?: string | undefined;
+                cond?: string | {
+                    type: string;
+                    params?: Record<string, any> | undefined;
+                } | undefined;
+                actions?: (string | {
+                    type: string;
+                    params?: Record<string, any> | undefined;
+                })[] | undefined;
+            } | {
+                target?: string | undefined;
+                description?: string | undefined;
+                cond?: string | {
+                    type: string;
+                    params?: Record<string, any> | undefined;
+                } | undefined;
+                actions?: (string | {
+                    type: string;
+                    params?: Record<string, any> | undefined;
+                })[] | undefined;
+            }[]> | undefined;
+            description?: string | undefined;
+            contextSchema?: Record<string, any> | undefined;
+        } | undefined;
+        stateMachines?: Record<string, {
+            initial: string;
+            states: Record<string, StateNodeConfig>;
+            id: string;
+            on?: Record<string, string | {
+                target?: string | undefined;
+                description?: string | undefined;
+                cond?: string | {
+                    type: string;
+                    params?: Record<string, any> | undefined;
+                } | undefined;
+                actions?: (string | {
+                    type: string;
+                    params?: Record<string, any> | undefined;
+                })[] | undefined;
+            } | {
+                target?: string | undefined;
+                description?: string | undefined;
+                cond?: string | {
+                    type: string;
+                    params?: Record<string, any> | undefined;
+                } | undefined;
+                actions?: (string | {
+                    type: string;
+                    params?: Record<string, any> | undefined;
+                })[] | undefined;
+            }[]> | undefined;
+            description?: string | undefined;
+            contextSchema?: Record<string, any> | undefined;
+        }> | undefined;
         titleFormat?: string | undefined;
         compactLayout?: string[] | undefined;
         enable?: {
@@ -236,7 +513,7 @@ declare class SchemaRegistry {
             trash: boolean;
             mru: boolean;
             clone: boolean;
-            apiMethods?: ("search" | "update" | "delete" | "get" | "list" | "create" | "upsert" | "bulk" | "aggregate" | "history" | "restore" | "purge" | "import" | "export")[] | undefined;
+            apiMethods?: ("search" | "update" | "delete" | "history" | "get" | "list" | "create" | "upsert" | "bulk" | "aggregate" | "restore" | "purge" | "import" | "export")[] | undefined;
         } | undefined;
     } | {
         label: string;
@@ -256,28 +533,315 @@ declare class SchemaRegistry {
         homePageId?: string | undefined;
         requiredPermissions?: string[] | undefined;
         apis?: any[] | undefined;
+    } | {
+        status: "error" | "disabled" | "installed" | "installing" | "uninstalling";
+        enabled: boolean;
+        manifest: {
+            type: "theme" | "driver" | "app" | "server" | "ui" | "agent" | "objectql" | "plugin" | "module" | "gateway" | "adapter";
+            name: string;
+            id: string;
+            version: string;
+            description?: string | undefined;
+            dependencies?: Record<string, string> | undefined;
+            data?: {
+                object: string;
+                externalId: string;
+                mode: "insert" | "update" | "upsert" | "replace" | "ignore";
+                env: ("prod" | "dev" | "test")[];
+                records: Record<string, any>[];
+            }[] | undefined;
+            capabilities?: {
+                implements?: {
+                    protocol: {
+                        label: string;
+                        id: string;
+                        version: {
+                            major: number;
+                            minor: number;
+                            patch: number;
+                        };
+                        description?: string | undefined;
+                        specification?: string | undefined;
+                    };
+                    conformance: "partial" | "full" | "deprecated" | "experimental";
+                    certified: boolean;
+                    metadata?: Record<string, any> | undefined;
+                    features?: {
+                        enabled: boolean;
+                        name: string;
+                        description?: string | undefined;
+                        sinceVersion?: string | undefined;
+                        deprecatedSince?: string | undefined;
+                    }[] | undefined;
+                    implementedFeatures?: string[] | undefined;
+                    certificationDate?: string | undefined;
+                }[] | undefined;
+                provides?: {
+                    methods: {
+                        name: string;
+                        async: boolean;
+                        description?: string | undefined;
+                        parameters?: {
+                            type: string;
+                            required: boolean;
+                            name: string;
+                            description?: string | undefined;
+                        }[] | undefined;
+                        returnType?: string | undefined;
+                    }[];
+                    name: string;
+                    id: string;
+                    version: {
+                        major: number;
+                        minor: number;
+                        patch: number;
+                    };
+                    stability: "alpha" | "experimental" | "stable" | "beta";
+                    description?: string | undefined;
+                    events?: {
+                        name: string;
+                        description?: string | undefined;
+                        payload?: string | undefined;
+                    }[] | undefined;
+                }[] | undefined;
+                requires?: {
+                    version: string;
+                    optional: boolean;
+                    pluginId: string;
+                    reason?: string | undefined;
+                    requiredCapabilities?: string[] | undefined;
+                }[] | undefined;
+                extensionPoints?: {
+                    type: "provider" | "action" | "widget" | "hook" | "transformer" | "validator" | "decorator";
+                    name: string;
+                    id: string;
+                    cardinality: "multiple" | "single";
+                    description?: string | undefined;
+                    contract?: {
+                        signature?: string | undefined;
+                        input?: string | undefined;
+                        output?: string | undefined;
+                    } | undefined;
+                }[] | undefined;
+                extensions?: {
+                    priority: number;
+                    implementation: string;
+                    targetPluginId: string;
+                    extensionPointId: string;
+                }[] | undefined;
+            } | undefined;
+            objects?: string[] | undefined;
+            permissions?: string[] | undefined;
+            namespace?: string | undefined;
+            extensions?: Record<string, any> | undefined;
+            loading?: {
+                strategy: "parallel" | "eager" | "lazy" | "deferred" | "on-demand";
+                caching?: {
+                    enabled: boolean;
+                    storage: "hybrid" | "memory" | "disk" | "indexeddb";
+                    keyStrategy: "hash" | "version" | "timestamp";
+                    maxSize?: number | undefined;
+                    ttl?: number | undefined;
+                    invalidateOn?: ("error" | "manual" | "version-change" | "dependency-change")[] | undefined;
+                    compression?: {
+                        enabled: boolean;
+                        algorithm: "gzip" | "brotli" | "deflate";
+                    } | undefined;
+                } | undefined;
+                preload?: {
+                    enabled: boolean;
+                    priority: number;
+                    conditions?: {
+                        roles?: string[] | undefined;
+                        routes?: string[] | undefined;
+                        deviceType?: ("desktop" | "mobile" | "tablet")[] | undefined;
+                        minNetworkSpeed?: "slow-2g" | "2g" | "3g" | "4g" | undefined;
+                    } | undefined;
+                    resources?: ("code" | "dependencies" | "metadata" | "assets" | "services")[] | undefined;
+                } | undefined;
+                codeSplitting?: {
+                    enabled: boolean;
+                    strategy: "custom" | "size" | "route" | "feature";
+                    chunkNaming: "hashed" | "named" | "sequential";
+                    maxChunkSize?: number | undefined;
+                    sharedDependencies?: {
+                        enabled: boolean;
+                        minChunks: number;
+                    } | undefined;
+                } | undefined;
+                dynamicImport?: {
+                    enabled: boolean;
+                    timeout: number;
+                    mode: "async" | "eager" | "lazy" | "sync";
+                    prefetch: boolean;
+                    preload: boolean;
+                    retry?: {
+                        enabled: boolean;
+                        maxAttempts: number;
+                        backoffMs: number;
+                    } | undefined;
+                    webpackChunkName?: string | undefined;
+                } | undefined;
+                initialization?: {
+                    timeout: number;
+                    priority: number;
+                    mode: "async" | "parallel" | "sequential" | "sync";
+                    critical: boolean;
+                    retry?: {
+                        enabled: boolean;
+                        maxAttempts: number;
+                        backoffMs: number;
+                    } | undefined;
+                    healthCheckInterval?: number | undefined;
+                } | undefined;
+                dependencyResolution?: {
+                    strategy: "strict" | "latest" | "compatible" | "pinned";
+                    conflictResolution: "latest" | "manual" | "fail" | "oldest";
+                    circularDependencies: "error" | "warn" | "allow";
+                    peerDependencies?: {
+                        resolve: boolean;
+                        onMissing: "error" | "warn" | "ignore";
+                        onMismatch: "error" | "warn" | "ignore";
+                    } | undefined;
+                    optionalDependencies?: {
+                        load: boolean;
+                        onFailure: "warn" | "ignore";
+                    } | undefined;
+                } | undefined;
+                hotReload?: {
+                    enabled: boolean;
+                    strategy: "partial" | "full" | "state-preserve";
+                    debounceMs: number;
+                    preserveState: boolean;
+                    watchPatterns?: string[] | undefined;
+                    ignorePatterns?: string[] | undefined;
+                    stateSerialization?: {
+                        enabled: boolean;
+                        handler?: string | undefined;
+                    } | undefined;
+                    hooks?: {
+                        onError?: string | undefined;
+                        beforeReload?: string | undefined;
+                        afterReload?: string | undefined;
+                    } | undefined;
+                } | undefined;
+                sandboxing?: {
+                    enabled: boolean;
+                    isolationLevel: "none" | "process" | "vm" | "iframe" | "web-worker";
+                    permissions?: {
+                        allowedAPIs?: string[] | undefined;
+                        allowedPaths?: string[] | undefined;
+                        allowedEndpoints?: string[] | undefined;
+                        allowedEnvVars?: string[] | undefined;
+                    } | undefined;
+                    allowedCapabilities?: string[] | undefined;
+                    resourceQuotas?: {
+                        maxMemoryMB?: number | undefined;
+                        maxCpuTimeMs?: number | undefined;
+                        maxFileDescriptors?: number | undefined;
+                        maxNetworkKBps?: number | undefined;
+                    } | undefined;
+                } | undefined;
+                monitoring?: {
+                    enabled: boolean;
+                    samplingRate: number;
+                    reportingInterval: number;
+                    onBudgetViolation: "error" | "warn" | "ignore";
+                    metrics?: ("load-time" | "init-time" | "memory-usage" | "cpu-usage" | "api-calls" | "error-rate" | "cache-hit-rate")[] | undefined;
+                    budgets?: {
+                        maxMemoryMB?: number | undefined;
+                        maxLoadTimeMs?: number | undefined;
+                        maxInitTimeMs?: number | undefined;
+                    } | undefined;
+                } | undefined;
+            } | undefined;
+            datasources?: string[] | undefined;
+            configuration?: {
+                properties: Record<string, {
+                    type: "string" | "number" | "boolean" | "object" | "array";
+                    required?: boolean | undefined;
+                    default?: any;
+                    description?: string | undefined;
+                    enum?: string[] | undefined;
+                    secret?: boolean | undefined;
+                }>;
+                title?: string | undefined;
+            } | undefined;
+            contributes?: {
+                events?: string[] | undefined;
+                actions?: {
+                    name: string;
+                    label?: string | undefined;
+                    description?: string | undefined;
+                    input?: any;
+                    output?: any;
+                }[] | undefined;
+                fieldTypes?: {
+                    label: string;
+                    name: string;
+                    description?: string | undefined;
+                }[] | undefined;
+                drivers?: {
+                    label: string;
+                    id: string;
+                    description?: string | undefined;
+                }[] | undefined;
+                kinds?: {
+                    id: string;
+                    globs: string[];
+                    description?: string | undefined;
+                }[] | undefined;
+                menus?: Record<string, {
+                    label: string;
+                    id: string;
+                    command?: string | undefined;
+                }[]> | undefined;
+                themes?: {
+                    path: string;
+                    label: string;
+                    id: string;
+                }[] | undefined;
+                translations?: {
+                    path: string;
+                    locale: string;
+                }[] | undefined;
+                functions?: {
+                    name: string;
+                    description?: string | undefined;
+                    returnType?: string | undefined;
+                    args?: string[] | undefined;
+                }[] | undefined;
+            } | undefined;
+        };
+        errorMessage?: string | undefined;
+        updatedAt?: string | undefined;
+        installedAt?: string | undefined;
+        statusChangedAt?: string | undefined;
+        settings?: Record<string, any> | undefined;
     } | {
         type: "theme" | "driver" | "app" | "server" | "ui" | "agent" | "objectql" | "plugin" | "module" | "gateway" | "adapter";
         name: string;
-        version: string;
         id: string;
+        version: string;
         description?: string | undefined;
         dependencies?: Record<string, string> | undefined;
         data?: {
             object: string;
-            mode: "insert" | "upsert" | "ignore";
+            externalId: string;
+            mode: "insert" | "update" | "upsert" | "replace" | "ignore";
+            env: ("prod" | "dev" | "test")[];
             records: Record<string, any>[];
         }[] | undefined;
         capabilities?: {
             implements?: {
                 protocol: {
                     label: string;
+                    id: string;
                     version: {
                         major: number;
                         minor: number;
                         patch: number;
                     };
-                    id: string;
                     description?: string | undefined;
                     specification?: string | undefined;
                 };
@@ -308,12 +872,12 @@ declare class SchemaRegistry {
                     returnType?: string | undefined;
                 }[];
                 name: string;
+                id: string;
                 version: {
                     major: number;
                     minor: number;
                     patch: number;
                 };
-                id: string;
                 stability: "alpha" | "experimental" | "stable" | "beta";
                 description?: string | undefined;
                 events?: {
@@ -350,6 +914,7 @@ declare class SchemaRegistry {
         } | undefined;
         objects?: string[] | undefined;
         permissions?: string[] | undefined;
+        namespace?: string | undefined;
         extensions?: Record<string, any> | undefined;
         loading?: {
             strategy: "parallel" | "eager" | "lazy" | "deferred" | "on-demand";
@@ -486,11 +1051,6 @@ declare class SchemaRegistry {
         } | undefined;
         contributes?: {
             events?: string[] | undefined;
-            fieldTypes?: {
-                label: string;
-                name: string;
-                description?: string | undefined;
-            }[] | undefined;
             actions?: {
                 name: string;
                 label?: string | undefined;
@@ -498,6 +1058,11 @@ declare class SchemaRegistry {
                 input?: any;
                 output?: any;
             }[] | undefined;
+            fieldTypes?: {
+                label: string;
+                name: string;
+                description?: string | undefined;
+            }[] | undefined;
             drivers?: {
                 label: string;
                 id: string;
@@ -541,25 +1106,22 @@ declare class SchemaRegistry {
     /**
      * Universal List Method
      */
-    static listItems<T>(type: string): T[];
+    static listItems<T>(type: string, packageId?: string): T[];
     /**
      * Get all registered metadata types (Kinds)
      */
     static getRegisteredTypes(): string[];
-    /**
-     * Object Helpers
-     */
-    static registerObject(schema: ServiceObject): void;
-    static getObject(name: string): ServiceObject | undefined;
-    static getAllObjects(): ServiceObject[];
-    /**
-     * Plugin Helpers
-     */
+    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[];
-    /**
-     * Kind (Metadata Type) Helpers
-     */
     static registerKind(kind: {
         id: string;
         globs: string[];
@@ -568,6 +1130,10 @@ declare class SchemaRegistry {
         id: string;
         globs: string[];
     }[];
+    /**
+     * Clear all registry state. Use only for testing.
+     */
+    static reset(): void;
 }
 
 declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
@@ -595,6 +1161,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     }>;
     getMetaItems(request: {
         type: string;
+        packageId?: string;
     }): Promise<{
         type: string;
         items: unknown[];
@@ -610,7 +1177,42 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     getUiView(request: {
         object: string;
         type: 'list' | 'form';
-    }): Promise<any>;
+    }): Promise<{
+        list: {
+            type: "grid";
+            object: string;
+            label: string;
+            columns: {
+                field: string;
+                label: string;
+                sortable: boolean;
+            }[];
+            sort: any;
+            searchableFields: string[];
+        };
+        form?: undefined;
+    } | {
+        form: {
+            type: "simple";
+            object: string;
+            label: string;
+            sections: {
+                label: string;
+                columns: 2;
+                collapsible: boolean;
+                collapsed: boolean;
+                fields: {
+                    field: string;
+                    label: string | undefined;
+                    required: boolean;
+                    readonly: boolean;
+                    type: "number" | "boolean" | "tags" | "code" | "email" | "date" | "lookup" | "text" | "textarea" | "url" | "phone" | "password" | "markdown" | "html" | "richtext" | "currency" | "percent" | "datetime" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "master_detail" | "tree" | "image" | "file" | "avatar" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "json" | "color" | "rating" | "slider" | "signature" | "qrcode" | "progress" | "vector";
+                    colSpan: number;
+                }[];
+            }[];
+        };
+        list?: undefined;
+    }>;
     findData(request: {
         object: string;
         query?: any;
@@ -736,6 +1338,13 @@ declare class ObjectQL implements IDataEngine {
     triggerHooks(event: string, context: HookContext): Promise<void>;
     /**
      * Register contribution (Manifest)
+     *
+     * Installs the manifest as a Package (the unit of installation),
+     * then decomposes it into individual metadata items (objects, apps, actions, etc.)
+     * and registers each into the SchemaRegistry.
+     *
+     * Key: Package ≠ App. The manifest is the package. The apps[] array inside
+     * the manifest contains UI navigation definitions (AppSchema).
      */
     registerApp(manifest: any): void;
     /**
@@ -950,6 +1559,66 @@ declare class ObjectQL implements IDataEngine {
             destination: string;
         } | undefined;
         validations?: any[] | undefined;
+        stateMachine?: {
+            initial: string;
+            states: Record<string, StateNodeConfig>;
+            id: string;
+            on?: Record<string, string | {
+                target?: string | undefined;
+                description?: string | undefined;
+                cond?: string | {
+                    type: string;
+                    params?: Record<string, any> | undefined;
+                } | undefined;
+                actions?: (string | {
+                    type: string;
+                    params?: Record<string, any> | undefined;
+                })[] | undefined;
+            } | {
+                target?: string | undefined;
+                description?: string | undefined;
+                cond?: string | {
+                    type: string;
+                    params?: Record<string, any> | undefined;
+                } | undefined;
+                actions?: (string | {
+                    type: string;
+                    params?: Record<string, any> | undefined;
+                })[] | undefined;
+            }[]> | undefined;
+            description?: string | undefined;
+            contextSchema?: Record<string, any> | undefined;
+        } | undefined;
+        stateMachines?: Record<string, {
+            initial: string;
+            states: Record<string, StateNodeConfig>;
+            id: string;
+            on?: Record<string, string | {
+                target?: string | undefined;
+                description?: string | undefined;
+                cond?: string | {
+                    type: string;
+                    params?: Record<string, any> | undefined;
+                } | undefined;
+                actions?: (string | {
+                    type: string;
+                    params?: Record<string, any> | undefined;
+                })[] | undefined;
+            } | {
+                target?: string | undefined;
+                description?: string | undefined;
+                cond?: string | {
+                    type: string;
+                    params?: Record<string, any> | undefined;
+                } | undefined;
+                actions?: (string | {
+                    type: string;
+                    params?: Record<string, any> | undefined;
+                })[] | undefined;
+            }[]> | undefined;
+            description?: string | undefined;
+            contextSchema?: Record<string, any> | undefined;
+        }> | undefined;
         titleFormat?: string | undefined;
         compactLayout?: string[] | undefined;
         enable?: {
@@ -962,9 +1631,20 @@ declare class ObjectQL implements IDataEngine {
             trash: boolean;
             mru: boolean;
             clone: boolean;
-            apiMethods?: ("search" | "update" | "delete" | "get" | "list" | "create" | "upsert" | "bulk" | "aggregate" | "history" | "restore" | "purge" | "import" | "export")[] | undefined;
+            apiMethods?: ("search" | "update" | "delete" | "history" | "get" | "list" | "create" | "upsert" | "bulk" | "aggregate" | "restore" | "purge" | "import" | "export")[] | undefined;
         } | undefined;
     } | 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).
+     *
+     * This ensures that all driver operations use a consistent key
+     * regardless of whether the caller uses the short name or FQN.
+     */
+    private resolveObjectName;
     /**
      * Helper to get the target driver
      */
@@ -996,4 +1676,4 @@ declare class ObjectQLPlugin implements Plugin {
     start: (ctx: PluginContext) => Promise<void>;
 }
 
-export { type HookHandler, ObjectQL, type ObjectQLHostContext, ObjectQLPlugin, ObjectStackProtocolImplementation, SchemaRegistry };
+export { DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type HookHandler, type ObjectContributor, ObjectQL, type ObjectQLHostContext, ObjectQLPlugin, ObjectStackProtocolImplementation, RESERVED_NAMESPACES, SchemaRegistry, computeFQN, parseFQN };