@objectstack/objectql 4.0.4 → 4.1.0

package/dist/index.js

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   DEFAULT_EXTENDER_PRIORITY: () => DEFAULT_EXTENDER_PRIORITY,
   DEFAULT_OWNER_PRIORITY: () => DEFAULT_OWNER_PRIORITY,
+  InMemoryHookMetricsRecorder: () => InMemoryHookMetricsRecorder,
   MetadataFacade: () => MetadataFacade,
   ObjectQL: () => ObjectQL,
   ObjectQLPlugin: () => ObjectQLPlugin,
@@ -30,11 +31,19 @@ __export(index_exports, {
   RESERVED_NAMESPACES: () => RESERVED_NAMESPACES,
   SchemaRegistry: () => SchemaRegistry,
   ScopedContext: () => ScopedContext,
+  ValidationError: () => ValidationError,
+  applyInMemoryAggregation: () => applyInMemoryAggregation,
+  applySystemFields: () => applySystemFields,
+  bindHooksToEngine: () => bindHooksToEngine,
+  bucketDateValue: () => bucketDateValue,
   computeFQN: () => computeFQN,
   convertIntrospectedSchemaToObjects: () => convertIntrospectedSchemaToObjects,
   createObjectQLKernel: () => createObjectQLKernel,
+  noopHookMetricsRecorder: () => noopHookMetricsRecorder,
   parseFQN: () => parseFQN,
-  toTitleCase: () => toTitleCase
+  toTitleCase: () => toTitleCase,
+  validateRecord: () => validateRecord,
+  wrapDeclarativeHook: () => wrapDeclarativeHook
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -45,11 +54,8 @@ var import_ui = require("@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("__");
@@ -77,14 +83,111 @@ 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 === "better-auth") return schema;
+  const sf = typeof schema.systemFields === "object" && schema.systemFields !== null ? schema.systemFields : void 0;
+  const tenancyDisabled = schema.tenancy?.enabled === false;
+  const wantTenant = opts.multiTenant && sf?.tenant !== false && !tenancyDisabled;
+  const wantAudit = sf?.audit !== 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,
+      system: true,
+      description: "Tenant scope (auto-populated by SecurityPlugin on insert)."
+    };
+  }
+  if (wantAudit) {
+    if (!schema.fields?.created_at) {
+      additions.created_at = {
+        type: "datetime",
+        label: "Created At",
+        required: false,
+        readonly: true,
+        system: true,
+        description: "Timestamp when the record was created (auto-populated by the driver)."
+      };
+    }
+    if (!schema.fields?.created_by) {
+      additions.created_by = {
+        type: "lookup",
+        reference: "sys_user",
+        label: "Created By",
+        required: false,
+        readonly: true,
+        system: true,
+        description: "User who created the record (populated when an authenticated session is present)."
+      };
+    }
+    if (!schema.fields?.updated_at) {
+      additions.updated_at = {
+        type: "datetime",
+        label: "Last Modified At",
+        required: false,
+        readonly: true,
+        system: true,
+        description: "Timestamp of the most recent modification (auto-populated by the driver)."
+      };
+    }
+    if (!schema.fields?.updated_by) {
+      additions.updated_by = {
+        type: "lookup",
+        reference: "sys_user",
+        label: "Last Modified By",
+        required: false,
+        readonly: true,
+        system: true,
+        description: "User who last modified the record (populated when an authenticated session is present)."
+      };
+    }
+  }
+  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);
   }
@@ -95,7 +198,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) {
@@ -108,7 +211,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);
@@ -121,7 +224,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;
@@ -129,7 +232,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) : [];
   }
@@ -147,7 +250,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) {
@@ -194,7 +298,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);
@@ -216,38 +320,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) {
@@ -266,13 +374,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");
   }
@@ -281,7 +389,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) {
@@ -313,7 +421,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());
     }
