@objectstack/objectql 4.0.5 → 4.1.1

package/dist/index.js

@@ -31,14 +31,18 @@ __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,
+  validateRecord: () => validateRecord,
   wrapDeclarativeHook: () => wrapDeclarativeHook
 });
 module.exports = __toCommonJS(index_exports);
@@ -81,9 +85,11 @@ function mergeObjectDefinitions(base, extension) {
 }
 function applySystemFields(schema, opts) {
   if (schema.systemFields === false) return schema;
-  if (schema.managedBy) return schema;
+  if (schema.managedBy === "better-auth") return schema;
   const sf = typeof schema.systemFields === "object" && schema.systemFields !== null ? schema.systemFields : void 0;
-  const wantTenant = opts.multiTenant && sf?.tenant !== false;
+  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 = {
@@ -94,9 +100,54 @@ function applySystemFields(schema, opts) {
       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,
@@ -592,6 +643,22 @@ var SchemaRegistry = class {
 // 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++) {
@@ -618,13 +685,67 @@ var SERVICE_CONFIG = {
   "file-storage": { route: "/api/v1/storage", plugin: "plugin-storage" },
   search: { route: "/api/v1/search", plugin: "plugin-search" }
 };
-var ObjectStackProtocolImplementation = class {
+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-
@@ -758,24 +879,32 @@ var ObjectStackProtocolImplementation = class {
         if (alt) items = [...this.engine.registry.listItems(alt, packageId)];
       }
     }
-    if (this.projectId === void 0) try {
-      const whereClause = {
-        type: request.type,
-        state: "active",
-        // Always filter by project_id: project kernels use their projectId,
-        // control-plane kernels use NULL (global scope only).
-        project_id: this.projectId ?? null
-      };
-      if (packageId) whereClause._packageId = packageId;
-      let records = await this.engine.find("sys_metadata", { where: whereClause });
-      if (!records || records.length === 0) {
-        const alt = import_shared.PLURAL_TO_SINGULAR[request.type] ?? import_shared.SINGULAR_TO_PLURAL[request.type];
-        if (alt) {
-          const altWhere = { type: alt, state: "active", project_id: this.projectId ?? null };
-          if (packageId) altWhere._packageId = packageId;
-          records = await this.engine.find("sys_metadata", { where: altWhere });
+    try {
+      const orgId = request.organizationId;
+      const queryByOrg = async (oid) => {
+        const whereClause = {
+          type: request.type,
+          state: "active",
+          organization_id: oid
+        };
+        if (packageId) whereClause._packageId = packageId;
+        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 altWhere = { type: alt, state: "active", organization_id: oid };
+            if (packageId) altWhere._packageId = packageId;
+            rs = await this.engine.find("sys_metadata", { where: altWhere });
+          }
         }
-      }
+        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) {
@@ -816,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());
@@ -831,44 +962,40 @@ var ObjectStackProtocolImplementation = class {
   }
   async getMetaItem(request) {
     let item;
-    if (this.projectId === void 0) {
-      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 && this.projectId === void 0) {
-      try {
-        const scopedWhere = {
+    const orgId = request.organizationId;
+    try {
+      const findOverlay = async (oid) => {
+        const where = {
           type: request.type,
           name: request.name,
-          state: "active"
+          state: "active",
+          organization_id: oid
         };
-        scopedWhere.project_id = this.projectId ?? null;
-        const record = await this.engine.findOne("sys_metadata", {
-          where: scopedWhere
-        });
-        if (record) {
-          item = typeof record.metadata === "string" ? JSON.parse(record.metadata) : record.metadata;
-          if (this.projectId === void 0) {
-            this.engine.registry.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 altWhere = { type: alt, name: request.name, state: "active" };
-            altWhere.project_id = this.projectId ?? null;
-            const altRecord = await this.engine.findOne("sys_metadata", { where: altWhere });
-            if (altRecord) {
-              item = typeof altRecord.metadata === "string" ? JSON.parse(altRecord.metadata) : altRecord.metadata;
-              if (this.projectId === void 0) {
-                this.engine.registry.registerItem(request.type, item, "name");
-              }
-            }
-          }
+        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 });
         }
-      } catch {
+        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) {
+      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) {
@@ -947,6 +1074,18 @@ var ObjectStackProtocolImplementation = class {
     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;
@@ -1053,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,
@@ -1086,7 +1242,11 @@ 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(
@@ -1121,25 +1281,281 @@ var ObjectStackProtocolImplementation = class {
     };
   }
   // ==========================================
-  // Metadata Caching
+  // Global Search (M10.5)
   // ==========================================
-  async getMetaItemCached(request) {
-    try {
-      let item = this.engine.registry.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 = this.engine.registry.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`);
       }
@@ -1431,45 +1847,65 @@ 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");
     }
-    if (this.projectId !== void 0) {
-      this.engine.registry.registerItem(request.type, request.item, "name");
-      if (request.type === "object" || request.type === "objects") {
-        try {
-          this.engine.registry.registerObject(request.item, "sys_metadata");
-        } catch (err) {
-          console.warn(
-            `[Protocol] registerObject failed for ${request.name}: ${err?.message ?? err}`
+    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;
         }
       }
-      return {
-        success: true,
-        message: "Saved to memory registry (project kernel \u2014 sys_metadata is control-plane only)"
-      };
     }
-    this.engine.registry.registerItem(request.type, request.item, "name");
     if (request.type === "object" || request.type === "objects") {
+      this.engine.registry.registerItem(request.type, request.item, "name");
       try {
         this.engine.registry.registerObject(request.item, "sys_metadata");
       } catch (err) {
         console.warn(
-          `[Protocol] this.engine.registry.registerObject failed for ${request.name}: ${err?.message ?? err}`
+          `[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
+        name: request.name,
+        organization_id: orgId,
+        state: "active"
       };
-      if (this.projectId !== void 0) {
-        scopedWhere.project_id = this.projectId;
-      }
       const existing = await this.engine.findOne("sys_metadata", {
         where: scopedWhere
       });
@@ -1477,7 +1913,8 @@ var ObjectStackProtocolImplementation = class {
         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 }
         });
@@ -1487,49 +1924,105 @@ var ObjectStackProtocolImplementation = class {
           id,
           name: request.name,
           type: request.type,
-          // `scope` tracks platform vs project authorship. With
-          // project_id carries the project id, 'project' is the
-          // honest label whenever we know we're inside one.
-          scope: this.projectId !== void 0 ? "project" : "platform",
+          // `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
         };
-        if (this.projectId !== void 0) {
-          row.project_id = this.projectId;
-        }
         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() {
-    if (this.projectId !== void 0) {
-      return { loaded: 0, errors: 0 };
-    }
     let loaded = 0;
     let errors = 0;
     try {
       const where = {
         state: "active",
-        project_id: this.projectId ?? null
+        organization_id: null
       };
       const records = await this.engine.find("sys_metadata", { where });
       for (const record of records) {
@@ -1686,9 +2179,30 @@ var ObjectStackProtocolImplementation = class {
     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_kernel2 = require("@objectstack/spec/kernel");
+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");
@@ -2122,6 +2636,275 @@ function resolveHandler(engine, hook, opts) {
   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` };
+  }
+  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)` };
+  }
+  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;
+  }
+  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;
+  }
+  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);
+  }
+  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
 function planFormulaProjection(schema, requestedFields) {
   if (!schema?.fields) return { plan: [] };
@@ -2142,7 +2925,11 @@ function planFormulaProjection(schema, requestedFields) {
   if (plan.length === 0) return { plan: [] };
   if (Array.isArray(requestedFields) && requestedFields.length > 0) {
     if (!projected.has("id")) projected.add("id");
-    for (const fname of allFieldNames) projected.add(fname);
+    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 };
@@ -2486,9 +3273,42 @@ 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.
@@ -2982,7 +3802,7 @@ 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 = this._registry.getObject(objectName);
@@ -3014,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;
@@ -3025,7 +3846,8 @@ var _ObjectQL = class _ObjectQL {
             referenceObject,
             relatedRecords,
             nestedAST.expand,
-            depth + 1
+            depth + 1,
+            execCtx
           );
           recordMap.clear();
           for (const rec of expandedRelated) {
@@ -3098,11 +3920,12 @@ var _ObjectQL = class _ObjectQL {
         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;
@@ -3141,10 +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;
@@ -3173,13 +3997,16 @@ var _ObjectQL = class _ObjectQL {
         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, rows, hookContext.input.options);
           } else {
@@ -3192,6 +4019,7 @@ var _ObjectQL = class _ObjectQL {
             opCtx.context,
             nowSnap
           );
+          validateRecord(schemaForValidation, row, "insert");
           result = await driver.create(object, row, hookContext.input.options);
         }
         hookContext.event = "afterInsert";
@@ -3264,11 +4092,14 @@ var _ObjectQL = class _ObjectQL {
         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 {
@@ -3330,6 +4161,7 @@ var _ObjectQL = class _ObjectQL {
         ql: this
       };
       await this.triggerHooks("beforeDelete", hookContext);
+      hookContext.input.options = this.buildDriverOptions(opCtx.context, hookContext.input.options);
       try {
         let result;
         if (hookContext.input.id) {
@@ -3379,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;
@@ -3406,13 +4239,33 @@ var _ObjectQL = class _ObjectQL {
         aggregations: query.aggregations
       };
       const drv = driver;
-      if (typeof drv.aggregate === "function") {
-        return drv.aggregate(object, ast);
+      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));
       }
-      return driver.find(object, ast);
+      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) {
@@ -3442,6 +4295,48 @@ var _ObjectQL = class _ObjectQL {
     }
     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;
+    }
+  }
   // ============================================
   // Compatibility / Convenience API
   // ============================================
@@ -3595,7 +4490,7 @@ var _ObjectQL = class _ObjectQL {
    */
   createContext(ctx) {
     return new ScopedContext(
-      import_kernel2.ExecutionContextSchema.parse(ctx),
+      import_kernel3.ExecutionContextSchema.parse(ctx),
       this
     );
   }
@@ -3876,6 +4771,13 @@ var ObjectQLPlugin = class {
     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 };
@@ -3903,6 +4805,17 @@ var ObjectQLPlugin = class {
       );
       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...");
@@ -3942,13 +4855,19 @@ var ObjectQLPlugin = class {
         }
       }
       await this.ql?.init();
-      await this.syncRegisteredSchemas(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)");
       }
-      await this.syncRegisteredSchemas(ctx);
+      if (!this.skipSchemaSync) {
+        await this.syncRegisteredSchemas(ctx);
+      }
       if (this.projectId === void 0) {
         await this.bridgeObjectsToMetadataService(ctx);
       }
@@ -3969,6 +4888,10 @@ var ObjectQLPlugin = class {
     }
     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
@@ -4056,7 +4979,13 @@ var ObjectQLPlugin = class {
           if (hookCtx.input?.id && !hookCtx.previous) {
             try {
               const existing = await this.ql.findOne(hookCtx.object, {
-                where: { id: hookCtx.input.id }
+                where: { id: hookCtx.input.id },
+                context: {
+                  roles: [],
+                  permissions: [],
+                  isSystem: true,
+                  ...hookCtx.transaction ? { transaction: hookCtx.transaction } : {}
+                }
               });
               if (existing) hookCtx.previous = existing;
             } catch (_e) {
@@ -4074,7 +5003,13 @@ var ObjectQLPlugin = class {
           if (hookCtx.input?.id && !hookCtx.previous) {
             try {
               const existing = await this.ql.findOne(hookCtx.object, {
-                where: { id: hookCtx.input.id }
+                where: { id: hookCtx.input.id },
+                context: {
+                  roles: [],
+                  permissions: [],
+                  isSystem: true,
+                  ...hookCtx.transaction ? { transaction: hookCtx.transaction } : {}
+                }
               });
               if (existing) hookCtx.previous = existing;
             } catch (_e) {
@@ -4456,14 +5391,18 @@ function convertIntrospectedSchemaToObjects(introspectedSchema, options) {
   RESERVED_NAMESPACES,
   SchemaRegistry,
   ScopedContext,
+  ValidationError,
+  applyInMemoryAggregation,
   applySystemFields,
   bindHooksToEngine,
+  bucketDateValue,
   computeFQN,
   convertIntrospectedSchemaToObjects,
   createObjectQLKernel,
   noopHookMetricsRecorder,
   parseFQN,
   toTitleCase,
+  validateRecord,
   wrapDeclarativeHook
 });
 //# sourceMappingURL=index.js.map