@objectstack/objectql 4.0.4 → 4.0.5

package/dist/index.mjs

@@ -5,11 +5,8 @@ import { AppSchema } from "@objectstack/spec/ui";
 var RESERVED_NAMESPACES = /* @__PURE__ */ new Set(["base", "system"]);
 var DEFAULT_OWNER_PRIORITY = 100;
 var DEFAULT_EXTENDER_PRIORITY = 200;
-function computeFQN(namespace, shortName) {
-  if (!namespace || RESERVED_NAMESPACES.has(namespace)) {
-    return shortName;
-  }
-  return `${namespace}__${shortName}`;
+function computeFQN(_namespace, shortName) {
+  return shortName;
 }
 function parseFQN(fqn) {
   const idx = fqn.indexOf("__");
@@ -37,14 +34,64 @@ function mergeObjectDefinitions(base, extension) {
   if (extension.description !== void 0) merged.description = extension.description;
   return merged;
 }
+function applySystemFields(schema, opts) {
+  if (schema.systemFields === false) return schema;
+  if (schema.managedBy) return schema;
+  const sf = typeof schema.systemFields === "object" && schema.systemFields !== null ? schema.systemFields : void 0;
+  const wantTenant = opts.multiTenant && sf?.tenant !== false;
+  const additions = {};
+  if (wantTenant && !schema.fields?.organization_id) {
+    additions.organization_id = {
+      type: "lookup",
+      reference: "sys_organization",
+      label: "Organization",
+      required: false,
+      indexed: true,
+      hidden: true,
+      readonly: true,
+      description: "Tenant scope (auto-populated by SecurityPlugin on insert)."
+    };
+  }
+  if (Object.keys(additions).length === 0) return schema;
+  return {
+    ...schema,
+    fields: { ...additions, ...schema.fields ?? {} }
+  };
+}
 var SchemaRegistry = class {
-  static get logLevel() {
+  constructor(options = {}) {
+    // ==========================================
+    // Logging control
+    // ==========================================
+    /** Controls verbosity of registry console messages. Default: 'info'. */
+    this._logLevel = "info";
+    // ==========================================
+    // Object-specific storage (Ownership Model)
+    // ==========================================
+    /** FQN → Contributor[] (all packages that own/extend this object) */
+    this.objectContributors = /* @__PURE__ */ new Map();
+    /** FQN → Merged ServiceObject (cached, invalidated on changes) */
+    this.mergedObjectCache = /* @__PURE__ */ new Map();
+    /** Namespace → Set<PackageId> (multiple packages can share a namespace) */
+    this.namespaceRegistry = /* @__PURE__ */ new Map();
+    // ==========================================
+    // Generic metadata storage (non-object types)
+    // ==========================================
+    /** Type → Name/ID → MetadataItem */
+    this.metadata = /* @__PURE__ */ new Map();
+    if (options.multiTenant !== void 0) {
+      this.multiTenant = options.multiTenant;
+    } else {
+      this.multiTenant = String(process.env.OS_MULTI_TENANT ?? "true").toLowerCase() !== "false";
+    }
+  }
+  get logLevel() {
     return this._logLevel;
   }
-  static set logLevel(level) {
+  set logLevel(level) {
     this._logLevel = level;
   }
-  static log(msg) {
+  log(msg) {
     if (this._logLevel === "silent" || this._logLevel === "error" || this._logLevel === "warn") return;
     console.log(msg);
   }
@@ -55,7 +102,7 @@ var SchemaRegistry = class {
    * Register a namespace for a package.
    * Multiple packages can share the same namespace (e.g. 'sys').
    */
-  static registerNamespace(namespace, packageId) {
+  registerNamespace(namespace, packageId) {
     if (!namespace) return;
     let owners = this.namespaceRegistry.get(namespace);
     if (!owners) {
@@ -68,7 +115,7 @@ var SchemaRegistry = class {
   /**
    * Unregister a namespace when a package is uninstalled.
    */
-  static unregisterNamespace(namespace, packageId) {
+  unregisterNamespace(namespace, packageId) {
     const owners = this.namespaceRegistry.get(namespace);
     if (owners) {
       owners.delete(packageId);
@@ -81,7 +128,7 @@ var SchemaRegistry = class {
   /**
    * Get the packages that use a namespace.
    */
-  static getNamespaceOwner(namespace) {
+  getNamespaceOwner(namespace) {
     const owners = this.namespaceRegistry.get(namespace);
     if (!owners || owners.size === 0) return void 0;
     return owners.values().next().value;
@@ -89,7 +136,7 @@ var SchemaRegistry = class {
   /**
    * Get all packages that share a namespace.
    */
-  static getNamespaceOwners(namespace) {
+  getNamespaceOwners(namespace) {
     const owners = this.namespaceRegistry.get(namespace);
     return owners ? Array.from(owners) : [];
   }
@@ -107,7 +154,8 @@ var SchemaRegistry = class {
    * 
    * @throws Error if trying to 'own' an object that already has an owner
    */
-  static registerObject(schema, packageId, namespace, ownership = "own", priority = ownership === "own" ? DEFAULT_OWNER_PRIORITY : DEFAULT_EXTENDER_PRIORITY) {
+  registerObject(schema, packageId, namespace, ownership = "own", priority = ownership === "own" ? DEFAULT_OWNER_PRIORITY : DEFAULT_EXTENDER_PRIORITY) {
+    schema = applySystemFields(schema, { multiTenant: this.multiTenant });
     const shortName = schema.name;
     const fqn = computeFQN(namespace, shortName);
     if (namespace) {
@@ -154,7 +202,7 @@ var SchemaRegistry = class {
    * Resolve an object by FQN, merging all contributions.
    * Returns the merged object or undefined if not found.
    */
-  static resolveObject(fqn) {
+  resolveObject(fqn) {
     const cached = this.mergedObjectCache.get(fqn);
     if (cached) return cached;
     const contributors = this.objectContributors.get(fqn);
@@ -176,38 +224,42 @@ var SchemaRegistry = class {
     return merged;
   }
   /**
-   * 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.
-   */
-  static getObject(name) {
-    const direct = this.resolveObject(name);
-    if (direct) return direct;
+   * 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.
+   */
+  getObject(name) {
+    const matches = [];
     for (const fqn of this.objectContributors.keys()) {
       const { shortName } = parseFQN(fqn);
       if (shortName === name) {
-        return this.resolveObject(fqn);
+        matches.push(fqn);
       }
     }
-    for (const fqn of this.objectContributors.keys()) {
-      const resolved = this.resolveObject(fqn);
-      if (resolved?.tableName === name) {
-        return resolved;
+    if (matches.length > 0) {
+      if (matches.length > 1) {
+        console.warn(
+          `[SchemaRegistry] Ambiguous short name "${name}" matches: ${matches.join(", ")}. Returning first match. Use FQN to disambiguate.`
+        );
       }
+      return this.resolveObject(matches[0]);
     }
-    return void 0;
+    return this.resolveObject(name);
   }
   /**
    * Get all registered objects (merged).
    * 
    * @param packageId - Optional filter: only objects contributed by this package
    */
-  static getAllObjects(packageId) {
+  getAllObjects(packageId) {
     const results = [];
     for (const fqn of this.objectContributors.keys()) {
       if (packageId) {
@@ -226,13 +278,13 @@ var SchemaRegistry = class {
   /**
    * Get all contributors for an object.
    */
-  static getObjectContributors(fqn) {
+  getObjectContributors(fqn) {
     return this.objectContributors.get(fqn) || [];
   }
   /**
    * Get the owner contributor for an object.
    */
-  static getObjectOwner(fqn) {
+  getObjectOwner(fqn) {
     const contributors = this.objectContributors.get(fqn);
     return contributors?.find((c) => c.ownership === "own");
   }
@@ -241,7 +293,7 @@ var SchemaRegistry = class {
    * 
    * @throws Error if trying to uninstall an owner that has extenders
    */
-  static unregisterObjectsByPackage(packageId, force = false) {
+  unregisterObjectsByPackage(packageId, force = false) {
     for (const [fqn, contributors] of this.objectContributors.entries()) {
       const packageContribs = contributors.filter((c) => c.packageId === packageId);
       for (const contrib of packageContribs) {
@@ -273,7 +325,7 @@ var SchemaRegistry = class {
   /**
    * Universal Register Method for non-object metadata.
    */
-  static registerItem(type, item, keyField = "name", packageId) {
+  registerItem(type, item, keyField = "name", packageId) {
     if (!this.metadata.has(type)) {
       this.metadata.set(type, /* @__PURE__ */ new Map());
     }
@@ -289,7 +341,7 @@ var SchemaRegistry = class {
     }
     const storageKey = packageId ? `${packageId}:${baseName}` : baseName;
     if (collection.has(storageKey)) {
-      console.warn(`[Registry] Overwriting ${type}: ${storageKey}`);
+      this.log(`[Registry] Overwriting ${type}: ${storageKey}`);
     }
     collection.set(storageKey, item);
     this.log(`[Registry] Registered ${type}: ${storageKey}`);
@@ -297,7 +349,7 @@ var SchemaRegistry = class {
   /**
    * Validate Metadata against Spec Zod Schemas
    */
-  static validate(type, item) {
+  validate(type, item) {
     if (type === "object") {
       return ObjectSchema.parse(item);
     }
@@ -315,7 +367,7 @@ var SchemaRegistry = class {
   /**
    * Universal Unregister Method
    */
-  static unregisterItem(type, name) {
+  unregisterItem(type, name) {
     const collection = this.metadata.get(type);
     if (!collection) {
       console.warn(`[Registry] Attempted to unregister non-existent ${type}: ${name}`);
@@ -338,7 +390,7 @@ var SchemaRegistry = class {
   /**
    * Universal Get Method
    */
-  static getItem(type, name) {
+  getItem(type, name) {
     if (type === "object" || type === "objects") {
       return this.getObject(name);
     }
@@ -354,7 +406,7 @@ var SchemaRegistry = class {
   /**
    * Universal List Method
    */
-  static listItems(type, packageId) {
+  listItems(type, packageId) {
     if (type === "object" || type === "objects") {
       return this.getAllObjects(packageId);
     }
@@ -367,7 +419,7 @@ var SchemaRegistry = class {
   /**
    * Get all registered metadata types (Kinds)
    */
-  static getRegisteredTypes() {
+  getRegisteredTypes() {
     const types = Array.from(this.metadata.keys());
     if (!types.includes("object") && this.objectContributors.size > 0) {
       types.push("object");
@@ -377,7 +429,7 @@ var SchemaRegistry = class {
   // ==========================================
   // Package Management
   // ==========================================
-  static installPackage(manifest, settings) {
+  installPackage(manifest, settings) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const pkg = {
       manifest,
@@ -401,7 +453,7 @@ var SchemaRegistry = class {
     this.log(`[Registry] Installed package: ${manifest.id} (${manifest.name})`);
     return pkg;
   }
-  static uninstallPackage(id) {
+  uninstallPackage(id) {
     const pkg = this.getPackage(id);
     if (!pkg) {
       console.warn(`[Registry] Package not found for uninstall: ${id}`);
@@ -419,13 +471,13 @@ var SchemaRegistry = class {
     }
     return false;
   }
-  static getPackage(id) {
+  getPackage(id) {
     return this.metadata.get("package")?.get(id);
   }
-  static getAllPackages() {
+  getAllPackages() {
     return this.listItems("package");
   }
-  static enablePackage(id) {
+  enablePackage(id) {
     const pkg = this.getPackage(id);
     if (pkg) {
       pkg.enabled = true;
@@ -436,7 +488,7 @@ var SchemaRegistry = class {
     }
     return pkg;
   }
-  static disablePackage(id) {
+  disablePackage(id) {
     const pkg = this.getPackage(id);
     if (pkg) {
       pkg.enabled = false;
@@ -450,31 +502,31 @@ var SchemaRegistry = class {
   // ==========================================
   // App Helpers
   // ==========================================
-  static registerApp(app, packageId) {
+  registerApp(app, packageId) {
     this.registerItem("app", app, "name", packageId);
   }
-  static getApp(name) {
+  getApp(name) {
     return this.getItem("app", name);
   }
-  static getAllApps() {
+  getAllApps() {
     return this.listItems("app");
   }
   // ==========================================
   // Plugin Helpers
   // ==========================================
-  static registerPlugin(manifest) {
+  registerPlugin(manifest) {
     this.registerItem("plugin", manifest, "id");
   }
-  static getAllPlugins() {
+  getAllPlugins() {
     return this.listItems("plugin");
   }
   // ==========================================
   // Kind Helpers
   // ==========================================
-  static registerKind(kind) {
+  registerKind(kind) {
     this.registerItem("kind", kind, "id");
   }
-  static getAllKinds() {
+  getAllKinds() {
     return this.listItems("kind");
   }
   // ==========================================
@@ -483,7 +535,7 @@ var SchemaRegistry = class {
   /**
    * Clear all registry state. Use only for testing.
    */
-  static reset() {
+  reset() {
     this.objectContributors.clear();
     this.mergedObjectCache.clear();
     this.namespaceRegistry.clear();
@@ -491,25 +543,6 @@ var SchemaRegistry = class {
     this.log("[Registry] Reset complete");
   }
 };
-// ==========================================
-// Logging control
-// ==========================================
-/** Controls verbosity of registry console messages. Default: 'info'. */
-SchemaRegistry._logLevel = "info";
-// ==========================================
-// Object-specific storage (Ownership Model)
-// ==========================================
-/** FQN → Contributor[] (all packages that own/extend this object) */
-SchemaRegistry.objectContributors = /* @__PURE__ */ new Map();
-/** FQN → Merged ServiceObject (cached, invalidated on changes) */
-SchemaRegistry.mergedObjectCache = /* @__PURE__ */ new Map();
-/** Namespace → Set<PackageId> (multiple packages can share a namespace) */
-SchemaRegistry.namespaceRegistry = /* @__PURE__ */ new Map();
-// ==========================================
-// Generic metadata storage (non-object types)
-// ==========================================
-/** Type → Name/ID → MetadataItem */
-SchemaRegistry.metadata = /* @__PURE__ */ new Map();
 
 // src/protocol.ts
 import { parseFilterAST, isFilterAST } from "@objectstack/spec/data";
@@ -541,10 +574,20 @@ var SERVICE_CONFIG = {
   search: { route: "/api/v1/search", plugin: "plugin-search" }
 };
 var ObjectStackProtocolImplementation = class {
-  constructor(engine, getServicesRegistry, getFeedService) {
+  constructor(engine, getServicesRegistry, getFeedService, projectId) {
     this.engine = engine;
     this.getServicesRegistry = getServicesRegistry;
     this.getFeedService = getFeedService;
+    this.projectId = projectId;
+  }
+  /**
+   * 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() {
+    return this.projectId;
   }
   requireFeedService() {
     const svc = this.getFeedService?.();
@@ -641,7 +684,7 @@ var ObjectStackProtocolImplementation = class {
     };
   }
   async getMetaTypes() {
-    const schemaTypes = SchemaRegistry.getRegisteredTypes();
+    const schemaTypes = this.engine.registry.getRegisteredTypes();
     let runtimeTypes = [];
     try {
       const services = this.getServicesRegistry?.();
@@ -656,41 +699,58 @@ var ObjectStackProtocolImplementation = class {
   }
   async getMetaItems(request) {
     const { packageId } = request;
-    let items = SchemaRegistry.listItems(request.type, packageId);
-    if (items.length === 0) {
-      const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
-      if (alt) items = SchemaRegistry.listItems(alt, packageId);
+    let items = [];
+    if (this.projectId === void 0) {
+      items = [...this.engine.registry.listItems(request.type, packageId)];
+      if (items.length === 0) {
+        const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
+        if (alt) items = [...this.engine.registry.listItems(alt, packageId)];
+      }
+    } else {
+      items = [...this.engine.registry.listItems(request.type, packageId)];
+      if (items.length === 0) {
+        const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
+        if (alt) items = [...this.engine.registry.listItems(alt, packageId)];
+      }
     }
-    if (items.length === 0) {
-      try {
-        const whereClause = { type: request.type, state: "active" };
-        if (packageId) whereClause._packageId = packageId;
-        const allRecords = await this.engine.find("sys_metadata", {
-          where: whereClause
-        });
-        if (allRecords && allRecords.length > 0) {
-          items = allRecords.map((record) => {
-            const data = typeof record.metadata === "string" ? JSON.parse(record.metadata) : record.metadata;
-            SchemaRegistry.registerItem(request.type, data, "name");
-            return data;
-          });
-        } else {
-          const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
-          if (alt) {
-            const altRecords = await this.engine.find("sys_metadata", {
-              where: { type: alt, state: "active" }
-            });
-            if (altRecords && altRecords.length > 0) {
-              items = altRecords.map((record) => {
-                const data = typeof record.metadata === "string" ? JSON.parse(record.metadata) : record.metadata;
-                SchemaRegistry.registerItem(request.type, data, "name");
-                return data;
-              });
-            }
+    if (this.projectId === void 0) try {
+      const whereClause = {
+        type: request.type,
+        state: "active",
+        // Always filter by project_id: project kernels use their projectId,
+        // control-plane kernels use NULL (global scope only).
+        project_id: this.projectId ?? null
+      };
+      if (packageId) whereClause._packageId = packageId;
+      let records = await this.engine.find("sys_metadata", { where: whereClause });
+      if (!records || records.length === 0) {
+        const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
+        if (alt) {
+          const altWhere = { type: alt, state: "active", project_id: this.projectId ?? null };
+          if (packageId) altWhere._packageId = packageId;
+          records = await this.engine.find("sys_metadata", { where: altWhere });
+        }
+      }
+      if (records && records.length > 0) {
+        const byName = /* @__PURE__ */ new Map();
+        for (const existing of items) {
+          const entry = existing;
+          if (entry && typeof entry === "object" && "name" in entry) {
+            byName.set(entry.name, entry);
           }
         }
-      } catch {
+        for (const record of records) {
+          const data = typeof record.metadata === "string" ? JSON.parse(record.metadata) : record.metadata;
+          if (data && typeof data === "object" && "name" in data) {
+            byName.set(data.name, data);
+          }
+          if (this.projectId === void 0) {
+            this.engine.registry.registerItem(request.type, data, "name");
+          }
+        }
+        items = Array.from(byName.values());
       }
+    } catch {
     }
     try {
       const services = this.getServicesRegistry?.();
@@ -725,28 +785,41 @@ var ObjectStackProtocolImplementation = class {
     };
   }
   async getMetaItem(request) {
-    let item = SchemaRegistry.getItem(request.type, request.name);
-    if (item === void 0) {
-      const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
-      if (alt) item = SchemaRegistry.getItem(alt, request.name);
+    let item;
+    if (this.projectId === void 0) {
+      item = this.engine.registry.getItem(request.type, request.name);
+      if (item === void 0) {
+        const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
+        if (alt) item = this.engine.registry.getItem(alt, request.name);
+      }
     }
-    if (item === void 0) {
+    if (item === void 0 && this.projectId === void 0) {
       try {
+        const scopedWhere = {
+          type: request.type,
+          name: request.name,
+          state: "active"
+        };
+        scopedWhere.project_id = this.projectId ?? null;
         const record = await this.engine.findOne("sys_metadata", {
-          where: { type: request.type, name: request.name, state: "active" }
+          where: scopedWhere
         });
         if (record) {
           item = typeof record.metadata === "string" ? JSON.parse(record.metadata) : record.metadata;
-          SchemaRegistry.registerItem(request.type, item, "name");
+          if (this.projectId === void 0) {
+            this.engine.registry.registerItem(request.type, item, "name");
+          }
         } else {
           const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
           if (alt) {
-            const altRecord = await this.engine.findOne("sys_metadata", {
-              where: { type: alt, name: request.name, state: "active" }
-            });
+            const altWhere = { type: alt, name: request.name, state: "active" };
+            altWhere.project_id = this.projectId ?? null;
+            const altRecord = await this.engine.findOne("sys_metadata", { where: altWhere });
             if (altRecord) {
               item = typeof altRecord.metadata === "string" ? JSON.parse(altRecord.metadata) : altRecord.metadata;
-              SchemaRegistry.registerItem(request.type, item, "name");
+              if (this.projectId === void 0) {
+                this.engine.registry.registerItem(request.type, item, "name");
+              }
             }
           }
         }
@@ -770,7 +843,7 @@ var ObjectStackProtocolImplementation = class {
     };
   }
   async getUiView(request) {
-    const schema = SchemaRegistry.getObject(request.object);
+    const schema = this.engine.registry.getObject(request.object);
     if (!schema) throw new Error(`Object ${request.object} not found`);
     const fields = schema.fields || {};
     const fieldKeys = Object.keys(fields);
@@ -826,6 +899,9 @@ var ObjectStackProtocolImplementation = class {
   }
   async findData(request) {
     const options = { ...request.query };
+    if (request.context !== void 0) {
+      options.context = request.context;
+    }
     if (options.top != null) {
       options.limit = Number(options.top);
       delete options.top;
@@ -944,6 +1020,9 @@ var ObjectStackProtocolImplementation = class {
     const queryOptions = {
       where: { id: request.id }
     };
+    if (request.context !== void 0) {
+      queryOptions.context = request.context;
+    }
     if (request.select) {
       queryOptions.fields = typeof request.select === "string" ? request.select.split(",").map((s) => s.trim()).filter(Boolean) : request.select;
     }
@@ -965,7 +1044,11 @@ var ObjectStackProtocolImplementation = class {
     throw new Error(`Record ${request.id} not found in ${request.object}`);
   }
   async createData(request) {
-    const result = await this.engine.insert(request.object, request.data);
+    const result = await this.engine.insert(
+      request.object,
+      request.data,
+      request.context !== void 0 ? { context: request.context } : void 0
+    );
     return {
       object: request.object,
       id: result.id,
@@ -973,7 +1056,9 @@ var ObjectStackProtocolImplementation = class {
     };
   }
   async updateData(request) {
-    const result = await this.engine.update(request.object, request.data, { where: { id: request.id } });
+    const opts = { where: { id: request.id } };
+    if (request.context !== void 0) opts.context = request.context;
+    const result = await this.engine.update(request.object, request.data, opts);
     return {
       object: request.object,
       id: request.id,
@@ -981,7 +1066,9 @@ var ObjectStackProtocolImplementation = class {
     };
   }
   async deleteData(request) {
-    await this.engine.delete(request.object, { where: { id: request.id } });
+    const opts = { where: { id: request.id } };
+    if (request.context !== void 0) opts.context = request.context;
+    await this.engine.delete(request.object, opts);
     return {
       object: request.object,
       id: request.id,
@@ -993,10 +1080,10 @@ var ObjectStackProtocolImplementation = class {
   // ==========================================
   async getMetaItemCached(request) {
     try {
-      let item = SchemaRegistry.getItem(request.type, request.name);
+      let item = this.engine.registry.getItem(request.type, request.name);
       if (!item) {
         const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
-        if (alt) item = SchemaRegistry.getItem(alt, request.name);
+        if (alt) item = this.engine.registry.getItem(alt, request.name);
       }
       if (!item) {
         try {
@@ -1199,7 +1286,7 @@ var ObjectStackProtocolImplementation = class {
     };
   }
   async getAnalyticsMeta(request) {
-    const objects = SchemaRegistry.listItems("object");
+    const objects = this.engine.registry.listItems("object");
     const cubeFilter = request?.cube;
     const cubes = [];
     for (const obj of objects) {
@@ -1303,11 +1390,43 @@ var ObjectStackProtocolImplementation = class {
     if (!request.item) {
       throw new Error("Item data is required");
     }
-    SchemaRegistry.registerItem(request.type, request.item, "name");
+    if (this.projectId !== void 0) {
+      this.engine.registry.registerItem(request.type, request.item, "name");
+      if (request.type === "object" || request.type === "objects") {
+        try {
+          this.engine.registry.registerObject(request.item, "sys_metadata");
+        } catch (err) {
+          console.warn(
+            `[Protocol] registerObject failed for ${request.name}: ${err?.message ?? err}`
+          );
+        }
+      }
+      return {
+        success: true,
+        message: "Saved to memory registry (project kernel \u2014 sys_metadata is control-plane only)"
+      };
+    }
+    this.engine.registry.registerItem(request.type, request.item, "name");
+    if (request.type === "object" || request.type === "objects") {
+      try {
+        this.engine.registry.registerObject(request.item, "sys_metadata");
+      } catch (err) {
+        console.warn(
+          `[Protocol] this.engine.registry.registerObject failed for ${request.name}: ${err?.message ?? err}`
+        );
+      }
+    }
     try {
       const now = (/* @__PURE__ */ new Date()).toISOString();
+      const scopedWhere = {
+        type: request.type,
+        name: request.name
+      };
+      if (this.projectId !== void 0) {
+        scopedWhere.project_id = this.projectId;
+      }
       const existing = await this.engine.findOne("sys_metadata", {
-        where: { type: request.type, name: request.name }
+        where: scopedWhere
       });
       if (existing) {
         await this.engine.update("sys_metadata", {
@@ -1319,17 +1438,24 @@ var ObjectStackProtocolImplementation = class {
         });
       } else {
         const id = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `meta_${Date.now()}_${Math.random().toString(36).slice(2)}`;
-        await this.engine.insert("sys_metadata", {
+        const row = {
           id,
           name: request.name,
           type: request.type,
-          scope: "platform",
+          // `scope` tracks platform vs project authorship. With
+          // project_id carries the project id, 'project' is the
+          // honest label whenever we know we're inside one.
+          scope: this.projectId !== void 0 ? "project" : "platform",
           metadata: JSON.stringify(request.item),
           state: "active",
           version: 1,
           created_at: now,
           updated_at: now
-        });
+        };
+        if (this.projectId !== void 0) {
+          row.project_id = this.projectId;
+        }
+        await this.engine.insert("sys_metadata", row);
       }
       return {
         success: true,
@@ -1350,20 +1476,25 @@ var ObjectStackProtocolImplementation = class {
    * Safe to call repeatedly — idempotent (latest DB record wins).
    */
   async loadMetaFromDb() {
+    if (this.projectId !== void 0) {
+      return { loaded: 0, errors: 0 };
+    }
     let loaded = 0;
     let errors = 0;
     try {
-      const records = await this.engine.find("sys_metadata", {
-        where: { state: "active" }
-      });
+      const where = {
+        state: "active",
+        project_id: this.projectId ?? null
+      };
+      const records = await this.engine.find("sys_metadata", { where });
       for (const record of records) {
         try {
           const data = typeof record.metadata === "string" ? JSON.parse(record.metadata) : record.metadata;
           const normalizedType = PLURAL_TO_SINGULAR[record.type] ?? record.type;
           if (normalizedType === "object") {
-            SchemaRegistry.registerObject(data, record.packageId || "sys_metadata");
+            this.engine.registry.registerObject(data, record.packageId || "sys_metadata");
           } else {
-            SchemaRegistry.registerItem(normalizedType, data, "name");
+            this.engine.registry.registerItem(normalizedType, data, "name");
           }
           loaded++;
         } catch (e) {
@@ -1372,7 +1503,9 @@ var ObjectStackProtocolImplementation = class {
         }
       }
     } catch (e) {
-      console.warn(`[Protocol] DB hydration skipped: ${e.message}`);
+      if (!/no such table/i.test(e.message ?? "")) {
+        console.warn(`[Protocol] DB hydration skipped: ${e.message}`);
+      }
     }
     return { loaded, errors };
   }
@@ -1512,8 +1645,482 @@ var ObjectStackProtocolImplementation = class {
 // src/engine.ts
 import { ExecutionContextSchema } from "@objectstack/spec/kernel";
 import { createLogger } from "@objectstack/core";
-import { CoreServiceName } from "@objectstack/spec/system";
+import { CoreServiceName, StorageNameMapping } from "@objectstack/spec/system";
 import { pluralToSingular } from "@objectstack/spec/shared";
+import { ExpressionEngine as ExpressionEngine2 } from "@objectstack/formula";
+
+// src/hook-wrappers.ts
+import { ExpressionEngine } from "@objectstack/formula";
+
+// src/hook-metrics.ts
+var noopHookMetricsRecorder = {
+  recordExecution: () => {
+  },
+  recordSkip: () => {
+  },
+  recordRetry: () => {
+  }
+};
+var InMemoryHookMetricsRecorder = class {
+  constructor() {
+    this.executions = /* @__PURE__ */ new Map();
+    this.skips = /* @__PURE__ */ new Map();
+    this.retries = /* @__PURE__ */ new Map();
+  }
+  recordExecution(label, outcome, durationMs) {
+    const key = `${label.hook}|${outcome}`;
+    const cur = this.executions.get(key) ?? { count: 0, totalMs: 0 };
+    cur.count += 1;
+    cur.totalMs += Math.max(0, durationMs);
+    this.executions.set(key, cur);
+  }
+  recordSkip(label, reason) {
+    const key = `${label.hook}|${reason}`;
+    this.skips.set(key, (this.skips.get(key) ?? 0) + 1);
+  }
+  recordRetry(label, _attempt) {
+    this.retries.set(label.hook, (this.retries.get(label.hook) ?? 0) + 1);
+  }
+  snapshot() {
+    return {
+      executions: Array.from(this.executions, ([key, v]) => {
+        const [hook, outcome] = key.split("|");
+        return { hook, outcome, count: v.count, totalMs: v.totalMs };
+      }),
+      skips: Array.from(this.skips, ([key, count]) => {
+        const [hook, reason] = key.split("|");
+        return { hook, reason, count };
+      }),
+      retries: Array.from(this.retries, ([hook, count]) => ({ hook, count }))
+    };
+  }
+  reset() {
+    this.executions.clear();
+    this.skips.clear();
+    this.retries.clear();
+  }
+};
+
+// src/hook-wrappers.ts
+var noopLogger = {
+  debug: () => {
+  },
+  info: () => {
+  },
+  warn: () => {
+  },
+  error: () => {
+  }
+};
+function wrapDeclarativeHook(meta, handler, opts = {}) {
+  const logger = opts.logger ?? noopLogger;
+  const metrics = opts.metrics ?? noopHookMetricsRecorder;
+  const isAfterEvent = meta.events?.some((e) => typeof e === "string" && e.startsWith("after")) ?? false;
+  const hasBody = Boolean(meta.body);
+  const labelFor = (ctx) => ({
+    hook: meta.name,
+    object: ctx.object ?? (typeof meta.object === "string" ? meta.object : void 0),
+    event: ctx.event,
+    body: hasBody
+  });
+  let conditionFn;
+  if (meta.condition) {
+    const expr = typeof meta.condition === "string" ? { dialect: "cel", source: meta.condition } : meta.condition;
+    if (expr.source && expr.source.trim()) {
+      const check = ExpressionEngine.compile(expr);
+      if (check.ok) {
+        conditionFn = (record) => {
+          const r = ExpressionEngine.evaluate(expr, { record: record ?? {} });
+          if (!r.ok) {
+            logger.warn("[hook] condition evaluation failed; treating as false", {
+              hook: meta.name,
+              condition: expr.source,
+              error: r.error.message
+            });
+            return false;
+          }
+          return Boolean(r.value);
+        };
+      } else {
+        logger.warn("[hook] condition formula failed to compile; condition ignored", {
+          hook: meta.name,
+          condition: expr.source,
+          error: check.error.message
+        });
+      }
+    }
+  }
+  const retryMax = Math.max(0, Number(meta.retryPolicy?.maxRetries ?? 0));
+  const retryBackoffMs = Math.max(0, Number(meta.retryPolicy?.backoffMs ?? 0));
+  const timeoutMs = typeof meta.timeout === "number" && meta.timeout > 0 ? meta.timeout : void 0;
+  const onError = meta.onError ?? "abort";
+  const fireAndForget = Boolean(meta.async) && isAfterEvent;
+  const runWithTimeout = async (ctx) => {
+    if (!timeoutMs) {
+      await handler(ctx);
+      return;
+    }
+    let timer;
+    try {
+      await Promise.race([
+        Promise.resolve().then(() => handler(ctx)),
+        new Promise((_, reject) => {
+          timer = setTimeout(() => {
+            reject(new Error(`Hook '${meta.name}' timed out after ${timeoutMs}ms`));
+          }, timeoutMs);
+        })
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  };
+  const runWithRetry = async (ctx) => {
+    let attempt = 0;
+    let lastErr;
+    while (attempt <= retryMax) {
+      try {
+        await runWithTimeout(ctx);
+        return;
+      } catch (err) {
+        lastErr = err;
+        attempt += 1;
+        if (attempt > retryMax) break;
+        if (retryBackoffMs > 0) {
+          await new Promise((r) => setTimeout(r, retryBackoffMs * attempt));
+        }
+        try {
+          metrics.recordRetry(labelFor(ctx), attempt);
+        } catch {
+        }
+        logger.warn("[hook] retrying after failure", {
+          hook: meta.name,
+          attempt,
+          maxRetries: retryMax,
+          error: err?.message
+        });
+      }
+    }
+    throw lastErr;
+  };
+  const runWithErrorPolicy = async (ctx) => {
+    try {
+      await runWithRetry(ctx);
+    } catch (err) {
+      if (onError === "log") {
+        logger.error("[hook] handler failed (onError=log; suppressing)", {
+          hook: meta.name,
+          object: ctx.object,
+          event: ctx.event,
+          error: err?.message
+        });
+        return;
+      }
+      throw err;
+    }
+  };
+  return async (ctx) => {
+    if (conditionFn) {
+      const record = pickRecordPayload(ctx);
+      if (!conditionFn(record)) {
+        logger.debug("[hook] skipped by condition", {
+          hook: meta.name,
+          object: ctx.object,
+          event: ctx.event
+        });
+        try {
+          metrics.recordSkip(labelFor(ctx), "condition");
+        } catch {
+        }
+        return;
+      }
+    }
+    const restore = installFlatInput(ctx);
+    const startedAt = Date.now();
+    const recordOutcome = (err) => {
+      const elapsed = Date.now() - startedAt;
+      let outcome = "success";
+      if (err) {
+        const msg = String(err?.message ?? err ?? "");
+        if (/timed out after/i.test(msg)) outcome = "timeout";
+        else if (/capability|cap-rejection|capability_rejected/i.test(msg)) outcome = "capability_rejected";
+        else outcome = "error";
+      }
+      try {
+        metrics.recordExecution(labelFor(ctx), outcome, elapsed);
+      } catch {
+      }
+    };
+    try {
+      if (fireAndForget) {
+        try {
+          metrics.recordSkip(labelFor(ctx), "fire_and_forget");
+        } catch {
+        }
+        void runWithErrorPolicy(ctx).then(() => recordOutcome()).catch((err) => {
+          recordOutcome(err);
+          logger.error("[hook] async handler error (fire-and-forget)", {
+            hook: meta.name,
+            error: err?.message
+          });
+        });
+        return;
+      }
+      try {
+        await runWithErrorPolicy(ctx);
+        recordOutcome();
+      } catch (err) {
+        recordOutcome(err);
+        throw err;
+      }
+    } finally {
+      restore();
+    }
+  };
+}
+function installFlatInput(ctx) {
+  const raw = ctx.input ?? {};
+  const looksWrapped = raw && typeof raw === "object" && ("data" in raw || "options" in raw || "id" in raw || "ast" in raw);
+  if (!looksWrapped) return () => {
+  };
+  const ensureData = () => {
+    if (!raw.data || typeof raw.data !== "object") {
+      raw.data = {};
+    }
+    return raw.data;
+  };
+  const proxy = new Proxy(raw, {
+    get(target, prop, receiver) {
+      if (prop === "id" || prop === "options" || prop === "ast" || prop === "data") {
+        return Reflect.get(target, prop, receiver);
+      }
+      const data = target.data;
+      if (data && typeof data === "object" && prop in data) {
+        return data[prop];
+      }
+      return Reflect.get(target, prop, receiver);
+    },
+    set(target, prop, value) {
+      if (prop === "id" || prop === "options" || prop === "ast" || prop === "data") {
+        target[prop] = value;
+        return true;
+      }
+      ensureData()[prop] = value;
+      return true;
+    },
+    has(target, prop) {
+      if (prop === "id" || prop === "options" || prop === "ast" || prop === "data") {
+        return prop in target;
+      }
+      const data = target.data;
+      if (data && typeof data === "object" && prop in data) return true;
+      return prop in target;
+    },
+    ownKeys(target) {
+      const dataKeys = target.data && typeof target.data === "object" ? Object.keys(target.data) : [];
+      return Array.from(new Set(dataKeys));
+    },
+    getOwnPropertyDescriptor(target, prop) {
+      const data = target.data;
+      if (data && typeof data === "object" && prop in data) {
+        return { configurable: true, enumerable: true, writable: true, value: data[prop] };
+      }
+      if (prop === "id" || prop === "options" || prop === "ast" || prop === "data") {
+        const desc = Object.getOwnPropertyDescriptor(target, prop);
+        return desc ? { ...desc, enumerable: false } : void 0;
+      }
+      return Object.getOwnPropertyDescriptor(target, prop);
+    }
+  });
+  ctx.input = proxy;
+  return () => {
+    ctx.input = raw;
+  };
+}
+function pickRecordPayload(ctx) {
+  const input = ctx.input ?? {};
+  if (input && typeof input === "object" && input.data && typeof input.data === "object") {
+    return input.data;
+  }
+  if (ctx.previous && typeof ctx.previous === "object") {
+    return ctx.previous;
+  }
+  return input;
+}
+
+// src/hook-binder.ts
+var noopLogger2 = {
+  debug: () => {
+  },
+  info: () => {
+  },
+  warn: () => {
+  },
+  error: () => {
+  }
+};
+function bindHooksToEngine(engine, hooks, opts = {}) {
+  const logger = opts.logger ?? noopLogger2;
+  const result = { registered: 0, skipped: 0, errors: [] };
+  if (!Array.isArray(hooks) || hooks.length === 0) {
+    return result;
+  }
+  if (opts.packageId && typeof engine.unregisterHooksByPackage === "function") {
+    try {
+      engine.unregisterHooksByPackage(opts.packageId);
+    } catch (err) {
+      logger.warn("[hook-binder] unregister-by-package failed; continuing", {
+        packageId: opts.packageId,
+        error: err?.message
+      });
+    }
+  }
+  if (opts.functions && typeof engine.registerFunction === "function") {
+    for (const [name, fn] of Object.entries(opts.functions)) {
+      try {
+        engine.registerFunction(name, fn, opts.packageId);
+      } catch (err) {
+        logger.warn("[hook-binder] failed to register function", {
+          name,
+          error: err?.message
+        });
+      }
+    }
+  }
+  for (const hook of hooks) {
+    try {
+      const resolved = resolveHandler(engine, hook, opts);
+      if (!resolved) {
+        result.skipped += 1;
+        const reason = hook.body ? `hook body present but no bodyRunner supplied to bindHooksToEngine (runtime must wire QuickJSScriptRunner)` : typeof hook.handler === "string" ? `unknown function '${hook.handler}'` : "no handler";
+        result.errors.push({ hook: hook.name, reason });
+        if (opts.strict) {
+          throw new Error(`[hook-binder] strict: cannot bind hook '${hook.name}': ${reason}`);
+        }
+        logger.warn("[hook-binder] skipping hook with unresolved handler", {
+          hook: hook.name,
+          handler: hook.handler,
+          hasBody: Boolean(hook.body)
+        });
+        continue;
+      }
+      if (opts.warnLegacyHandler && !hook.body && typeof hook.handler === "string") {
+        logger.warn("[hook-binder] DEPRECATED: hook uses legacy handler ref without body", {
+          hook: hook.name,
+          handler: hook.handler,
+          hint: "Move the handler source into Hook.body so the artifact stays metadata-only and the .mjs runtime bundle can be dropped."
+        });
+      }
+      const wrapped = wrapDeclarativeHook(hook, resolved, { logger, metrics: opts.metrics });
+      const objects = normalizeObjects(hook.object);
+      const events = Array.isArray(hook.events) ? hook.events : [];
+      for (const event of events) {
+        for (const object of objects) {
+          engine.registerHook(event, wrapped, {
+            object,
+            priority: typeof hook.priority === "number" ? hook.priority : 100,
+            packageId: opts.packageId,
+            // Reflect metadata so future tooling can introspect / unregister
+            // and so we can detect duplicate name collisions.
+            // The engine ignores unknown options today; this is forward-only.
+            ...{ meta: hook, hookName: hook.name }
+          });
+          result.registered += 1;
+        }
+      }
+    } catch (err) {
+      result.errors.push({ hook: hook.name, reason: err?.message ?? String(err) });
+      logger.error("[hook-binder] failed to bind hook", {
+        hook: hook.name,
+        error: err?.message
+      });
+    }
+  }
+  if (result.registered > 0) {
+    logger.debug("[hook-binder] hooks bound", {
+      packageId: opts.packageId,
+      registered: result.registered,
+      skipped: result.skipped
+    });
+  }
+  return result;
+}
+function normalizeObjects(target) {
+  if (Array.isArray(target)) return target.length > 0 ? target : ["*"];
+  if (typeof target === "string" && target.length > 0) return [target];
+  return ["*"];
+}
+function resolveHandler(engine, hook, opts) {
+  const body = hook.body;
+  if (body && typeof body === "object") {
+    let runner = opts.bodyRunner;
+    if (typeof runner !== "function") {
+      const fallback = engine?._defaultBodyRunner;
+      if (typeof fallback === "function") runner = fallback;
+    }
+    if (typeof runner !== "function") {
+      return void 0;
+    }
+    const fn = runner(hook);
+    if (typeof fn === "function") return fn;
+    return void 0;
+  }
+  const h = hook.handler;
+  if (typeof h === "function") return h;
+  if (typeof h === "string" && h.length > 0) {
+    const fromBundle = opts.functions?.[h];
+    if (typeof fromBundle === "function") return fromBundle;
+    if (typeof engine.resolveFunction === "function") {
+      const fn = engine.resolveFunction(h);
+      if (typeof fn === "function") return fn;
+    }
+  }
+  return void 0;
+}
+
+// src/engine.ts
+function planFormulaProjection(schema, requestedFields) {
+  if (!schema?.fields) return { plan: [] };
+  const allFieldNames = Object.keys(schema.fields);
+  const targets = Array.isArray(requestedFields) && requestedFields.length > 0 ? requestedFields : allFieldNames;
+  const plan = [];
+  const projected = /* @__PURE__ */ new Set();
+  for (const f of targets) {
+    const def = schema.fields[f];
+    if (def?.type === "formula" && def.expression) {
+      const expr = typeof def.expression === "string" ? { dialect: "cel", source: def.expression } : def.expression;
+      plan.push({ name: f, expression: expr });
+      ExpressionEngine2.compile(expr);
+    } else if (Array.isArray(requestedFields) && requestedFields.length > 0) {
+      projected.add(f);
+    }
+  }
+  if (plan.length === 0) return { plan: [] };
+  if (Array.isArray(requestedFields) && requestedFields.length > 0) {
+    if (!projected.has("id")) projected.add("id");
+    for (const fname of allFieldNames) projected.add(fname);
+    return { plan, projected: Array.from(projected) };
+  }
+  return { plan };
+}
+function applyFormulaPlan(plan, records) {
+  if (!plan.length) return;
+  for (const rec of records) {
+    if (rec == null) continue;
+    for (const fp of plan) {
+      const r = ExpressionEngine2.evaluate(fp.expression, { record: rec });
+      rec[fp.name] = r.ok ? r.value : null;
+    }
+  }
+}
+function resolveMetadataItemName(key, item) {
+  if (!item) return void 0;
+  if (item.name) return item.name;
+  if (item.id) return item.id;
+  if (key === "views") {
+    return item?.list?.data?.object || item?.form?.data?.object || void 0;
+  }
+  return void 0;
+}
 var _ObjectQL = class _ObjectQL {
   constructor(hostContext = {}) {
     this.drivers = /* @__PURE__ */ new Map();
@@ -1537,10 +2144,29 @@ var _ObjectQL = class _ObjectQL {
     this.middlewares = [];
     // Action registry: key = "objectName:actionName"
     this.actions = /* @__PURE__ */ new Map();
+    // Function registry: name → handler. Used by `bindHooksToEngine` to
+    // resolve string-named hook handlers (the JSON-safe form). Populated by
+    // `defineStack({ functions })` via `AppPlugin`, or directly via
+    // `engine.registerFunction(...)`.
+    this.functions = /* @__PURE__ */ new Map();
     // Host provided context additions (e.g. Server router)
     this.hostContext = {};
+    // Per-engine SchemaRegistry instance.
+    //
+    // Historically SchemaRegistry was a process-wide singleton of static state,
+    // which broke multi-project servers: a project kernel would inherit every
+    // object registered by the control plane (e.g. sys_metadata), and
+    // getDriver()'s owner lookup would route CRUD to the wrong database. Each
+    // engine now owns its registry so kernels are fully isolated.
+    this._registry = new SchemaRegistry();
     this.hostContext = hostContext;
     this.logger = hostContext.logger || createLogger({ level: "info", format: "pretty" });
+    if (process?.env?.OBJECTQL_STRICT_HOOKS === "1") {
+      this._strictHookBinding = true;
+    }
+    if (process?.env?.OBJECTQL_WARN_LEGACY_HANDLER === "1") {
+      this._warnLegacyHandler = true;
+    }
     this.logger.info("ObjectQL Engine Instance Created");
   }
   /**
@@ -1556,10 +2182,13 @@ var _ObjectQL = class _ObjectQL {
     };
   }
   /**
-   * 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() {
-    return SchemaRegistry;
+    return this._registry;
   }
   /**
    * Load and Register a Plugin
@@ -1605,11 +2234,121 @@ var _ObjectQL = class _ObjectQL {
       handler,
       object: options?.object,
       priority: options?.priority ?? 100,
-      packageId: options?.packageId
+      packageId: options?.packageId,
+      meta: options?.meta,
+      hookName: options?.hookName
     });
     entries.sort((a, b) => a.priority - b.priority);
     this.logger.debug("Registered hook", { event, object: options?.object, priority: options?.priority ?? 100, totalHandlers: entries.length });
   }
+  /**
+   * 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) {
+    if (!packageId) return 0;
+    let removed = 0;
+    for (const [event, entries] of this.hooks.entries()) {
+      const before = entries.length;
+      const kept = entries.filter((e) => e.packageId !== packageId);
+      if (kept.length !== before) {
+        this.hooks.set(event, kept);
+        removed += before - kept.length;
+      }
+    }
+    if (removed > 0) {
+      this.logger.debug("Unregistered hooks by package", { packageId, removed });
+    }
+    return removed;
+  }
+  /**
+   * 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, handler, packageId) {
+    if (!name || typeof handler !== "function") return;
+    this.functions.set(name, { handler, packageId });
+    this.logger.debug("Registered function", { name, packageId });
+  }
+  /** Look up a registered function by name. */
+  resolveFunction(name) {
+    return this.functions.get(name)?.handler;
+  }
+  /** Remove all functions registered under a given `packageId`. */
+  unregisterFunctionsByPackage(packageId) {
+    if (!packageId) return 0;
+    let removed = 0;
+    for (const [name, entry] of this.functions.entries()) {
+      if (entry.packageId === packageId) {
+        this.functions.delete(name);
+        removed += 1;
+      }
+    }
+    if (removed > 0) {
+      this.logger.debug("Unregistered functions by package", { packageId, removed });
+    }
+    return removed;
+  }
+  /**
+   * 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, opts) {
+    const merged = { ...opts ?? {}, logger: this.logger };
+    if (!merged.bodyRunner && this._defaultBodyRunner) {
+      merged.bodyRunner = this._defaultBodyRunner;
+    }
+    if (merged.strict === void 0 && this._strictHookBinding) {
+      merged.strict = true;
+    }
+    if (merged.warnLegacyHandler === void 0 && this._warnLegacyHandler) {
+      merged.warnLegacyHandler = true;
+    }
+    if (!merged.metrics && this._hookMetricsRecorder) {
+      merged.metrics = this._hookMetricsRecorder;
+    }
+    bindHooksToEngine(this, hooks, merged);
+  }
+  /**
+   * 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) {
+    this._defaultBodyRunner = runner;
+  }
+  /**
+   * 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) {
+    this._strictHookBinding = strict;
+  }
+  /** Toggle deprecation warnings for hooks still using legacy `handler` ref. */
+  setWarnLegacyHandler(warn) {
+    this._warnLegacyHandler = warn;
+  }
+  /**
+   * 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) {
+    this._hookMetricsRecorder = recorder;
+  }
+  /** Read the engine's installed metrics recorder, if any. */
+  getHookMetricsRecorder() {
+    return this._hookMetricsRecorder;
+  }
   async triggerHooks(event, context) {
     const entries = this.hooks.get(event) || [];
     if (entries.length === 0) {
@@ -1705,6 +2444,62 @@ var _ObjectQL = class _ObjectQL {
       accessToken: execCtx.accessToken
     };
   }
+  /**
+   * 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).
+   */
+  buildHookApi(execCtx) {
+    const safeCtx = execCtx ?? { isSystem: true };
+    return new ScopedContext(safeCtx, this);
+  }
+  /**
+   * 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()\``.
+   */
+  applyFieldDefaults(object, record, execCtx, nowSnapshot) {
+    const schema = this.getSchema(object);
+    const fieldsRaw = schema?.fields;
+    if (!fieldsRaw || typeof fieldsRaw !== "object") return record;
+    const fieldEntries = Array.isArray(fieldsRaw) ? fieldsRaw : Object.entries(fieldsRaw).map(([name, def]) => ({ name, ...def }));
+    const out = { ...record };
+    const now = nowSnapshot ?? /* @__PURE__ */ new Date();
+    for (const f of fieldEntries) {
+      if (out[f.name] !== void 0) continue;
+      if (f.defaultValue == null) continue;
+      const dv = f.defaultValue;
+      if (typeof dv === "object" && dv !== null && dv.dialect && typeof dv.source === "string") {
+        const result = ExpressionEngine2.evaluate(dv, {
+          now,
+          user: execCtx?.userId ? { id: String(execCtx.userId), role: execCtx?.roles?.[0] } : void 0,
+          org: execCtx?.tenantId ? { id: String(execCtx.tenantId) } : void 0,
+          record: out,
+          extra: { object }
+        });
+        if (result.ok) {
+          out[f.name] = result.value;
+        } else {
+          this.logger.warn("Failed to evaluate default expression", {
+            object,
+            field: f.name,
+            error: result.error
+          });
+        }
+      } else {
+        out[f.name] = dv;
+      }
+    }
+    return out;
+  }
   /**
    * Register contribution (Manifest)
    * 
@@ -1719,23 +2514,24 @@ var _ObjectQL = class _ObjectQL {
     const id = manifest.id || manifest.name;
     const namespace = manifest.namespace;
     this.logger.debug("Registering package manifest", { id, namespace });
+    console.warn(`[ObjectQL:registerApp] id=${id} flows=${Array.isArray(manifest.flows) ? manifest.flows.length : typeof manifest.flows} keys=${Object.keys(manifest).join(",")}`);
     if (id) {
       this.manifests.set(id, manifest);
     }
-    SchemaRegistry.installPackage(manifest);
+    this._registry.installPackage(manifest);
     this.logger.debug("Installed Package", { id: manifest.id, name: manifest.name, namespace });
     if (manifest.objects) {
       if (Array.isArray(manifest.objects)) {
         this.logger.debug("Registering objects from manifest (Array)", { id, objectCount: manifest.objects.length });
         for (const objDef of manifest.objects) {
-          const fqn = SchemaRegistry.registerObject(objDef, id, namespace, "own");
+          const fqn = this._registry.registerObject(objDef, id, namespace, "own");
           this.logger.debug("Registered Object", { fqn, from: id });
         }
       } else {
         this.logger.debug("Registering objects from manifest (Map)", { id, objectCount: Object.keys(manifest.objects).length });
         for (const [name, objDef] of Object.entries(manifest.objects)) {
           objDef.name = name;
-          const fqn = SchemaRegistry.registerObject(objDef, id, namespace, "own");
+          const fqn = this._registry.registerObject(objDef, id, namespace, "own");
           this.logger.debug("Registered Object", { fqn, from: id });
         }
       }
@@ -1755,7 +2551,7 @@ var _ObjectQL = class _ObjectQL {
           validations: ext.validations,
           indexes: ext.indexes
         };
-        SchemaRegistry.registerObject(extDef, id, void 0, "extend", priority);
+        this._registry.registerObject(extDef, id, void 0, "extend", priority);
         this.logger.debug("Registered Object Extension", { target: targetFqn, priority, from: id });
       }
     }
@@ -1764,13 +2560,15 @@ var _ObjectQL = class _ObjectQL {
       for (const app of manifest.apps) {
         const appName = app.name || app.id;
         if (appName) {
-          SchemaRegistry.registerApp(app, id);
+          const resolved = namespace ? this.resolveNavObjectNames(app, namespace) : app;
+          this._registry.registerApp(resolved, id);
           this.logger.debug("Registered App", { app: appName, from: id });
         }
       }
     }
     if (manifest.name && manifest.navigation && !manifest.apps?.length) {
-      SchemaRegistry.registerApp(manifest, id);
+      const resolved = namespace ? this.resolveNavObjectNames(manifest, namespace) : manifest;
+      this._registry.registerApp(resolved, id);
       this.logger.debug("Registered manifest-as-app", { app: manifest.name, from: id });
     }
     const metadataArrayKeys = [
@@ -1809,9 +2607,12 @@ var _ObjectQL = class _ObjectQL {
       if (Array.isArray(items) && items.length > 0) {
         this.logger.debug(`Registering ${key} from manifest`, { id, count: items.length });
         for (const item of items) {
-          const itemName = item.name || item.id;
+          const itemName = resolveMetadataItemName(key, item);
           if (itemName) {
-            SchemaRegistry.registerItem(pluralToSingular(key), item, "name", id);
+            const toRegister = item.name === itemName ? item : { ...item, name: itemName };
+            this._registry.registerItem(pluralToSingular(key), toRegister, "name", id);
+          } else {
+            this.logger.warn(`Skipping ${pluralToSingular(key)} without a derivable name`, { id });
           }
         }
       }
@@ -1821,14 +2622,14 @@ var _ObjectQL = class _ObjectQL {
       this.logger.debug("Registering seed data datasets", { id, count: seedData.length });
       for (const dataset of seedData) {
         if (dataset.object) {
-          SchemaRegistry.registerItem("data", dataset, "object", id);
+          this._registry.registerItem("data", dataset, "object", id);
         }
       }
     }
     if (manifest.contributes?.kinds) {
       this.logger.debug("Registering kinds from manifest", { id, kindCount: manifest.contributes.kinds.length });
       for (const kind of manifest.contributes.kinds) {
-        SchemaRegistry.registerKind(kind);
+        this._registry.registerKind(kind);
         this.logger.debug("Registered Kind", { kind: kind.name || kind.type, from: id });
       }
     }
@@ -1843,6 +2644,25 @@ var _ObjectQL = class _ObjectQL {
       }
     }
   }
+  /**
+   * Deep-clone an app definition, resolving objectName references in navigation
+   * items via the registry. Object names are canonical identifiers — no FQN
+   * expansion is applied.
+   */
+  resolveNavObjectNames(app, namespace) {
+    if (!app.navigation) return app;
+    const resolveItems = (items) => items.map((item) => {
+      const resolved = { ...item };
+      if (resolved.objectName && !resolved.objectName.includes("__")) {
+        resolved.objectName = computeFQN(namespace, resolved.objectName);
+      }
+      if (Array.isArray(resolved.children)) {
+        resolved.children = resolveItems(resolved.children);
+      }
+      return resolved;
+    });
+    return { ...app, navigation: resolveItems(app.navigation) };
+  }
   /**
    * Register a nested plugin's metadata (objects, actions, views, etc.)
    *
@@ -1863,7 +2683,7 @@ var _ObjectQL = class _ObjectQL {
         if (Array.isArray(plugin.objects)) {
           this.logger.debug("Registering plugin objects (Array)", { pluginName, count: plugin.objects.length });
           for (const objDef of plugin.objects) {
-            const fqn = SchemaRegistry.registerObject(objDef, ownerId, pluginNamespace, "own");
+            const fqn = this._registry.registerObject(objDef, ownerId, pluginNamespace, "own");
             this.logger.debug("Registered Object", { fqn, from: pluginName });
           }
         } else {
@@ -1871,7 +2691,7 @@ var _ObjectQL = class _ObjectQL {
           this.logger.debug("Registering plugin objects (Map)", { pluginName, count: entries.length });
           for (const [name, objDef] of entries) {
             objDef.name = name;
-            const fqn = SchemaRegistry.registerObject(objDef, ownerId, pluginNamespace, "own");
+            const fqn = this._registry.registerObject(objDef, ownerId, pluginNamespace, "own");
             this.logger.debug("Registered Object", { fqn, from: pluginName });
           }
         }
@@ -1881,7 +2701,8 @@ var _ObjectQL = class _ObjectQL {
     }
     if (plugin.name && plugin.navigation) {
       try {
-        SchemaRegistry.registerApp(plugin, ownerId);
+        const resolved = pluginNamespace ? this.resolveNavObjectNames(plugin, pluginNamespace) : plugin;
+        this._registry.registerApp(resolved, ownerId);
         this.logger.debug("Registered plugin-as-app", { app: plugin.name, from: pluginName });
       } catch (err) {
         this.logger.warn("Failed to register plugin as app", { pluginName, error: err.message });
@@ -1915,9 +2736,10 @@ var _ObjectQL = class _ObjectQL {
       const items = plugin[key];
       if (Array.isArray(items) && items.length > 0) {
         for (const item of items) {
-          const itemName = item.name || item.id;
+          const itemName = resolveMetadataItemName(key, item);
           if (itemName) {
-            SchemaRegistry.registerItem(pluralToSingular(key), item, "name", ownerId);
+            const toRegister = item.name === itemName ? item : { ...item, name: itemName };
+            this._registry.registerItem(pluralToSingular(key), toRegister, "name", ownerId);
           }
         }
       }
@@ -1955,24 +2777,21 @@ var _ObjectQL = class _ObjectQL {
    * Helper to get object definition
    */
   getSchema(objectName) {
-    return SchemaRegistry.getObject(objectName);
+    return this._registry.getObject(objectName);
   }
   /**
-   * 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.
+   * Resolve any object identifier to the physical storage name used by drivers.
+   *
+   * 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`.
    */
   resolveObjectName(name) {
-    const schema = SchemaRegistry.getObject(name);
+    const schema = this._registry.getObject(name);
     if (schema) {
-      return schema.tableName || schema.name;
+      return StorageNameMapping.resolveTableName(schema);
     }
-    return name;
+    return StorageNameMapping.resolveTableName({ name });
   }
   /**
    * Helper to get the target driver
@@ -1984,7 +2803,7 @@ var _ObjectQL = class _ObjectQL {
    * 4. Global default driver
    */
   getDriver(objectName) {
-    const object = SchemaRegistry.getObject(objectName);
+    const object = this._registry.getObject(objectName);
     if (object?.datasource && object.datasource !== "default") {
       if (this.drivers.has(object.datasource)) {
         return this.drivers.get(object.datasource);
@@ -2000,7 +2819,7 @@ var _ObjectQL = class _ObjectQL {
       return this.drivers.get(mappedDatasource);
     }
     const fqn = object?.name || objectName;
-    const owner = SchemaRegistry.getObjectOwner(fqn);
+    const owner = this._registry.getObjectOwner(fqn);
     if (owner?.packageId) {
       const manifest = this.manifests.get(owner.packageId);
       if (manifest?.defaultDatasource && manifest.defaultDatasource !== "default") {
@@ -2121,7 +2940,7 @@ var _ObjectQL = class _ObjectQL {
   async expandRelatedRecords(objectName, records, expand, depth = 0) {
     if (!records || records.length === 0) return records;
     if (depth >= _ObjectQL.MAX_EXPAND_DEPTH) return records;
-    const objectSchema = SchemaRegistry.getObject(objectName);
+    const objectSchema = this._registry.getObject(objectName);
     if (!objectSchema || !objectSchema.fields) return records;
     for (const [fieldName, nestedAST] of Object.entries(expand)) {
       const fieldDef = objectSchema.fields[fieldName];
@@ -2202,6 +3021,20 @@ var _ObjectQL = class _ObjectQL {
       ast.limit = ast.top;
     }
     delete ast.top;
+    const _findSchema = this._registry.getObject(object);
+    const _findFormula = planFormulaProjection(_findSchema, ast.fields);
+    if (_findFormula.projected) ast.fields = _findFormula.projected;
+    if (_findSchema?.fields && Array.isArray(ast.fields) && ast.fields.length > 0) {
+      const known = new Set(Object.keys(_findSchema.fields));
+      known.add("id");
+      known.add("created_at");
+      known.add("updated_at");
+      const filtered = ast.fields.filter((f) => {
+        const head = String(f).split(".")[0];
+        return known.has(head);
+      });
+      ast.fields = filtered.length > 0 ? filtered : void 0;
+    }
     const opCtx = {
       object,
       operation: "find",
@@ -2215,12 +3048,14 @@ var _ObjectQL = class _ObjectQL {
         event: "beforeFind",
         input: { ast: opCtx.ast, options: opCtx.options },
         session: this.buildSession(opCtx.context),
+        api: this.buildHookApi(opCtx.context),
         transaction: opCtx.context?.transaction,
         ql: this
       };
       await this.triggerHooks("beforeFind", hookContext);
       try {
         let result = await driver.find(object, hookContext.input.ast, hookContext.input.options);
+        if (Array.isArray(result)) applyFormulaPlan(_findFormula.plan, result);
         if (ast.expand && Object.keys(ast.expand).length > 0 && Array.isArray(result)) {
           result = await this.expandRelatedRecords(object, result, ast.expand, 0);
         }
@@ -2242,6 +3077,17 @@ var _ObjectQL = class _ObjectQL {
     const ast = { object: objectName, ...query, limit: 1 };
     delete ast.context;
     delete ast.top;
+    const _findOneSchema = this._registry.getObject(objectName);
+    const _findOneFormula = planFormulaProjection(_findOneSchema, ast.fields);
+    if (_findOneFormula.projected) ast.fields = _findOneFormula.projected;
+    if (_findOneSchema?.fields && Array.isArray(ast.fields) && ast.fields.length > 0) {
+      const known = new Set(Object.keys(_findOneSchema.fields));
+      known.add("id");
+      known.add("created_at");
+      known.add("updated_at");
+      const filtered = ast.fields.filter((f) => known.has(String(f).split(".")[0]));
+      ast.fields = filtered.length > 0 ? filtered : void 0;
+    }
     const opCtx = {
       object: objectName,
       operation: "findOne",
@@ -2251,6 +3097,7 @@ var _ObjectQL = class _ObjectQL {
     };
     await this.executeWithMiddleware(opCtx, async () => {
       let result = await driver.findOne(objectName, opCtx.ast);
+      if (result != null) applyFormulaPlan(_findOneFormula.plan, [result]);
       if (ast.expand && Object.keys(ast.expand).length > 0 && result != null) {
         const expanded = await this.expandRelatedRecords(objectName, [result], ast.expand, 0);
         result = expanded[0];
@@ -2276,20 +3123,31 @@ var _ObjectQL = class _ObjectQL {
         event: "beforeInsert",
         input: { data: opCtx.data, options: opCtx.options },
         session: this.buildSession(opCtx.context),
+        api: this.buildHookApi(opCtx.context),
         transaction: opCtx.context?.transaction,
         ql: this
       };
       await this.triggerHooks("beforeInsert", hookContext);
       try {
         let result;
+        const nowSnap = /* @__PURE__ */ new Date();
         if (Array.isArray(hookContext.input.data)) {
+          const rows = hookContext.input.data.map(
+            (row) => this.applyFieldDefaults(object, row, opCtx.context, nowSnap)
+          );
           if (driver.bulkCreate) {
-            result = await driver.bulkCreate(object, hookContext.input.data, hookContext.input.options);
+            result = await driver.bulkCreate(object, rows, hookContext.input.options);
           } else {
-            result = await Promise.all(hookContext.input.data.map((item) => driver.create(object, item, hookContext.input.options)));
+            result = await Promise.all(rows.map((item) => driver.create(object, item, hookContext.input.options)));
           }
         } else {
-          result = await driver.create(object, hookContext.input.data, hookContext.input.options);
+          const row = this.applyFieldDefaults(
+            object,
+            hookContext.input.data,
+            opCtx.context,
+            nowSnap
+          );
+          result = await driver.create(object, row, hookContext.input.options);
         }
         hookContext.event = "afterInsert";
         hookContext.result = result;
@@ -2356,6 +3214,7 @@ var _ObjectQL = class _ObjectQL {
         event: "beforeUpdate",
         input: { id, data: opCtx.data, options: opCtx.options },
         session: this.buildSession(opCtx.context),
+        api: this.buildHookApi(opCtx.context),
         transaction: opCtx.context?.transaction,
         ql: this
       };
@@ -2421,6 +3280,7 @@ var _ObjectQL = class _ObjectQL {
         event: "beforeDelete",
         input: { id, options: opCtx.options },
         session: this.buildSession(opCtx.context),
+        api: this.buildHookApi(opCtx.context),
         transaction: opCtx.context?.transaction,
         ql: this
       };
@@ -2500,18 +3360,42 @@ var _ObjectQL = class _ObjectQL {
         groupBy: query.groupBy,
         aggregations: query.aggregations
       };
+      const drv = driver;
+      if (typeof drv.aggregate === "function") {
+        return drv.aggregate(object, ast);
+      }
       return driver.find(object, ast);
     });
     return opCtx.result;
   }
   async execute(command, options) {
+    let driver;
     if (options?.object) {
-      const driver = this.getDriver(options.object);
-      if (driver.execute) {
-        return driver.execute(command, void 0, options);
+      driver = this.getDriver(options.object);
+    } else if (options?.datasource && this.drivers.has(options.datasource)) {
+      driver = this.drivers.get(options.datasource);
+    } else if (this.defaultDriver && this.drivers.has(this.defaultDriver)) {
+      driver = this.drivers.get(this.defaultDriver);
+    } else if (this.drivers.size === 1) {
+      driver = this.drivers.values().next().value;
+    }
+    if (!driver) {
+      throw new Error(
+        "Execute requires options.object to select a driver, or a default driver to be configured. Configure datasourceMapping with `default: true` or pass `{ object }` / `{ datasource }` in options."
+      );
+    }
+    if (!driver.execute) {
+      throw new Error("Selected driver does not implement execute()");
+    }
+    let rawCommand = command;
+    let params = options?.args ?? options?.params;
+    if (command && typeof command === "object" && !Array.isArray(command) && "sql" in command) {
+      rawCommand = command.sql;
+      if (params === void 0) {
+        params = command.args ?? command.params;
       }
     }
-    throw new Error("Execute requires options.object to select driver");
+    return driver.execute(rawCommand, params, options);
   }
   // ============================================
   // Compatibility / Convenience API
@@ -2532,16 +3416,16 @@ var _ObjectQL = class _ObjectQL {
         }
       }
     }
-    return SchemaRegistry.registerObject(schema, packageId, namespace);
+    return this._registry.registerObject(schema, packageId, namespace);
   }
   /**
    * Unregister a single object by name.
    */
   unregisterObject(name, packageId) {
     if (packageId) {
-      SchemaRegistry.unregisterObjectsByPackage(packageId);
+      this._registry.unregisterObjectsByPackage(packageId);
     } else {
-      SchemaRegistry.unregisterItem("object", name);
+      this._registry.unregisterItem("object", name);
     }
   }
   /**
@@ -2557,7 +3441,7 @@ var _ObjectQL = class _ObjectQL {
    */
   getConfigs() {
     const result = {};
-    const objects = SchemaRegistry.getAllObjects();
+    const objects = this._registry.getAllObjects();
     for (const obj of objects) {
       if (obj.name) {
         result[obj.name] = obj;
@@ -2591,10 +3475,32 @@ var _ObjectQL = class _ObjectQL {
       return void 0;
     }
   }
+  /**
+   * 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.
+   */
+  async syncSchemas() {
+    const allObjects = this._registry.getAllObjects();
+    for (const obj of allObjects) {
+      const driver = this.getDriverForObject(obj.name);
+      if (!driver) continue;
+      const tableName = StorageNameMapping.resolveTableName(obj);
+      if (typeof driver.syncSchemasBatch === "function" && driver.supports?.batchSchemaSync) {
+      }
+      if (typeof driver.syncSchema === "function") {
+        try {
+          await driver.syncSchema(tableName, obj);
+        } catch {
+        }
+      }
+    }
+  }
   /**
    * Get a registered driver by datasource name.
    * Alias matching @objectql/core datasource() API.
-   * 
+   *
    * @throws Error if the datasource is not found
    */
   datasource(name) {
@@ -2625,7 +3531,7 @@ var _ObjectQL = class _ObjectQL {
       }
     }
     this.removeActionsByPackage(packageId);
-    SchemaRegistry.unregisterObjectsByPackage(packageId, true);
+    this._registry.unregisterObjectsByPackage(packageId, true);
   }
   /**
    * Gracefully shut down the engine, disconnecting all drivers.
@@ -2841,83 +3747,87 @@ var ScopedContext = class _ScopedContext {
 
 // src/metadata-facade.ts
 var MetadataFacade = class {
+  constructor(registry) {
+    this.registry = registry;
+  }
   /**
    * Register a metadata item
    */
   async register(type, name, data) {
     const definition = typeof data === "object" && data !== null ? { ...data, name: data.name ?? name } : data;
     if (type === "object") {
-      SchemaRegistry.registerItem(type, definition, "name");
+      this.registry.registerItem(type, definition, "name");
     } else {
-      SchemaRegistry.registerItem(type, definition, definition.id ? "id" : "name");
+      this.registry.registerItem(type, definition, definition.id ? "id" : "name");
     }
   }
   /**
    * Get a metadata item by type and name
    */
   async get(type, name) {
-    const item = SchemaRegistry.getItem(type, name);
+    const item = this.registry.getItem(type, name);
     return item?.content ?? item;
   }
   /**
    * Get the raw entry (with metadata wrapper)
    */
   getEntry(type, name) {
-    return SchemaRegistry.getItem(type, name);
+    return this.registry.getItem(type, name);
   }
   /**
    * List all items of a type
    */
   async list(type) {
-    const items = SchemaRegistry.listItems(type);
+    const items = this.registry.listItems(type);
     return items.map((item) => item?.content ?? item);
   }
   /**
    * Unregister a metadata item
    */
   async unregister(type, name) {
-    SchemaRegistry.unregisterItem(type, name);
+    this.registry.unregisterItem(type, name);
   }
   /**
    * Check if a metadata item exists
    */
   async exists(type, name) {
-    const item = SchemaRegistry.getItem(type, name);
+    const item = this.registry.getItem(type, name);
     return item !== void 0 && item !== null;
   }
   /**
    * List all names of metadata items of a given type
    */
   async listNames(type) {
-    const items = SchemaRegistry.listItems(type);
+    const items = this.registry.listItems(type);
     return items.map((item) => item?.name ?? item?.content?.name ?? "").filter(Boolean);
   }
   /**
    * Unregister all metadata from a package
    */
   async unregisterPackage(packageName) {
-    SchemaRegistry.unregisterObjectsByPackage(packageName);
+    this.registry.unregisterObjectsByPackage(packageName);
   }
   /**
    * Convenience: get object definition
    */
   async getObject(name) {
-    return SchemaRegistry.getObject(name);
+    return this.registry.getObject(name);
   }
   /**
    * Convenience: list all objects
    */
   async listObjects() {
-    return SchemaRegistry.getAllObjects();
+    return this.registry.getAllObjects();
   }
 };
 
 // src/plugin.ts
+import { StorageNameMapping as StorageNameMapping2 } from "@objectstack/spec/system";
 function hasLoadMetaFromDb(service) {
   return typeof service === "object" && service !== null && typeof service["loadMetaFromDb"] === "function";
 }
 var ObjectQLPlugin = class {
-  constructor(ql, hostContext) {
+  constructor(qlOrOptions, hostContext) {
     this.name = "com.objectstack.engine.objectql";
     this.type = "objectql";
     this.version = "1.0.0";
@@ -2942,7 +3852,9 @@ var ObjectQLPlugin = class {
       });
       const protocolShim = new ObjectStackProtocolImplementation(
         this.ql,
-        () => ctx.getServices ? ctx.getServices() : /* @__PURE__ */ new Map()
+        () => ctx.getServices ? ctx.getServices() : /* @__PURE__ */ new Map(),
+        void 0,
+        this.projectId
       );
       ctx.registerService("protocol", protocolShim);
       ctx.logger.info("Protocol service registered");
@@ -2985,103 +3897,172 @@ var ObjectQLPlugin = class {
         }
       }
       await this.ql?.init();
-      await this.restoreMetadataFromDb(ctx);
       await this.syncRegisteredSchemas(ctx);
-      await this.bridgeObjectsToMetadataService(ctx);
+      if (this.projectId === void 0) {
+        await this.restoreMetadataFromDb(ctx);
+      } else {
+        ctx.logger.info("Project kernel \u2014 skipping sys_metadata hydration (metadata sourced from artifact)");
+      }
+      await this.syncRegisteredSchemas(ctx);
+      if (this.projectId === void 0) {
+        await this.bridgeObjectsToMetadataService(ctx);
+      }
       this.registerAuditHooks(ctx);
-      this.registerTenantMiddleware(ctx);
       ctx.logger.info("ObjectQL engine started", {
         driversRegistered: this.ql?.["drivers"]?.size || 0,
         objectsRegistered: this.ql?.registry?.getAllObjects?.()?.length || 0
       });
     };
-    if (ql) {
-      this.ql = ql;
-    } else {
+    if (qlOrOptions instanceof ObjectQL) {
+      this.ql = qlOrOptions;
       this.hostContext = hostContext;
+      return;
+    }
+    const opts = qlOrOptions ?? {};
+    if (opts.ql) {
+      this.ql = opts.ql;
     }
+    this.hostContext = opts.hostContext ?? hostContext;
+    this.projectId = opts.projectId;
   }
   /**
    * 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).
    */
   registerAuditHooks(ctx) {
     if (!this.ql) return;
-    this.ql.registerHook("beforeInsert", async (hookCtx) => {
-      if (hookCtx.session?.userId && hookCtx.input?.data) {
-        const data = hookCtx.input.data;
-        if (typeof data === "object" && data !== null) {
-          data.created_by = data.created_by ?? hookCtx.session.userId;
-          data.updated_by = hookCtx.session.userId;
-          data.created_at = data.created_at ?? (/* @__PURE__ */ new Date()).toISOString();
-          data.updated_at = (/* @__PURE__ */ new Date()).toISOString();
-          if (hookCtx.session.tenantId) {
-            data.tenant_id = data.tenant_id ?? hookCtx.session.tenantId;
-          }
+    const stamp = () => (/* @__PURE__ */ new Date()).toISOString();
+    const hasField = (objectName, field) => {
+      try {
+        const schema = this.ql?.getSchema?.(objectName);
+        if (!schema || typeof schema !== "object") return false;
+        const fields = schema.fields;
+        if (!fields || typeof fields !== "object") return false;
+        return Object.prototype.hasOwnProperty.call(fields, field);
+      } catch {
+        return false;
+      }
+    };
+    const applyToRecord = (record, objectName, session, isInsert) => {
+      const now = stamp();
+      if (isInsert) {
+        record.created_at = record.created_at ?? now;
+      }
+      record.updated_at = now;
+      if (session?.userId) {
+        if (isInsert && hasField(objectName, "created_by")) {
+          record.created_by = record.created_by ?? session.userId;
         }
+        if (hasField(objectName, "updated_by")) {
+          record.updated_by = session.userId;
+        }
+      }
+      if (isInsert && session?.tenantId && hasField(objectName, "tenant_id")) {
+        record.tenant_id = record.tenant_id ?? session.tenantId;
       }
-    }, { object: "*", priority: 10 });
-    this.ql.registerHook("beforeUpdate", async (hookCtx) => {
-      if (hookCtx.session?.userId && hookCtx.input?.data) {
-        const data = hookCtx.input.data;
-        if (typeof data === "object" && data !== null) {
-          data.updated_by = hookCtx.session.userId;
-          data.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+    };
+    const stampData = (data, objectName, session, isInsert) => {
+      if (Array.isArray(data)) {
+        for (const row of data) {
+          if (row && typeof row === "object") {
+            applyToRecord(row, objectName, session, isInsert);
+          }
         }
+      } else if (data && typeof data === "object") {
+        applyToRecord(data, objectName, session, isInsert);
       }
-    }, { object: "*", priority: 10 });
-    this.ql.registerHook("beforeUpdate", async (hookCtx) => {
-      if (hookCtx.input?.id && !hookCtx.previous) {
-        try {
-          const existing = await this.ql.findOne(hookCtx.object, {
-            where: { id: hookCtx.input.id }
-          });
-          if (existing) {
-            hookCtx.previous = existing;
+    };
+    const builtinHooks = [
+      {
+        name: "sys_stamp_audit_insert",
+        object: "*",
+        events: ["beforeInsert"],
+        priority: 10,
+        description: "Auto-stamp created_by / updated_by / created_at / updated_at / tenant_id on insert (only when the field exists on the object schema)",
+        handler: async (hookCtx) => {
+          if (hookCtx.input?.data) {
+            stampData(hookCtx.input.data, hookCtx.object, hookCtx.session, true);
+          }
+        }
+      },
+      {
+        name: "sys_stamp_audit_update",
+        object: "*",
+        events: ["beforeUpdate"],
+        priority: 10,
+        description: "Auto-stamp updated_by / updated_at on update (only when the field exists on the object schema)",
+        handler: async (hookCtx) => {
+          if (hookCtx.input?.data) {
+            stampData(hookCtx.input.data, hookCtx.object, hookCtx.session, false);
+          }
+        }
+      },
+      {
+        name: "sys_fetch_previous_update",
+        object: "*",
+        events: ["beforeUpdate"],
+        priority: 5,
+        description: "Auto-fetch the previous record for update hooks",
+        handler: async (hookCtx) => {
+          if (hookCtx.input?.id && !hookCtx.previous) {
+            try {
+              const existing = await this.ql.findOne(hookCtx.object, {
+                where: { id: hookCtx.input.id }
+              });
+              if (existing) hookCtx.previous = existing;
+            } catch (_e) {
+            }
+          }
+        }
+      },
+      {
+        name: "sys_fetch_previous_delete",
+        object: "*",
+        events: ["beforeDelete"],
+        priority: 5,
+        description: "Auto-fetch the previous record for delete hooks",
+        handler: async (hookCtx) => {
+          if (hookCtx.input?.id && !hookCtx.previous) {
+            try {
+              const existing = await this.ql.findOne(hookCtx.object, {
+                where: { id: hookCtx.input.id }
+              });
+              if (existing) hookCtx.previous = existing;
+            } catch (_e) {
+            }
           }
-        } catch (_e) {
         }
       }
-    }, { object: "*", priority: 5 });
-    this.ql.registerHook("beforeDelete", async (hookCtx) => {
-      if (hookCtx.input?.id && !hookCtx.previous) {
-        try {
-          const existing = await this.ql.findOne(hookCtx.object, {
-            where: { id: hookCtx.input.id }
+    ];
+    if (typeof this.ql.bindHooks === "function") {
+      this.ql.bindHooks(builtinHooks, { packageId: "sys:audit" });
+    } else {
+      for (const h of builtinHooks) {
+        for (const event of h.events) {
+          this.ql.registerHook(event, h.handler, {
+            object: h.object,
+            priority: h.priority,
+            packageId: "sys:audit"
           });
-          if (existing) {
-            hookCtx.previous = existing;
-          }
-        } catch (_e) {
         }
       }
-    }, { object: "*", priority: 5 });
-    ctx.logger.debug("Audit hooks registered (created_by/updated_by, previousData)");
+    }
+    ctx.logger.debug("Audit hooks registered via binder (created_by/updated_by, previousData)");
   }
   /**
-   * 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.
    */
-  registerTenantMiddleware(ctx) {
-    if (!this.ql) return;
-    this.ql.registerMiddleware(async (opCtx, next) => {
-      if (!opCtx.context?.tenantId || opCtx.context?.isSystem) {
-        return next();
-      }
-      if (["find", "findOne", "count", "aggregate"].includes(opCtx.operation)) {
-        if (opCtx.ast) {
-          const tenantFilter = { tenant_id: opCtx.context.tenantId };
-          if (opCtx.ast.where) {
-            opCtx.ast.where = { $and: [opCtx.ast.where, tenantFilter] };
-          } else {
-            opCtx.ast.where = tenantFilter;
-          }
-        }
-      }
-      await next();
-    });
-    ctx.logger.debug("Tenant isolation middleware registered");
-  }
   /**
    * Synchronize all registered object schemas to the database.
    *
@@ -3120,7 +4101,7 @@ var ObjectQLPlugin = class {
         skipped++;
         continue;
       }
-      const tableName = obj.tableName || obj.name;
+      const tableName = StorageNameMapping2.resolveTableName(obj);
       let group = driverGroups.get(driver);
       if (!group) {
         group = [];
@@ -3277,13 +4258,20 @@ var ObjectQLPlugin = class {
    */
   async loadMetadataFromService(metadataService, ctx) {
     ctx.logger.info("Syncing metadata from external service into ObjectQL registry...");
-    const metadataTypes = ["object", "view", "app", "flow", "workflow", "function"];
+    const metadataTypes = ["object", "view", "app", "flow", "workflow", "function", "hook"];
     let totalLoaded = 0;
     for (const type of metadataTypes) {
       try {
         if (typeof metadataService.loadMany === "function") {
           const items = await metadataService.loadMany(type);
           if (items && items.length > 0) {
+            if (type === "function" && this.ql && typeof this.ql.registerFunction === "function") {
+              for (const item of items) {
+                if (item?.name && typeof item.handler === "function") {
+                  this.ql.registerFunction(item.name, item.handler, "metadata-service");
+                }
+              }
+            }
             items.forEach((item) => {
               const keyField = item.id ? "id" : "name";
               if (type === "object" && this.ql) {
@@ -3293,6 +4281,11 @@ var ObjectQLPlugin = class {
                 this.ql.registry.registerItem(type, item, keyField);
               }
             });
+            if (type === "hook" && this.ql && typeof this.ql.bindHooks === "function") {
+              this.ql.bindHooks(items, {
+                packageId: "metadata-service"
+              });
+            }
             totalLoaded += items.length;
             ctx.logger.info(`Synced ${items.length} ${type}(s) from metadata service`);
           }
@@ -3408,6 +4401,7 @@ function convertIntrospectedSchemaToObjects(introspectedSchema, options) {
 export {
   DEFAULT_EXTENDER_PRIORITY,
   DEFAULT_OWNER_PRIORITY,
+  InMemoryHookMetricsRecorder,
   MetadataFacade,
   ObjectQL,
   ObjectQLPlugin,
@@ -3416,10 +4410,14 @@ export {
   RESERVED_NAMESPACES,
   SchemaRegistry,
   ScopedContext,
+  applySystemFields,
+  bindHooksToEngine,
   computeFQN,
   convertIntrospectedSchemaToObjects,
   createObjectQLKernel,
+  noopHookMetricsRecorder,
   parseFQN,
-  toTitleCase
+  toTitleCase,
+  wrapDeclarativeHook
 };
 //# sourceMappingURL=index.mjs.map