@@ -329,7 +437,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}`);
@@ -337,7 +445,7 @@ var SchemaRegistry = class {
   /**
    * Validate Metadata against Spec Zod Schemas
    */
-  static validate(type, item) {
+  validate(type, item) {
     if (type === "object") {
       return import_data.ObjectSchema.parse(item);
     }
@@ -355,7 +463,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}`);
@@ -378,7 +486,7 @@ var SchemaRegistry = class {
   /**
    * Universal Get Method
    */
-  static getItem(type, name) {
+  getItem(type, name) {
     if (type === "object" || type === "objects") {
       return this.getObject(name);
     }
@@ -394,7 +502,7 @@ var SchemaRegistry = class {
   /**
    * Universal List Method
    */
-  static listItems(type, packageId) {
+  listItems(type, packageId) {
     if (type === "object" || type === "objects") {
       return this.getAllObjects(packageId);
     }
@@ -407,7 +515,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");
@@ -417,7 +525,7 @@ var SchemaRegistry = class {
   // ==========================================
   // Package Management
   // ==========================================
-  static installPackage(manifest, settings) {
+  installPackage(manifest, settings) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const pkg = {
       manifest,
@@ -441,7 +549,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}`);
@@ -459,13 +567,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;
@@ -476,7 +584,7 @@ var SchemaRegistry = class {
     }
     return pkg;
   }
-  static disablePackage(id) {
+  disablePackage(id) {
     const pkg = this.getPackage(id);
     if (pkg) {
       pkg.enabled = false;
@@ -490,31 +598,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");
   }
   // ==========================================
@@ -523,7 +631,7 @@ var SchemaRegistry = class {
   /**
    * Clear all registry state. Use only for testing.
    */
-  static reset() {
+  reset() {
     this.objectContributors.clear();
     this.mergedObjectCache.clear();
     this.namespaceRegistry.clear();
@@ -531,29 +639,26 @@ 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
 var import_data2 = require("@objectstack/spec/data");
 var import_shared = require("@objectstack/spec/shared");
+var import_ui2 = require("@objectstack/spec/ui");
+var import_kernel2 = require("@objectstack/spec/kernel");
+var FORM_VIEW_TYPES = /* @__PURE__ */ new Set(["simple", "tabbed", "wizard", "split", "drawer", "modal"]);
+function resolveOverlaySchema(type, item) {
+  const singular = import_shared.PLURAL_TO_SINGULAR[type] ?? type;
+  switch (singular) {
+    case "view": {
+      const t = item && typeof item === "object" && "type" in item ? String(item.type) : void 0;
+      return t && FORM_VIEW_TYPES.has(t) ? import_ui2.FormViewSchema : import_ui2.ListViewSchema;
+    }
+    case "dashboard":
+      return import_ui2.DashboardSchema;
+    default:
+      return null;
+  }
+}
 function simpleHash(str) {
   let hash = 0;
   for (let i = 0; i < str.length; i++) {
@@ -580,11 +685,75 @@ var SERVICE_CONFIG = {
   "file-storage": { route: "/api/v1/storage", plugin: "plugin-storage" },
   search: { route: "/api/v1/search", plugin: "plugin-search" }
 };
-var ObjectStackProtocolImplementation = class {
-  constructor(engine, getServicesRegistry, getFeedService) {
+var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementation {
+  constructor(engine, getServicesRegistry, getFeedService, projectId) {
+    /**
+     * One-time guard for ensuring the overlay-uniqueness UNIQUE INDEX exists
+     * on `sys_metadata`. ADR-0005: scopes overlays by
+     * `(type, name, organization_id, project_id, scope)` for active rows only.
+     * Idempotent SQL — safe to attempt on every protocol instance.
+     *
+     * Inlined here (rather than importing from @objectstack/metadata/migrations)
+     * to avoid a circular dependency: metadata already depends on objectql.
+     */
+    this.overlayIndexEnsured = false;
     this.engine = engine;
     this.getServicesRegistry = getServicesRegistry;
     this.getFeedService = getFeedService;
+    this.projectId = projectId;
+  }
+  async ensureOverlayIndex() {
+    if (this.overlayIndexEnsured) return;
+    this.overlayIndexEnsured = true;
+    try {
+      const engineAny = this.engine;
+      let driver = engineAny?.driver ?? engineAny?.getDriver?.();
+      if (!driver && engineAny?.drivers instanceof Map) {
+        for (const candidate of engineAny.drivers.values()) {
+          if (candidate && (typeof candidate.raw === "function" || typeof candidate.execute === "function")) {
+            driver = candidate;
+            break;
+          }
+        }
+      }
+      if (!driver) return;
+      const exec = async (sql) => {
+        if (typeof driver.raw === "function") {
+          await driver.raw(sql);
+        } else if (typeof driver.execute === "function") {
+          await driver.execute(sql);
+        } else {
+          throw new Error("driver has neither raw nor execute");
+        }
+      };
+      try {
+        await exec("DROP INDEX IF EXISTS idx_sys_metadata_overlay_active");
+      } catch {
+      }
+      const partialSql = "CREATE UNIQUE INDEX IF NOT EXISTS idx_sys_metadata_overlay_active ON sys_metadata (type, name, organization_id) WHERE state = 'active'";
+      const fallbackSql = "CREATE INDEX IF NOT EXISTS idx_sys_metadata_overlay_active ON sys_metadata (type, name, organization_id)";
+      try {
+        await exec(partialSql);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (/partial|where clause|syntax/i.test(msg)) {
+          try {
+            await exec(fallbackSql);
+          } catch {
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  /**
+   * 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?.();
@@ -681,7 +850,7 @@ var ObjectStackProtocolImplementation = class {
     };
   }
   async getMetaTypes() {
-    const schemaTypes = SchemaRegistry.getRegisteredTypes();
+    const schemaTypes = this.engine.registry.getRegisteredTypes();
     let runtimeTypes = [];
     try {
       const services = this.getServicesRegistry?.();
@@ -696,41 +865,66 @@ var ObjectStackProtocolImplementation = class {
   }
   async getMetaItems(request) {
     const { packageId } = request;
-    let items = SchemaRegistry.listItems(request.type, packageId);
-    if (items.length === 0) {
-      const alt = import_shared.PLURAL_TO_SINGULAR[request.type] ?? import_shared.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 = import_shared.PLURAL_TO_SINGULAR[request.type] ?? import_shared.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 = import_shared.PLURAL_TO_SINGULAR[request.type] ?? import_shared.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" };
+    try {
+      const orgId = request.organizationId;
+      const queryByOrg = async (oid) => {
+        const whereClause = {
+          type: request.type,
+          state: "active",
+          organization_id: oid
+        };
         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 {
+        let rs = await this.engine.find("sys_metadata", { where: whereClause });
+        if (!rs || rs.length === 0) {
           const alt = import_shared.PLURAL_TO_SINGULAR[request.type] ?? import_shared.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;
-              });
-            }
+            const altWhere = { type: alt, state: "active", organization_id: oid };
+            if (packageId) altWhere._packageId = packageId;
+            rs = await this.engine.find("sys_metadata", { where: altWhere });
           }
         }
-      } catch {
+        return rs ?? [];
+      };
+      const envWideRecords = await queryByOrg(null);
+      const orgRecords = orgId ? await queryByOrg(orgId) : [];
+      const mergedMap = /* @__PURE__ */ new Map();
+      for (const r of envWideRecords) mergedMap.set(r.name, r);
+      for (const r of orgRecords) mergedMap.set(r.name, r);
+      const records = Array.from(mergedMap.values());
+      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);
+          }
+        }
+        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?.();
@@ -751,7 +945,9 @@ var ObjectStackProtocolImplementation = class {
           for (const item of runtimeItems) {
             const entry = item;
             if (entry && typeof entry === "object" && "name" in entry) {
-              itemMap.set(entry.name, entry);
+              if (!itemMap.has(entry.name)) {
+                itemMap.set(entry.name, entry);
+              }
             }
           }
           items = Array.from(itemMap.values());
@@ -765,32 +961,41 @@ var ObjectStackProtocolImplementation = class {
     };
   }
   async getMetaItem(request) {
-    let item = SchemaRegistry.getItem(request.type, request.name);
-    if (item === void 0) {
-      const alt = import_shared.PLURAL_TO_SINGULAR[request.type] ?? import_shared.SINGULAR_TO_PLURAL[request.type];
-      if (alt) item = SchemaRegistry.getItem(alt, request.name);
+    let item;
+    const orgId = request.organizationId;
+    try {
+      const findOverlay = async (oid) => {
+        const where = {
+          type: request.type,
+          name: request.name,
+          state: "active",
+          organization_id: oid
+        };
+        const rec = await this.engine.findOne("sys_metadata", { where });
+        if (rec) return rec;
+        const alt = import_shared.PLURAL_TO_SINGULAR[request.type] ?? import_shared.SINGULAR_TO_PLURAL[request.type];
+        if (alt) {
+          const altWhere = {
+            type: alt,
+            name: request.name,
+            state: "active",
+            organization_id: oid
+          };
+          return await this.engine.findOne("sys_metadata", { where: altWhere });
+        }
+        return void 0;
+      };
+      const record = (orgId ? await findOverlay(orgId) : void 0) ?? await findOverlay(null);
+      if (record) {
+        item = typeof record.metadata === "string" ? JSON.parse(record.metadata) : record.metadata;
+      }
+    } catch {
     }
     if (item === void 0) {
-      try {
-        const record = await this.engine.findOne("sys_metadata", {
-          where: { type: request.type, name: request.name, state: "active" }
-        });
-        if (record) {
-          item = typeof record.metadata === "string" ? JSON.parse(record.metadata) : record.metadata;
-          SchemaRegistry.registerItem(request.type, item, "name");
-        } else {
-          const alt = import_shared.PLURAL_TO_SINGULAR[request.type] ?? import_shared.SINGULAR_TO_PLURAL[request.type];
-          if (alt) {
-            const altRecord = await this.engine.findOne("sys_metadata", {
-              where: { type: alt, name: request.name, state: "active" }
-            });
-            if (altRecord) {
-              item = typeof altRecord.metadata === "string" ? JSON.parse(altRecord.metadata) : altRecord.metadata;
-              SchemaRegistry.registerItem(request.type, item, "name");
-            }
-          }
-        }
-      } catch {
+      item = this.engine.registry.getItem(request.type, request.name);
+      if (item === void 0) {
+        const alt = import_shared.PLURAL_TO_SINGULAR[request.type] ?? import_shared.SINGULAR_TO_PLURAL[request.type];
+        if (alt) item = this.engine.registry.getItem(alt, request.name);
       }
     }
     if (item === void 0) {
@@ -810,7 +1015,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);
@@ -866,6 +1071,21 @@ var ObjectStackProtocolImplementation = class {
   }
   async findData(request) {
     const options = { ...request.query };
+    if (request.context !== void 0) {
+      options.context = request.context;
+    }
+    for (const [dollar, bare] of [
+      ["$top", "top"],
+      ["$skip", "skip"],
+      ["$orderby", "orderBy"],
+      ["$select", "select"],
+      ["$count", "count"]
+    ]) {
+      if (options[dollar] != null && options[bare] == null) {
+        options[bare] = options[dollar];
+      }
+      delete options[dollar];
+    }
     if (options.top != null) {
       options.limit = Number(options.top);
       delete options.top;
@@ -972,6 +1192,23 @@ var ObjectStackProtocolImplementation = class {
         options.where = implicitFilters;
       }
     }
+    const hasGroupBy = Array.isArray(options.groupBy) && options.groupBy.length > 0;
+    const hasAggregations = Array.isArray(options.aggregations) && options.aggregations.length > 0;
+    if (hasGroupBy || hasAggregations) {
+      const records2 = await this.engine.aggregate(request.object, {
+        where: options.where,
+        groupBy: options.groupBy,
+        aggregations: options.aggregations,
+        context: options.context
+      });
+      const limited = typeof options.limit === "number" && options.limit > 0 ? records2.slice(0, options.limit) : records2;
+      return {
+        object: request.object,
+        records: limited,
+        total: limited.length,
+        hasMore: false
+      };
+    }
     const records = await this.engine.find(request.object, options);
     return {
       object: request.object,
@@ -984,6 +1221,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;
     }
@@ -1002,10 +1242,18 @@ var ObjectStackProtocolImplementation = class {
         record: result
       };
     }
-    throw new Error(`Record ${request.id} not found in ${request.object}`);
+    const err = new Error(`Record ${request.id} not found in ${request.object}`);
+    err.code = "RECORD_NOT_FOUND";
+    err.status = 404;
+    err.object = request.object;
+    throw err;
   }
   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,
@@ -1013,7 +1261,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,
@@ -1021,7 +1271,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,
@@ -1029,25 +1281,281 @@ var ObjectStackProtocolImplementation = class {
     };
   }
   // ==========================================
-  // Metadata Caching
+  // Global Search (M10.5)
   // ==========================================
-  async getMetaItemCached(request) {
-    try {
-      let item = SchemaRegistry.getItem(request.type, request.name);
-      if (!item) {
-        const alt = import_shared.PLURAL_TO_SINGULAR[request.type] ?? import_shared.SINGULAR_TO_PLURAL[request.type];
-        if (alt) item = SchemaRegistry.getItem(alt, request.name);
+  /**
+   * Cross-object substring search across all registered objects that opt in
+   * via `enable.searchable !== false` and `enable.apiEnabled !== false`.
+   * Searches text-like fields (text/textarea/email/url/phone/markdown/html/string)
+   * whose `searchable: true` flag is set, falling back to the object's
+   * `displayNameField` (or `name`) when no fields are explicitly searchable.
+   *
+   * The query is split into whitespace-separated terms; each term must match
+   * (case-insensitive LIKE) at least one searchable field. RBAC/RLS is
+   * enforced by forwarding the caller's `context` to `engine.find` so users
+   * only see records they are entitled to read.
+   */
+  async searchAll(request) {
+    const q = (request.q ?? "").trim();
+    if (!q) {
+      return { query: "", hits: [], totalObjects: 0, totalHits: 0, truncated: false };
+    }
+    const overallLimit = Math.max(1, Math.min(100, Number(request.limit ?? 20)));
+    const perObject = Math.max(1, Math.min(25, Number(request.perObject ?? 5)));
+    const objectsFilter = request.objects && request.objects.length ? new Set(request.objects) : null;
+    const terms = q.split(/\s+/).filter(Boolean).slice(0, 8);
+    const allObjects = this.engine.registry?.getAllObjects?.() ?? [];
+    const hits = [];
+    let objectsScanned = 0;
+    for (const obj of allObjects) {
+      if (hits.length >= overallLimit) break;
+      if (!obj?.name) continue;
+      if (objectsFilter && !objectsFilter.has(obj.name)) continue;
+      const enable = obj.enable ?? {};
+      if (enable.searchable === false) continue;
+      if (enable.apiEnabled === false) continue;
+      if (obj.name.startsWith("sys_audit_log") || obj.name.startsWith("sys_activity") || obj.name.startsWith("sys_session") || obj.name.startsWith("sys_presence") || obj.name.startsWith("sys_metadata") || obj.name.startsWith("sys_account")) {
+        continue;
       }
-      if (!item) {
-        try {
-          const services = this.getServicesRegistry?.();
-          const metadataService = services?.get("metadata");
-          if (metadataService && typeof metadataService.get === "function") {
-            item = await metadataService.get(request.type, request.name);
+      const fieldsRaw = obj.fields;
+      const fields = Array.isArray(fieldsRaw) ? fieldsRaw : fieldsRaw && typeof fieldsRaw === "object" ? Object.entries(fieldsRaw).map(([name, f]) => ({ name, ...f || {} })) : [];
+      const TEXT_TYPES = /* @__PURE__ */ new Set(["text", "textarea", "string", "email", "url", "phone", "markdown", "html"]);
+      const fieldByName = new Map(fields.map((f) => [f.name, f]));
+      const hasField = (n) => fieldByName.has(n);
+      const titleFormatSource = obj.titleFormat && (obj.titleFormat.source || obj.titleFormat) || void 0;
+      const renderTitle = (row) => {
+        if (typeof titleFormatSource === "string") {
+          let allResolved = true;
+          const rendered = titleFormatSource.replace(/\{\{?\s*([a-zA-Z0-9_.]+)\s*\}?\}/g, (_m, key) => {
+            const v = row[key];
+            if (v == null || v === "") {
+              allResolved = false;
+              return "";
+            }
+            return String(v);
+          }).trim();
+          if (rendered && allResolved) return rendered;
+          if (rendered) return rendered.replace(/\s+-\s+$/, "").replace(/^\s+-\s+/, "").trim() || row.id;
+        }
+        const candidates = [
+          obj.displayNameField,
+          "name",
+          "full_name",
+          "title",
+          "subject",
+          "label",
+          "company"
+        ].filter((c) => typeof c === "string" && hasField(c));
+        for (const c of candidates) {
+          const v = row[c];
+          if (v != null && String(v).trim()) return String(v);
+        }
+        const fn = row.first_name, ln = row.last_name;
+        if (fn || ln) return `${fn ?? ""} ${ln ?? ""}`.trim();
+        return String(row.id);
+      };
+      const titleFieldName = obj.displayNameField || (hasField("name") ? "name" : void 0) || (hasField("title") ? "title" : void 0) || fields.find((f) => TEXT_TYPES.has(f.type))?.name;
+      let searchableFields = fields.filter((f) => f && TEXT_TYPES.has(f.type) && f.searchable === true).map((f) => f.name);
+      if (searchableFields.length === 0 && titleFieldName) {
+        searchableFields = [titleFieldName];
+      }
+      if (searchableFields.length === 0) continue;
+      objectsScanned++;
+      const andClauses = terms.map((term) => ({
+        $or: searchableFields.map((f) => ({ [f]: { $contains: term } }))
+      }));
+      const where = andClauses.length === 1 ? andClauses[0] : { $and: andClauses };
+      try {
+        const opts = {
+          where,
+          limit: perObject,
+          orderBy: [{ field: "updated_at", direction: "desc" }]
+        };
+        if (request.context !== void 0) opts.context = request.context;
+        const rows = await this.engine.find(obj.name, opts);
+        for (const row of rows || []) {
+          if (hits.length >= overallLimit) break;
+          const title = renderTitle(row);
+          let snippet;
+          for (const f of searchableFields) {
+            const v = row[f];
+            if (typeof v === "string" && v) {
+              const lc = v.toLowerCase();
+              const idx = terms.map((t) => lc.indexOf(t.toLowerCase())).find((i) => i >= 0);
+              if (idx != null && idx >= 0) {
+                const start = Math.max(0, idx - 30);
+                const end = Math.min(v.length, idx + 90);
+                snippet = (start > 0 ? "\u2026" : "") + v.slice(start, end) + (end < v.length ? "\u2026" : "");
+                break;
+              }
+            }
           }
-        } catch {
+          hits.push({
+            object: obj.name,
+            id: row.id,
+            title,
+            snippet,
+            record: row
+          });
         }
+      } catch {
+        continue;
       }
+    }
+    return {
+      query: q,
+      hits,
+      totalObjects: objectsScanned,
+      totalHits: hits.length,
+      truncated: hits.length >= overallLimit
+    };
+  }
+  // ==========================================
+  // Lead Convert (M10.6)
+  // ==========================================
+  /**
+   * Convert a qualified Lead into an Account + Contact (+ optional
+   * Opportunity) and mark the Lead as converted. Mirrors the Salesforce
+   * lead-conversion model:
+   *
+   *   - If `accountId` is provided, the lead's company info is NOT used
+   *     to create a new account; the new contact and opportunity link to
+   *     the existing account instead.
+   *   - If `contactId` is provided, no new contact is created either —
+   *     useful when the lead is a new contact at an existing account.
+   *   - `createOpportunity` defaults to true; pass `false` to convert
+   *     without producing an opportunity (some teams convert "logos
+   *     only" first).
+   *   - Lead is updated atomically: `is_converted=true`,
+   *     `converted_account`/`converted_contact`/`converted_opportunity`
+   *     pointers, `converted_date`, and `status='converted'`.
+   *
+   * Atomicity is enforced via the default driver's transaction support
+   * when available; otherwise a best-effort compensation (delete
+   * already-created child records on failure) is attempted. Permission
+   * checks on each child object are inherited from the caller's
+   * execution context so SecurityPlugin still gates account/contact/
+   * opportunity creates.
+   */
+  async convertLead(request) {
+    const leadId = String(request.leadId || "").trim();
+    if (!leadId) {
+      const err = new Error("leadId is required");
+      err.status = 400;
+      err.code = "INVALID_REQUEST";
+      throw err;
+    }
+    const ctx = request.context;
+    const ctxOpt = ctx !== void 0 ? { context: ctx } : void 0;
+    const lead = await this.engine.findOne("lead", { where: { id: leadId }, ...ctxOpt });
+    if (!lead) {
+      const err = new Error(`Lead '${leadId}' not found`);
+      err.status = 404;
+      err.code = "LEAD_NOT_FOUND";
+      throw err;
+    }
+    if (lead.is_converted) {
+      const err = new Error(`Lead '${leadId}' is already converted`);
+      err.status = 409;
+      err.code = "LEAD_ALREADY_CONVERTED";
+      throw err;
+    }
+    const runConversion = async (trxCtx) => {
+      const opCtx = trxCtx ?? ctx;
+      const trxCtxOpt = opCtx !== void 0 ? { context: opCtx } : void 0;
+      let account;
+      if (request.accountId) {
+        account = await this.engine.findOne("account", { where: { id: request.accountId }, ...trxCtxOpt });
+        if (!account) {
+          const err = new Error(`Account '${request.accountId}' not found`);
+          err.status = 404;
+          err.code = "ACCOUNT_NOT_FOUND";
+          throw err;
+        }
+      } else {
+        const accountPayload = {
+          name: lead.company || `${lead.first_name ?? ""} ${lead.last_name ?? ""}`.trim() || "Untitled Account"
+        };
+        if (lead.industry) accountPayload.industry = lead.industry;
+        if (lead.annual_revenue) accountPayload.annual_revenue = lead.annual_revenue;
+        if (lead.number_of_employees) accountPayload.employees = lead.number_of_employees;
+        if (lead.website) accountPayload.website = lead.website;
+        if (lead.phone) accountPayload.phone = lead.phone;
+        if (lead.address) accountPayload.billing_address = lead.address;
+        if (lead.owner) accountPayload.owner = lead.owner;
+        account = await this.engine.insert("account", accountPayload, trxCtxOpt);
+      }
+      let contact;
+      if (request.contactId) {
+        contact = await this.engine.findOne("contact", { where: { id: request.contactId }, ...trxCtxOpt });
+        if (!contact) {
+          const err = new Error(`Contact '${request.contactId}' not found`);
+          err.status = 404;
+          err.code = "CONTACT_NOT_FOUND";
+          throw err;
+        }
+      } else {
+        const contactPayload = {
+          first_name: lead.first_name ?? "",
+          last_name: lead.last_name ?? lead.company ?? "Unknown"
+        };
+        if (lead.salutation) contactPayload.salutation = lead.salutation;
+        if (lead.email) contactPayload.email = lead.email;
+        if (lead.phone) contactPayload.phone = lead.phone;
+        if (lead.mobile) contactPayload.mobile = lead.mobile;
+        if (lead.title) contactPayload.title = lead.title;
+        if (lead.address) contactPayload.mailing_address = lead.address;
+        if (lead.owner) contactPayload.owner = lead.owner;
+        if (account?.id) contactPayload.account = account.id;
+        contact = await this.engine.insert("contact", contactPayload, trxCtxOpt);
+      }
+      let opportunity = null;
+      const shouldCreateOpp = request.createOpportunity !== false;
+      if (shouldCreateOpp) {
+        const oppOverrides = request.opportunity ?? {};
+        const defaultName = oppOverrides.name || `${account?.name ?? lead.company ?? "Lead"} - New Opportunity`;
+        const defaultClose = oppOverrides.close_date || new Date(Date.now() + 30 * 24 * 60 * 60 * 1e3).toISOString().slice(0, 10);
+        const oppPayload = {
+          name: defaultName,
+          stage: oppOverrides.stage ?? "qualification",
+          close_date: defaultClose
+        };
+        if (oppOverrides.amount !== void 0) oppPayload.amount = oppOverrides.amount;
+        else if (lead.annual_revenue) oppPayload.amount = lead.annual_revenue;
+        if (account?.id) oppPayload.account = account.id;
+        if (contact?.id) oppPayload.primary_contact = contact.id;
+        if (lead.owner) oppPayload.owner = lead.owner;
+        if (lead.lead_source) oppPayload.lead_source = lead.lead_source;
+        opportunity = await this.engine.insert("opportunity", oppPayload, trxCtxOpt);
+      }
+      const leadUpdate = {
+        is_converted: true,
+        status: request.convertedStatus ?? "converted",
+        converted_account: account?.id ?? null,
+        converted_contact: contact?.id ?? null,
+        converted_opportunity: opportunity?.id ?? null,
+        converted_date: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      const updatedLead = await this.engine.update("lead", leadUpdate, {
+        where: { id: leadId },
+        ...trxCtxOpt
+      });
+      return {
+        lead: updatedLead ?? { ...lead, ...leadUpdate },
+        account,
+        contact,
+        opportunity
+      };
+    };
+    return this.engine.transaction(runConversion, ctx);
+  }
+  // ==========================================
+  // Metadata Caching
+  // ==========================================
+  async getMetaItemCached(request) {
+    try {
+      const result = await this.getMetaItem({ type: request.type, name: request.name });
+      const item = result?.item;
       if (!item) {
         throw new Error(`Metadata item ${request.type}/${request.name} not found`);
       }
@@ -1239,7 +1747,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) {
@@ -1339,71 +1847,192 @@ var ObjectStackProtocolImplementation = class {
       ...request.options
     });
   }
+  /** Normalize plural→singular before consulting the allow-list. */
+  static isOverlayAllowed(type) {
+    const singular = import_shared.PLURAL_TO_SINGULAR[type] ?? type;
+    return _ObjectStackProtocolImplementation.OVERLAY_ALLOWED_TYPES.has(singular) || _ObjectStackProtocolImplementation.OVERLAY_ALLOWED_TYPES.has(type);
+  }
   async saveMetaItem(request) {
     if (!request.item) {
       throw new Error("Item data is required");
     }
-    SchemaRegistry.registerItem(request.type, request.item, "name");
+    if (this.projectId !== void 0 && !_ObjectStackProtocolImplementation.isOverlayAllowed(request.type)) {
+      const allowed = Array.from(_ObjectStackProtocolImplementation.OVERLAY_ALLOWED_TYPES).join(", ");
+      const err = new Error(
+        `[not_overridable] Metadata type '${request.type}' has not opted into per-org overlay writes. Set allowOrgOverride: true on its DEFAULT_METADATA_TYPE_REGISTRY entry to enable. Currently allowed: ${allowed}. See docs/adr/0005-metadata-customization-overlay.md.`
+      );
+      err.code = "not_overridable";
+      err.status = 403;
+      throw err;
+    }
+    {
+      const schema = resolveOverlaySchema(request.type, request.item);
+      if (schema) {
+        const parsed = schema.safeParse(request.item);
+        if (!parsed.success) {
+          const issues = parsed.error.issues.map((i) => ({
+            path: i.path.join("."),
+            message: i.message,
+            code: i.code
+          }));
+          const summary = issues.slice(0, 3).map((i) => `${i.path || "<root>"}: ${i.message}`).join("; ");
+          const err = new Error(
+            `[invalid_metadata] ${request.type}/${request.name} failed spec validation: ${summary}` + (issues.length > 3 ? ` (+${issues.length - 3} more)` : "")
+          );
+          err.code = "invalid_metadata";
+          err.status = 422;
+          err.issues = issues;
+          throw err;
+        }
+      }
+    }
+    if (request.type === "object" || request.type === "objects") {
+      this.engine.registry.registerItem(request.type, request.item, "name");
+      try {
+        this.engine.registry.registerObject(request.item, "sys_metadata");
+      } catch (err) {
+        console.warn(
+          `[Protocol] registerObject failed for ${request.name}: ${err?.message ?? err}`
+        );
+      }
+    }
+    await this.ensureOverlayIndex();
     try {
       const now = (/* @__PURE__ */ new Date()).toISOString();
+      const orgId = request.organizationId ?? null;
+      const scopedWhere = {
+        type: request.type,
+        name: request.name,
+        organization_id: orgId,
+        state: "active"
+      };
       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", {
           metadata: JSON.stringify(request.item),
           updated_at: now,
-          version: (existing.version || 0) + 1
+          version: (existing.version || 0) + 1,
+          state: "active"
         }, {
           where: { id: existing.id }
         });
       } 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` enum is ['system','platform','user']; per-org
+          // overlays use 'platform' as the informational tag. The
+          // authoritative isolation key is `organization_id`.
           scope: "platform",
           metadata: JSON.stringify(request.item),
           state: "active",
           version: 1,
           created_at: now,
-          updated_at: now
-        });
+          updated_at: now,
+          organization_id: orgId
+        };
+        await this.engine.insert("sys_metadata", row);
       }
       return {
         success: true,
-        message: "Saved to database and registry"
+        message: orgId ? `Saved customization overlay (org=${orgId}) \u2014 type=${request.type}, name=${request.name}` : `Saved customization overlay (env-wide) \u2014 type=${request.type}, name=${request.name}`
       };
     } catch (dbError) {
-      console.warn(`[Protocol] DB persistence failed for ${request.type}/${request.name}: ${dbError.message}`);
+      console.error(
+        `[Protocol] sys_metadata persistence failed for ${request.type}/${request.name}: ${dbError.message}`
+      );
+      const err = new Error(
+        `Failed to persist customization overlay to sys_metadata: ${dbError.message}. In-memory registry was updated but will be lost on restart.`
+      );
+      err.code = "overlay_persistence_failed";
+      err.status = 500;
+      throw err;
+    }
+  }
+  /**
+   * Remove a customization overlay row for the given metadata item, so the
+   * next read falls through to the artifact-loaded default. Implements the
+   * "Reset to factory default" semantic from ADR-0005. Whitelist is shared
+   * with {@link saveMetaItem}.
+   */
+  async deleteMetaItem(request) {
+    if (this.projectId !== void 0 && !_ObjectStackProtocolImplementation.isOverlayAllowed(request.type)) {
+      const err = new Error(
+        `[not_overridable] Metadata type '${request.type}' has not opted into per-org overlay writes. See docs/adr/0005-metadata-customization-overlay.md.`
+      );
+      err.code = "not_overridable";
+      err.status = 403;
+      throw err;
+    }
+    const scopedWhere = {
+      type: request.type,
+      name: request.name,
+      organization_id: request.organizationId ?? null
+    };
+    try {
+      const existing = await this.engine.findOne("sys_metadata", { where: scopedWhere });
+      if (!existing) {
+        return {
+          success: true,
+          reset: false,
+          message: `No customization overlay found for ${request.type}/${request.name} \u2014 already at artifact default.`
+        };
+      }
+      await this.engine.delete("sys_metadata", { where: { id: existing.id } });
+      if (this.projectId === void 0) {
+        try {
+          const services = this.getServicesRegistry?.();
+          const metadataService = services?.get("metadata");
+          if (metadataService && typeof metadataService.get === "function") {
+            const artifactItem = await metadataService.get(request.type, request.name);
+            if (artifactItem !== void 0) {
+              this.engine.registry.registerItem(request.type, artifactItem, "name");
+            }
+          }
+        } catch {
+        }
+      }
       return {
         success: true,
-        message: "Saved to memory registry (DB persistence unavailable)",
-        warning: dbError.message
+        reset: true,
+        message: `Customization overlay deleted \u2014 ${request.type}/${request.name} reset to artifact default.`
       };
+    } catch (err) {
+      const e = new Error(`Failed to delete customization overlay: ${err.message}`);
+      e.status = 500;
+      throw e;
     }
   }
   /**
    * Hydrate SchemaRegistry from the database on startup.
    * Loads all active metadata records and registers them in the in-memory registry.
    * Safe to call repeatedly — idempotent (latest DB record wins).
+   *
+   * Per ADR-0005, project-kernel mode ALSO hydrates from sys_metadata —
+   * customization overlay rows must survive restart. Scope filter
+   * (`project_id = this.projectId ?? null`) keeps tenants isolated.
    */
   async loadMetaFromDb() {
     let loaded = 0;
     let errors = 0;
     try {
-      const records = await this.engine.find("sys_metadata", {
-        where: { state: "active" }
-      });
+      const where = {
+        state: "active",
+        organization_id: 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 = import_shared.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) {
@@ -1412,7 +2041,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 };
   }
@@ -1482,78 +2113,846 @@ var ObjectStackProtocolImplementation = class {
     await svc.updateFeedItem(request.feedId, { visibility: item.visibility });
     return { success: true, data: { feedId: request.feedId, pinned: false } };
   }
-  async starFeedItem(request) {
-    const svc = this.requireFeedService();
-    const item = await svc.getFeedItem(request.feedId);
-    if (!item) throw new Error(`Feed item ${request.feedId} not found`);
-    await svc.updateFeedItem(request.feedId, { visibility: item.visibility });
-    return { success: true, data: { feedId: request.feedId, starred: true, starredAt: (/* @__PURE__ */ new Date()).toISOString() } };
+  async starFeedItem(request) {
+    const svc = this.requireFeedService();
+    const item = await svc.getFeedItem(request.feedId);
+    if (!item) throw new Error(`Feed item ${request.feedId} not found`);
+    await svc.updateFeedItem(request.feedId, { visibility: item.visibility });
+    return { success: true, data: { feedId: request.feedId, starred: true, starredAt: (/* @__PURE__ */ new Date()).toISOString() } };
+  }
+  async unstarFeedItem(request) {
+    const svc = this.requireFeedService();
+    const item = await svc.getFeedItem(request.feedId);
+    if (!item) throw new Error(`Feed item ${request.feedId} not found`);
+    await svc.updateFeedItem(request.feedId, { visibility: item.visibility });
+    return { success: true, data: { feedId: request.feedId, starred: false } };
+  }
+  async searchFeed(request) {
+    const svc = this.requireFeedService();
+    const result = await svc.listFeed({
+      object: request.object,
+      recordId: request.recordId,
+      filter: request.type,
+      limit: request.limit,
+      cursor: request.cursor
+    });
+    const queryLower = (request.query || "").toLowerCase();
+    const filtered = result.items.filter(
+      (item) => item.body?.toLowerCase().includes(queryLower)
+    );
+    return { success: true, data: { items: filtered, total: filtered.length, hasMore: false } };
+  }
+  async getChangelog(request) {
+    const svc = this.requireFeedService();
+    const result = await svc.listFeed({
+      object: request.object,
+      recordId: request.recordId,
+      filter: "changes_only",
+      limit: request.limit,
+      cursor: request.cursor
+    });
+    const entries = result.items.map((item) => ({
+      id: item.id,
+      object: item.object,
+      recordId: item.recordId,
+      actor: item.actor,
+      changes: item.changes || [],
+      timestamp: item.createdAt,
+      source: item.source
+    }));
+    return { success: true, data: { entries, total: result.total, nextCursor: result.nextCursor, hasMore: result.hasMore } };
+  }
+  async feedSubscribe(request) {
+    const svc = this.requireFeedService();
+    const subscription = await svc.subscribe({
+      object: request.object,
+      recordId: request.recordId,
+      userId: "current_user",
+      events: request.events,
+      channels: request.channels
+    });
+    return { success: true, data: subscription };
+  }
+  async feedUnsubscribe(request) {
+    const svc = this.requireFeedService();
+    const unsubscribed = await svc.unsubscribe(request.object, request.recordId, "current_user");
+    return { success: true, data: { object: request.object, recordId: request.recordId, unsubscribed } };
+  }
+};
+/**
+ * Metadata types that are customer-overridable via {@link saveMetaItem}/
+ * {@link deleteMetaItem} in project-kernel mode. Derived from the canonical
+ * registry in {@link DEFAULT_METADATA_TYPE_REGISTRY}: a type opts in by
+ * setting `allowOrgOverride: true` on its registry entry. The set is
+ * augmented with the plural form of every singular so callers using REST
+ * conventions (`/api/v1/meta/views/...`) get the same gate. See ADR-0005
+ * §"Whitelist enforcement" for the rationale and the per-type rollout
+ * checklist.
+ */
+_ObjectStackProtocolImplementation.OVERLAY_ALLOWED_TYPES = (() => {
+  const out = /* @__PURE__ */ new Set();
+  for (const entry of import_kernel2.DEFAULT_METADATA_TYPE_REGISTRY) {
+    if (!entry.allowOrgOverride) continue;
+    out.add(entry.type);
+    const plural = import_shared.SINGULAR_TO_PLURAL[entry.type];
+    if (plural) out.add(plural);
+  }
+  return out;
+})();
+var ObjectStackProtocolImplementation = _ObjectStackProtocolImplementation;
+
+// src/engine.ts
+var import_kernel3 = require("@objectstack/spec/kernel");
+var import_core = require("@objectstack/core");
+var import_system = require("@objectstack/spec/system");
+var import_shared2 = require("@objectstack/spec/shared");
+var import_formula2 = require("@objectstack/formula");
+
+// src/hook-wrappers.ts
+var import_formula = require("@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 = import_formula.ExpressionEngine.compile(expr);
+      if (check.ok) {
+        conditionFn = (record) => {
+          const r = import_formula.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/validation/record-validator.ts
+var SKIP_FIELDS = /* @__PURE__ */ new Set([
+  "id",
+  "created_at",
+  "created_by",
+  "updated_at",
+  "updated_by",
+  "organization_id",
+  "tenant_id"
+]);
+var EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+var URL_RE = /^[a-z][a-z0-9+.\-]*:\/\/[^\s]+$/i;
+var PHONE_RE = /^[+()\-\s\d.]{5,}$/;
+var ValidationError = class extends Error {
+  constructor(fields) {
+    super(
+      `Validation failed for ${fields.length} field(s): ` + fields.map((f) => `${f.field} (${f.code})`).join(", ")
+    );
+    this.code = "VALIDATION_FAILED";
+    this.name = "ValidationError";
+    this.fields = fields;
+  }
+};
+function isMissing(v) {
+  return v === void 0 || v === null || typeof v === "string" && v.trim() === "";
+}
+function optionValues(options) {
+  if (!Array.isArray(options)) return [];
+  return options.map(
+    (o) => typeof o === "object" && o !== null ? String(o.value) : String(o)
+  );
+}
+function validateOne(name, def, value) {
+  if (def.required && isMissing(value)) {
+    return { field: name, code: "required", message: `${name} is required` };
+  }
+  if (isMissing(value)) return null;
+  const t = def.type;
+  if (t === "text" || t === "textarea" || t === "email" || t === "url" || t === "phone" || t === "password" || t === "markdown" || t === "html" || t === "richtext" || t === "code") {
+    const s = typeof value === "string" ? value : String(value);
+    if (def.maxLength !== void 0 && s.length > def.maxLength) {
+      return { field: name, code: "max_length", message: `${name} must be \u2264 ${def.maxLength} characters (got ${s.length})` };
+    }
+    if (def.minLength !== void 0 && s.length < def.minLength) {
+      return { field: name, code: "min_length", message: `${name} must be \u2265 ${def.minLength} characters (got ${s.length})` };
+    }
+    if (t === "email" && !EMAIL_RE.test(s)) {
+      return { field: name, code: "invalid_email", message: `${name} must be a valid email address` };
+    }
+    if (t === "url" && !URL_RE.test(s)) {
+      return { field: name, code: "invalid_url", message: `${name} must be a valid URL (scheme://...)` };
+    }
+    if (t === "phone" && !PHONE_RE.test(s)) {
+      return { field: name, code: "invalid_phone", message: `${name} must be a valid phone number` };
+    }
+    return null;
+  }
+  if (t === "number" || t === "currency" || t === "percent" || t === "rating" || t === "slider") {
+    const n = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(n)) {
+      return { field: name, code: "invalid_number", message: `${name} must be a number` };
+    }
+    if (def.min !== void 0 && n < def.min) {
+      return { field: name, code: "min_value", message: `${name} must be \u2265 ${def.min}` };
+    }
+    if (def.max !== void 0 && n > def.max) {
+      return { field: name, code: "max_value", message: `${name} must be \u2264 ${def.max}` };
+    }
+    return null;
+  }
+  if (t === "boolean" || t === "toggle") {
+    if (typeof value === "boolean") return null;
+    if (value === 0 || value === 1 || value === "0" || value === "1" || value === "true" || value === "false") return null;
+    return { field: name, code: "invalid_boolean", message: `${name} must be true or false` };
   }
-  async unstarFeedItem(request) {
-    const svc = this.requireFeedService();
-    const item = await svc.getFeedItem(request.feedId);
-    if (!item) throw new Error(`Feed item ${request.feedId} not found`);
-    await svc.updateFeedItem(request.feedId, { visibility: item.visibility });
-    return { success: true, data: { feedId: request.feedId, starred: false } };
+  if (t === "date" || t === "datetime" || t === "time") {
+    if (value instanceof Date) return null;
+    if (typeof value === "string" && !Number.isNaN(Date.parse(value))) return null;
+    return { field: name, code: "invalid_date", message: `${name} must be a valid ${t} (ISO-8601)` };
   }
-  async searchFeed(request) {
-    const svc = this.requireFeedService();
-    const result = await svc.listFeed({
-      object: request.object,
-      recordId: request.recordId,
-      filter: request.type,
-      limit: request.limit,
-      cursor: request.cursor
-    });
-    const queryLower = (request.query || "").toLowerCase();
-    const filtered = result.items.filter(
-      (item) => item.body?.toLowerCase().includes(queryLower)
-    );
-    return { success: true, data: { items: filtered, total: filtered.length, hasMore: false } };
+  if (t === "select" || t === "radio") {
+    const allowed = optionValues(def.options);
+    if (allowed.length > 0 && !allowed.includes(String(value))) {
+      return { field: name, code: "invalid_option", message: `${name} must be one of: ${allowed.join(", ")}`, options: allowed };
+    }
+    return null;
   }
-  async getChangelog(request) {
-    const svc = this.requireFeedService();
-    const result = await svc.listFeed({
-      object: request.object,
-      recordId: request.recordId,
-      filter: "changes_only",
-      limit: request.limit,
-      cursor: request.cursor
-    });
-    const entries = result.items.map((item) => ({
-      id: item.id,
-      object: item.object,
-      recordId: item.recordId,
-      actor: item.actor,
-      changes: item.changes || [],
-      timestamp: item.createdAt,
-      source: item.source
-    }));
-    return { success: true, data: { entries, total: result.total, nextCursor: result.nextCursor, hasMore: result.hasMore } };
+  if (t === "multiselect" || t === "checkboxes" || t === "tags") {
+    const allowed = optionValues(def.options);
+    if (allowed.length === 0) return null;
+    const arr = Array.isArray(value) ? value : [value];
+    for (const v of arr) {
+      if (!allowed.includes(String(v))) {
+        return { field: name, code: "invalid_option", message: `${name}: "${v}" is not one of: ${allowed.join(", ")}`, options: allowed };
+      }
+    }
+    return null;
   }
-  async feedSubscribe(request) {
-    const svc = this.requireFeedService();
-    const subscription = await svc.subscribe({
-      object: request.object,
-      recordId: request.recordId,
-      userId: "current_user",
-      events: request.events,
-      channels: request.channels
-    });
-    return { success: true, data: subscription };
+  return null;
+}
+function validateRecord(objectSchema, data, mode) {
+  if (!objectSchema?.fields || !data) return;
+  const errors = [];
+  const fields = objectSchema.fields;
+  if (mode === "insert") {
+    for (const [name, def] of Object.entries(fields)) {
+      if (SKIP_FIELDS.has(name)) continue;
+      if (def.system || def.readonly) continue;
+      const err = validateOne(name, def, data[name]);
+      if (err) errors.push(err);
+    }
+  } else {
+    for (const [name, value] of Object.entries(data)) {
+      if (SKIP_FIELDS.has(name)) continue;
+      const def = fields[name];
+      if (!def) continue;
+      if (def.system || def.readonly) continue;
+      const err = validateOne(name, { ...def, required: false }, value);
+      if (err) errors.push(err);
+    }
+  }
+  if (errors.length > 0) throw new ValidationError(errors);
+}
+
+// src/in-memory-aggregation.ts
+function applyInMemoryAggregation(rows, ast) {
+  const groupBy = ast.groupBy ?? [];
+  const aggregations = ast.aggregations ?? [];
+  if (groupBy.length === 0 && aggregations.length === 0) return rows;
+  if (groupBy.length === 0) {
+    return [aggregateBucket(rows, aggregations)];
+  }
+  const buckets = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const key = {};
+    const parts = [];
+    for (const g of groupBy) {
+      const fieldName = typeof g === "string" ? g : g.alias ?? g.field;
+      const value = projectGroupValue(row, g);
+      key[fieldName] = value;
+      parts.push(`${fieldName}=${value}`);
+    }
+    const id = parts.join("
");
+    let bucket = buckets.get(id);
+    if (!bucket) {
+      bucket = { key, rows: [] };
+      buckets.set(id, bucket);
+    }
+    bucket.rows.push(row);
+  }
+  const out = [];
+  for (const { key, rows: bucketRows } of buckets.values()) {
+    const aggValues = aggregateBucket(bucketRows, aggregations);
+    out.push({ ...key, ...aggValues });
+  }
+  return out;
+}
+function projectGroupValue(row, g) {
+  const field = typeof g === "string" ? g : g.field;
+  const v = row?.[field];
+  if (typeof g !== "string" && g.dateGranularity) {
+    return bucketDateValue(v, g.dateGranularity);
   }
-  async feedUnsubscribe(request) {
-    const svc = this.requireFeedService();
-    const unsubscribed = await svc.unsubscribe(request.object, request.recordId, "current_user");
-    return { success: true, data: { object: request.object, recordId: request.recordId, unsubscribed } };
+  return v == null ? "(null)" : String(v);
+}
+function aggregateBucket(rows, aggregations) {
+  const out = {};
+  for (const agg of aggregations) {
+    const alias = agg.alias;
+    const fn = agg.function;
+    if (fn === "count") {
+      if (!agg.field) {
+        out[alias] = rows.length;
+      } else {
+        out[alias] = rows.reduce(
+          (acc, r) => r[agg.field] != null ? acc + 1 : acc,
+          0
+        );
+      }
+      continue;
+    }
+    const field = agg.field;
+    if (!field) {
+      out[alias] = null;
+      continue;
+    }
+    const values = collectValues(rows, field, !!agg.distinct);
+    switch (fn) {
+      case "count_distinct":
+        out[alias] = new Set(values.filter((v) => v != null)).size;
+        break;
+      case "sum":
+        out[alias] = values.reduce((a, b) => a + toNumber(b), 0);
+        break;
+      case "avg": {
+        const nums = values.filter((v) => v != null).map(toNumber);
+        out[alias] = nums.length === 0 ? null : nums.reduce((a, b) => a + b, 0) / nums.length;
+        break;
+      }
+      case "min": {
+        const defined = values.filter((v) => v != null);
+        out[alias] = defined.length === 0 ? null : defined.reduce((a, b) => a < b ? a : b);
+        break;
+      }
+      case "max": {
+        const defined = values.filter((v) => v != null);
+        out[alias] = defined.length === 0 ? null : defined.reduce((a, b) => a > b ? a : b);
+        break;
+      }
+      case "array_agg":
+        out[alias] = values.slice();
+        break;
+      case "string_agg":
+        out[alias] = values.filter((v) => v != null).map(String).join(",");
+        break;
+      default:
+        out[alias] = null;
+    }
   }
-};
+  return out;
+}
+function collectValues(rows, field, distinct) {
+  if (!distinct) return rows.map((r) => r?.[field]);
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const r of rows) {
+    const v = r?.[field];
+    if (seen.has(v)) continue;
+    seen.add(v);
+    out.push(v);
+  }
+  return out;
+}
+function toNumber(v) {
+  if (typeof v === "number") return v;
+  if (v == null) return 0;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : 0;
+}
+function bucketDateValue(value, granularity) {
+  if (value == null) return "(null)";
+  const d = value instanceof Date ? value : new Date(String(value));
+  if (Number.isNaN(d.getTime())) return "(null)";
+  const y = d.getUTCFullYear();
+  const m = d.getUTCMonth() + 1;
+  switch (granularity) {
+    case "year":
+      return String(y);
+    case "quarter":
+      return `${y}-Q${Math.floor((m - 1) / 3) + 1}`;
+    case "month":
+      return `${y}-${String(m).padStart(2, "0")}`;
+    case "day":
+      return `${y}-${String(m).padStart(2, "0")}-${String(d.getUTCDate()).padStart(2, "0")}`;
+    case "week": {
+      const target = new Date(Date.UTC(y, d.getUTCMonth(), d.getUTCDate()));
+      const dayNum = (target.getUTCDay() + 6) % 7;
+      target.setUTCDate(target.getUTCDate() - dayNum + 3);
+      const firstThursday = new Date(Date.UTC(target.getUTCFullYear(), 0, 4));
+      const weekNo = 1 + Math.round(
+        ((target.getTime() - firstThursday.getTime()) / 864e5 - 3 + (firstThursday.getUTCDay() + 6) % 7) / 7
+      );
+      return `${target.getUTCFullYear()}-W${String(weekNo).padStart(2, "0")}`;
+    }
+    default:
+      return String(value);
+  }
+}
 
 // src/engine.ts
-var import_kernel2 = require("@objectstack/spec/kernel");
-var import_core = require("@objectstack/core");
-var import_system = require("@objectstack/spec/system");
-var import_shared2 = require("@objectstack/spec/shared");
+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 });
+      import_formula2.ExpressionEngine.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) {
+      const fdef = schema.fields[fname];
+      if (fdef?.type === "formula") continue;
+      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 = import_formula2.ExpressionEngine.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();
@@ -1577,10 +2976,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 || (0, import_core.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");
   }
   /**
@@ -1596,10 +3014,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
@@ -1645,11 +3066,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) {
@@ -1742,9 +3273,98 @@ var _ObjectQL = class _ObjectQL {
       userId: execCtx.userId,
       tenantId: execCtx.tenantId,
       roles: execCtx.roles,
-      accessToken: execCtx.accessToken
+      accessToken: execCtx.accessToken,
+      // Propagate system-elevated flag so hooks can distinguish engine
+      // self-writes (e.g. approval status mirror) from genuine user writes.
+      ...execCtx.isSystem ? { isSystem: true } : {}
     };
   }
+  /**
+   * Build the DriverOptions blob passed to every IDataDriver call.
+   *
+   * Always carries `tenantId` from the active ExecutionContext so the
+   * driver can enforce per-tenant isolation (SQL driver auto-scopes reads
+   * and auto-injects the tenant column on writes). Existing user-supplied
+   * shapes (transactions, AST extras) are preserved by spreading them
+   * first.
+   *
+   * System / isSystem callers may still cross tenants by clearing
+   * `tenantId` themselves on the resulting object; this helper does not
+   * mask the system path.
+   */
+  buildDriverOptions(execCtx, base) {
+    const hasTx = execCtx?.transaction !== void 0;
+    const hasTenant = execCtx?.tenantId !== void 0;
+    const isSystem = execCtx?.isSystem === true;
+    if (!hasTx && !hasTenant && !isSystem) return base;
+    const opts = base && typeof base === "object" ? { ...base } : {};
+    if (hasTx && opts.transaction === void 0) {
+      opts.transaction = execCtx.transaction;
+    }
+    if (hasTenant && opts.tenantId === void 0) {
+      opts.tenantId = execCtx.tenantId;
+    }
+    if (isSystem && opts.bypassTenantAudit === void 0) {
+      opts.bypassTenantAudit = true;
+    }
+    return opts;
+  }
+  /**
+   * 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 = import_formula2.ExpressionEngine.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)
    * 
@@ -1759,23 +3379,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 });
         }
       }
@@ -1795,7 +3416,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 });
       }
     }
@@ -1804,13 +3425,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 = [
@@ -1849,9 +3472,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((0, import_shared2.pluralToSingular)(key), item, "name", id);
+            const toRegister = item.name === itemName ? item : { ...item, name: itemName };
+            this._registry.registerItem((0, import_shared2.pluralToSingular)(key), toRegister, "name", id);
+          } else {
+            this.logger.warn(`Skipping ${(0, import_shared2.pluralToSingular)(key)} without a derivable name`, { id });
           }
         }
       }
@@ -1861,14 +3487,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 });
       }
     }
@@ -1883,6 +3509,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.)
    *
@@ -1903,7 +3548,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 {
@@ -1911,7 +3556,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 });
           }
         }
@@ -1921,7 +3566,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 });
@@ -1955,9 +3601,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((0, import_shared2.pluralToSingular)(key), item, "name", ownerId);
+            const toRegister = item.name === itemName ? item : { ...item, name: itemName };
+            this._registry.registerItem((0, import_shared2.pluralToSingular)(key), toRegister, "name", ownerId);
           }
         }
       }
@@ -1995,24 +3642,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 import_system.StorageNameMapping.resolveTableName(schema);
     }
-    return name;
+    return import_system.StorageNameMapping.resolveTableName({ name });
   }
   /**
    * Helper to get the target driver
@@ -2024,7 +3668,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);
@@ -2040,7 +3684,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") {
@@ -2158,10 +3802,10 @@ var _ObjectQL = class _ObjectQL {
    * @param depth - Current recursion depth (0-based)
    * @returns Records with expanded lookup fields (IDs replaced by full objects)
    */
-  async expandRelatedRecords(objectName, records, expand, depth = 0) {
+  async expandRelatedRecords(objectName, records, expand, depth = 0, execCtx) {
     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];
@@ -2190,7 +3834,8 @@ var _ObjectQL = class _ObjectQL {
           ...nestedAST.orderBy ? { orderBy: nestedAST.orderBy } : {}
         };
         const driver = this.getDriver(referenceObject);
-        const relatedRecords = await driver.find(referenceObject, relatedQuery) ?? [];
+        const expandOpts = this.buildDriverOptions(execCtx);
+        const relatedRecords = await driver.find(referenceObject, relatedQuery, expandOpts) ?? [];
         const recordMap = /* @__PURE__ */ new Map();
         for (const rec of relatedRecords) {
           const id = rec.id;
@@ -2201,7 +3846,8 @@ var _ObjectQL = class _ObjectQL {
             referenceObject,
             relatedRecords,
             nestedAST.expand,
-            depth + 1
+            depth + 1,
+            execCtx
           );
           recordMap.clear();
           for (const rec of expandedRelated) {
@@ -2242,6 +3888,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",
@@ -2255,14 +3915,17 @@ 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);
+      hookContext.input.options = this.buildDriverOptions(opCtx.context, hookContext.input.options);
       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);
+          result = await this.expandRelatedRecords(object, result, ast.expand, 0, opCtx.context);
         }
         hookContext.event = "afterFind";
         hookContext.result = result;
@@ -2282,6 +3945,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",
@@ -2290,9 +3964,11 @@ var _ObjectQL = class _ObjectQL {
       context: query?.context
     };
     await this.executeWithMiddleware(opCtx, async () => {
-      let result = await driver.findOne(objectName, opCtx.ast);
+      const findOneOpts = this.buildDriverOptions(opCtx.context);
+      let result = await driver.findOne(objectName, opCtx.ast, findOneOpts);
+      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);
+        const expanded = await this.expandRelatedRecords(objectName, [result], ast.expand, 0, opCtx.context);
         result = expanded[0];
       }
       return result;
@@ -2316,20 +3992,35 @@ 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);
+      hookContext.input.options = this.buildDriverOptions(opCtx.context, hookContext.input.options);
       try {
         let result;
+        const nowSnap = /* @__PURE__ */ new Date();
+        const schemaForValidation = this._registry.getObject(object);
         if (Array.isArray(hookContext.input.data)) {
+          const rows = hookContext.input.data.map(
+            (row) => this.applyFieldDefaults(object, row, opCtx.context, nowSnap)
+          );
+          for (const r of rows) validateRecord(schemaForValidation, r, "insert");
           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
+          );
+          validateRecord(schemaForValidation, row, "insert");
+          result = await driver.create(object, row, hookContext.input.options);
         }
         hookContext.event = "afterInsert";
         hookContext.result = result;
@@ -2396,15 +4087,19 @@ 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
       };
       await this.triggerHooks("beforeUpdate", hookContext);
+      hookContext.input.options = this.buildDriverOptions(opCtx.context, hookContext.input.options);
       try {
         let result;
         if (hookContext.input.id) {
+          validateRecord(this._registry.getObject(object), hookContext.input.data, "update");
           result = await driver.update(object, hookContext.input.id, hookContext.input.data, hookContext.input.options);
         } else if (options?.multi && driver.updateMany) {
+          validateRecord(this._registry.getObject(object), hookContext.input.data, "update");
           const ast = { object, where: options.where };
           result = await driver.updateMany(object, ast, hookContext.input.data, hookContext.input.options);
         } else {
@@ -2461,10 +4156,12 @@ 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
       };
       await this.triggerHooks("beforeDelete", hookContext);
+      hookContext.input.options = this.buildDriverOptions(opCtx.context, hookContext.input.options);
       try {
         let result;
         if (hookContext.input.id) {
@@ -2514,11 +4211,12 @@ var _ObjectQL = class _ObjectQL {
       context: query?.context
     };
     await this.executeWithMiddleware(opCtx, async () => {
+      const countOpts = this.buildDriverOptions(opCtx.context);
       if (driver.count) {
         const ast = { object, where: query?.where };
-        return driver.count(object, ast);
+        return driver.count(object, ast, countOpts);
       }
-      const res = await this.find(object, { where: query?.where, fields: ["id"] });
+      const res = await this.find(object, { where: query?.where, fields: ["id"], context: opCtx.context });
       return res.length;
     });
     return opCtx.result;
@@ -2540,18 +4238,104 @@ var _ObjectQL = class _ObjectQL {
         groupBy: query.groupBy,
         aggregations: query.aggregations
       };
-      return driver.find(object, ast);
+      const drv = driver;
+      const groupByItems = Array.isArray(query.groupBy) ? query.groupBy : [];
+      const granularityCaps = drv?.supports?.queryDateGranularity;
+      const structuredItems = groupByItems.filter((g) => typeof g !== "string");
+      const allStructuredSupported = structuredItems.every((g) => {
+        if (!g?.dateGranularity) return true;
+        return granularityCaps?.[g.dateGranularity] === true;
+      });
+      if (typeof drv.aggregate === "function" && allStructuredSupported) {
+        return drv.aggregate(object, ast, this.buildDriverOptions(opCtx.context));
+      }
+      const raw = await driver.find(object, ast, this.buildDriverOptions(opCtx.context));
+      return applyInMemoryAggregation(raw, ast);
     });
     return opCtx.result;
   }
+  /**
+   * Run raw driver-specific commands (SQL for SqlDriver, REST for RestDriver, …).
+   *
+   * ⚠️ **Tenant isolation bypass.** Raw `execute()` does NOT thread the
+   * caller's `ExecutionContext.tenantId` into a `WHERE organization_id`
+   * predicate — drivers see the command verbatim. Callers MUST inline the
+   * tenant filter themselves, or restrict raw execution to genuinely global
+   * statements (schema migrations, sys_* / control-plane tables).
+   *
+   * Prefer the typed entry points (`find`, `update`, `delete`, `count`, …)
+   * whenever feasible — they auto-apply tenancy + soft-delete + audit warnings.
+   */
   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;
+      }
+    }
+    return driver.execute(rawCommand, params, options);
+  }
+  /**
+   * Execute a callback inside a database transaction.
+   *
+   * The callback receives a context object that should be passed to all
+   * downstream `engine.insert/update/delete/find/findOne` calls (as
+   * `{ context: trxCtx }`). The transaction handle threads through
+   * `OperationContext.context.transaction` and the SQL driver's per-builder
+   * `.transacting(trx)` call.
+   *
+   * - If the default driver does not support `beginTransaction`, the callback
+   *   runs directly with the supplied base context (no rollback). This keeps
+   *   the API safe to call on drivers without ACID support (e.g. the
+   *   in-memory driver in tests).
+   * - On callback success the transaction is committed; on any thrown error
+   *   it is rolled back and the original error is re-thrown.
+   *
+   * Use case: multi-step operations that must be atomic (e.g. CRM
+   * `convertLead`, which creates an account + contact + opportunity + flips
+   * the lead in a single unit of work).
+   */
+  async transaction(callback, baseContext) {
+    const driver = this.defaultDriver ? this.drivers.get(this.defaultDriver) : void 0;
+    const drv = driver;
+    if (!drv?.beginTransaction) {
+      return callback(baseContext);
+    }
+    const trx = await drv.beginTransaction();
+    const trxCtx = { ...baseContext ?? {}, transaction: trx };
+    try {
+      const result = await callback(trxCtx);
+      if (drv.commit) await drv.commit(trx);
+      else if (drv.commitTransaction) await drv.commitTransaction(trx);
+      return result;
+    } catch (err) {
+      try {
+        if (drv.rollback) await drv.rollback(trx);
+        else if (drv.rollbackTransaction) await drv.rollbackTransaction(trx);
+      } catch {
       }
+      throw err;
     }
-    throw new Error("Execute requires options.object to select driver");
   }
   // ============================================
   // Compatibility / Convenience API
@@ -2572,16 +4356,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);
     }
   }
   /**
@@ -2597,7 +4381,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;
@@ -2631,10 +4415,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 = import_system.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) {
@@ -2665,7 +4471,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.
@@ -2684,7 +4490,7 @@ var _ObjectQL = class _ObjectQL {
    */
   createContext(ctx) {
     return new ScopedContext(
-      import_kernel2.ExecutionContextSchema.parse(ctx),
+      import_kernel3.ExecutionContextSchema.parse(ctx),
       this
     );
   }
@@ -2881,86 +4687,97 @@ 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
+var import_system2 = require("@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";
+    /**
+     * Schema sync to remote SQL DBs is latency-bound (one round-trip per
+     * table × 2 phases). Default to 120s instead of the kernel's 30s so
+     * cold Neon/Turso starts don't get killed mid-sync.
+     */
+    this.startupTimeout = 12e4;
+    this.skipSchemaSync = false;
     this.init = async (ctx) => {
       if (!this.ql) {
         const hostCtx = { ...this.hostContext, logger: ctx.logger };
@@ -2982,10 +4799,23 @@ 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");
+      ctx.registerService("analytics", {
+        query: (body) => protocolShim.analyticsQuery(body),
+        getMeta: async () => ({
+          cubes: [],
+          message: "Analytics meta endpoint not implemented by ObjectQL adapter"
+        }),
+        generateSql: async (_body) => ({
+          sql: null,
+          message: "Analytics SQL generation not implemented by ObjectQL adapter"
+        })
+      });
     };
     this.start = async (ctx) => {
       ctx.logger.info("ObjectQL engine starting...");
@@ -3025,103 +4855,194 @@ var ObjectQLPlugin = class {
         }
       }
       await this.ql?.init();
-      await this.restoreMetadataFromDb(ctx);
-      await this.syncRegisteredSchemas(ctx);
-      await this.bridgeObjectsToMetadataService(ctx);
+      if (this.skipSchemaSync) {
+        ctx.logger.info("Skipping schema sync (OS_SKIP_SCHEMA_SYNC=1) \u2014 assuming DDL is managed out-of-band");
+      } else {
+        await this.syncRegisteredSchemas(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)");
+      }
+      if (!this.skipSchemaSync) {
+        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;
+    if (typeof opts.startupTimeout === "number" && opts.startupTimeout > 0) {
+      this.startupTimeout = opts.startupTimeout;
     }
+    this.skipSchemaSync = typeof opts.skipSchemaSync === "boolean" ? opts.skipSchemaSync : process.env.OS_SKIP_SCHEMA_SYNC === "1";
   }
   /**
    * 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 },
+                context: {
+                  roles: [],
+                  permissions: [],
+                  isSystem: true,
+                  ...hookCtx.transaction ? { transaction: hookCtx.transaction } : {}
+                }
+              });
+              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 },
+                context: {
+                  roles: [],
+                  permissions: [],
+                  isSystem: true,
+                  ...hookCtx.transaction ? { transaction: hookCtx.transaction } : {}
+                }
+              });
+              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.
    *
@@ -3160,7 +5081,7 @@ var ObjectQLPlugin = class {
         skipped++;
         continue;
       }
-      const tableName = obj.tableName || obj.name;
+      const tableName = import_system2.StorageNameMapping.resolveTableName(obj);
       let group = driverGroups.get(driver);
       if (!group) {
         group = [];
@@ -3317,13 +5238,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) {
@@ -3333,6 +5261,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`);
           }
@@ -3449,6 +5382,7 @@ function convertIntrospectedSchemaToObjects(introspectedSchema, options) {
 0 && (module.exports = {
   DEFAULT_EXTENDER_PRIORITY,
   DEFAULT_OWNER_PRIORITY,
+  InMemoryHookMetricsRecorder,
   MetadataFacade,
   ObjectQL,
   ObjectQLPlugin,
@@ -3457,10 +5391,18 @@ function convertIntrospectedSchemaToObjects(introspectedSchema, options) {
   RESERVED_NAMESPACES,
   SchemaRegistry,
   ScopedContext,
+  ValidationError,
+  applyInMemoryAggregation,
+  applySystemFields,
+  bindHooksToEngine,
+  bucketDateValue,
   computeFQN,
   convertIntrospectedSchemaToObjects,
   createObjectQLKernel,
+  noopHookMetricsRecorder,
   parseFQN,
-  toTitleCase
+  toTitleCase,
+  validateRecord,
+  wrapDeclarativeHook
 });
 //# sourceMappingURL=index.js.map