@objectstack/objectql 9.8.0 → 9.9.0

package/dist/index.d.mts

@@ -636,6 +636,8 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                 variant?: "link" | "primary" | "secondary" | "danger" | "ghost" | undefined;
                 confirmText?: string | undefined;
                 successMessage?: string | undefined;
+                errorMessage?: string | undefined;
+                undoable?: boolean | undefined;
                 resultDialog?: {
                     title?: string | undefined;
                     description?: string | undefined;
@@ -1161,49 +1163,6 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         totalHits: number;
         truncated: boolean;
     }>;
-    /**
-     * 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.
-     */
-    convertLead(request: {
-        leadId: string;
-        accountId?: string;
-        contactId?: string;
-        createOpportunity?: boolean;
-        opportunity?: {
-            name?: string;
-            amount?: number;
-            close_date?: string;
-            stage?: string;
-        };
-        convertedStatus?: string;
-        context?: any;
-    }): Promise<{
-        lead: any;
-        account: any;
-        contact: any;
-        opportunity: any | null;
-    }>;
     getMetaItemCached(request: {
         type: string;
         name: string;
@@ -2472,7 +2431,10 @@ declare class ObjectQL implements IDataEngine {
      *   - `set_null` → clear the foreign key,
      *   - `restrict` → refuse the delete when dependents exist.
      * `master_detail` defaults to `cascade` (the parent owns the child
-     * lifecycle); `lookup` defaults to `set_null`. Only runs for single-id
+     * lifecycle); `lookup` defaults to `set_null` — except a `set_null` default
+     * on a REQUIRED lookup escalates to `restrict` (you can't null a NOT NULL
+     * FK; restricting with a clear dependent-count message beats a misleading
+     * "<field> is required" 400 from the child). Only runs for single-id
      * deletes — multi/predicate deletes skip cascade (logged).
      */
     private cascadeDeleteRelations;
@@ -2715,13 +2677,25 @@ declare class ScopedContext {
 /**
  * Group + aggregate raw rows according to the AST's `groupBy` /
  * `aggregations`. When neither is present, returns the rows unchanged.
+ *
+ * `timezone` (ADR-0053 Phase 2) shifts date bucketing to a reference timezone
+ * so a row near a tz day-boundary lands in the right day/week/month/quarter.
+ * It is only consulted by `groupBy` items carrying a `dateGranularity`; an
+ * unset or `'UTC'` value keeps the historical UTC bucketing.
  */
-declare function applyInMemoryAggregation(rows: any[], ast: Pick<QueryAST, 'groupBy' | 'aggregations'>): any[];
+declare function applyInMemoryAggregation(rows: any[], ast: Pick<QueryAST, 'groupBy' | 'aggregations'>, timezone?: string): any[];
 /**
  * Bucket a date-like value into an ISO-formatted period label. Weeks start
  * Monday and use ISO week numbering.
+ *
+ * `timezone` (ADR-0053 Phase 2) resolves the calendar day in a reference zone
+ * so an instant near a tz day-boundary buckets where a user in that zone would
+ * expect. An unset / `'UTC'` / invalid zone keeps the historical UTC bucketing.
+ * The y/m/d are taken in the reference zone and the ISO-week math then runs on
+ * a UTC date built from those parts — the parts already carry the zone shift,
+ * so the week boundary lands correctly without re-applying any offset.
  */
-declare function bucketDateValue(value: unknown, granularity: DateGranularityValue): string;
+declare function bucketDateValue(value: unknown, granularity: DateGranularityValue, timezone?: string): string;
 
 /**
  * Hook Execution Metrics
@@ -2917,7 +2891,7 @@ declare function wrapDeclarativeHook(meta: Hook, handler: HookHandler, opts?: Wr
 
 interface FieldValidationError {
     field: string;
-    code: 'required' | 'min_length' | 'max_length' | 'min_value' | 'max_value' | 'invalid_email' | 'invalid_url' | 'invalid_phone' | 'invalid_number' | 'invalid_boolean' | 'invalid_date' | 'invalid_option' | 'invalid_transition' | 'rule_violation' | 'invalid_format' | 'invalid_json' | 'json_schema_violation';
+    code: 'required' | 'min_length' | 'max_length' | 'min_value' | 'max_value' | 'invalid_email' | 'invalid_url' | 'invalid_phone' | 'invalid_number' | 'invalid_boolean' | 'invalid_date' | 'invalid_time' | 'invalid_option' | 'invalid_transition' | 'rule_violation' | 'invalid_format' | 'invalid_json' | 'json_schema_violation';
     message: string;
     /** Allowed values for select/multiselect, when applicable. */
     options?: string[];

package/dist/index.d.ts

@@ -636,6 +636,8 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                 variant?: "link" | "primary" | "secondary" | "danger" | "ghost" | undefined;
                 confirmText?: string | undefined;
                 successMessage?: string | undefined;
+                errorMessage?: string | undefined;
+                undoable?: boolean | undefined;
                 resultDialog?: {
                     title?: string | undefined;
                     description?: string | undefined;
@@ -1161,49 +1163,6 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         totalHits: number;
         truncated: boolean;
     }>;
-    /**
-     * 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.
-     */
-    convertLead(request: {
-        leadId: string;
-        accountId?: string;
-        contactId?: string;
-        createOpportunity?: boolean;
-        opportunity?: {
-            name?: string;
-            amount?: number;
-            close_date?: string;
-            stage?: string;
-        };
-        convertedStatus?: string;
-        context?: any;
-    }): Promise<{
-        lead: any;
-        account: any;
-        contact: any;
-        opportunity: any | null;
-    }>;
     getMetaItemCached(request: {
         type: string;
         name: string;
@@ -2472,7 +2431,10 @@ declare class ObjectQL implements IDataEngine {
      *   - `set_null` → clear the foreign key,
      *   - `restrict` → refuse the delete when dependents exist.
      * `master_detail` defaults to `cascade` (the parent owns the child
-     * lifecycle); `lookup` defaults to `set_null`. Only runs for single-id
+     * lifecycle); `lookup` defaults to `set_null` — except a `set_null` default
+     * on a REQUIRED lookup escalates to `restrict` (you can't null a NOT NULL
+     * FK; restricting with a clear dependent-count message beats a misleading
+     * "<field> is required" 400 from the child). Only runs for single-id
      * deletes — multi/predicate deletes skip cascade (logged).
      */
     private cascadeDeleteRelations;
@@ -2715,13 +2677,25 @@ declare class ScopedContext {
 /**
  * Group + aggregate raw rows according to the AST's `groupBy` /
  * `aggregations`. When neither is present, returns the rows unchanged.
+ *
+ * `timezone` (ADR-0053 Phase 2) shifts date bucketing to a reference timezone
+ * so a row near a tz day-boundary lands in the right day/week/month/quarter.
+ * It is only consulted by `groupBy` items carrying a `dateGranularity`; an
+ * unset or `'UTC'` value keeps the historical UTC bucketing.
  */
-declare function applyInMemoryAggregation(rows: any[], ast: Pick<QueryAST, 'groupBy' | 'aggregations'>): any[];
+declare function applyInMemoryAggregation(rows: any[], ast: Pick<QueryAST, 'groupBy' | 'aggregations'>, timezone?: string): any[];
 /**
  * Bucket a date-like value into an ISO-formatted period label. Weeks start
  * Monday and use ISO week numbering.
+ *
+ * `timezone` (ADR-0053 Phase 2) resolves the calendar day in a reference zone
+ * so an instant near a tz day-boundary buckets where a user in that zone would
+ * expect. An unset / `'UTC'` / invalid zone keeps the historical UTC bucketing.
+ * The y/m/d are taken in the reference zone and the ISO-week math then runs on
+ * a UTC date built from those parts — the parts already carry the zone shift,
+ * so the week boundary lands correctly without re-applying any offset.
  */
-declare function bucketDateValue(value: unknown, granularity: DateGranularityValue): string;
+declare function bucketDateValue(value: unknown, granularity: DateGranularityValue, timezone?: string): string;
 
 /**
  * Hook Execution Metrics
@@ -2917,7 +2891,7 @@ declare function wrapDeclarativeHook(meta: Hook, handler: HookHandler, opts?: Wr
 
 interface FieldValidationError {
     field: string;
-    code: 'required' | 'min_length' | 'max_length' | 'min_value' | 'max_value' | 'invalid_email' | 'invalid_url' | 'invalid_phone' | 'invalid_number' | 'invalid_boolean' | 'invalid_date' | 'invalid_option' | 'invalid_transition' | 'rule_violation' | 'invalid_format' | 'invalid_json' | 'json_schema_violation';
+    code: 'required' | 'min_length' | 'max_length' | 'min_value' | 'max_value' | 'invalid_email' | 'invalid_url' | 'invalid_phone' | 'invalid_number' | 'invalid_boolean' | 'invalid_date' | 'invalid_time' | 'invalid_option' | 'invalid_transition' | 'rule_violation' | 'invalid_format' | 'invalid_json' | 'json_schema_violation';
     message: string;
     /** Allowed values for select/multiselect, when applicable. */
     options?: string[];

package/dist/index.js

@@ -4345,145 +4345,6 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     };
   }
   // ==========================================
-  // 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) {
@@ -6316,7 +6177,7 @@ var ObjectStackProtocolImplementation = _ObjectStackProtocolImplementation;
 // src/engine.ts
 var import_node_async_hooks = require("async_hooks");
 var import_kernel6 = require("@objectstack/spec/kernel");
-var import_core = require("@objectstack/core");
+var import_core2 = require("@objectstack/core");
 var import_system2 = require("@objectstack/spec/system");
 
 // src/secret-fields.ts
@@ -6847,11 +6708,20 @@ function validateOne(name, def, value) {
     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 (t === "date" || t === "datetime") {
     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 === "time") {
+    if (value instanceof Date) return null;
+    if (typeof value === "string") {
+      const timeOfDay = /^([01]\d|2[0-3]):[0-5]\d(:[0-5]\d(\.\d+)?)?(Z|[+-]([01]\d|2[0-3]):?[0-5]\d)?$/;
+      const hasDate = /\d{4}-\d{2}-\d{2}/.test(value);
+      if (timeOfDay.test(value.trim()) || hasDate && !Number.isNaN(Date.parse(value))) return null;
+    }
+    return { field: name, code: "invalid_time", message: `${name} must be a valid time (HH:MM or HH:MM:SS)` };
+  }
   if (t === "select" || t === "radio") {
     const allowed = optionValues(def.options);
     if (allowed.length > 0 && !allowed.includes(String(value))) {
@@ -7167,7 +7037,8 @@ function legalNextStates(objectSchema, field, currentState) {
 }
 
 // src/in-memory-aggregation.ts
-function applyInMemoryAggregation(rows, ast) {
+var import_core = require("@objectstack/core");
+function applyInMemoryAggregation(rows, ast, timezone) {
   const groupBy = ast.groupBy ?? [];
   const aggregations = ast.aggregations ?? [];
   if (groupBy.length === 0 && aggregations.length === 0) return rows;
@@ -7180,7 +7051,7 @@ function applyInMemoryAggregation(rows, ast) {
     const parts = [];
     for (const g of groupBy) {
       const fieldName = typeof g === "string" ? g : g.alias ?? g.field;
-      const value = projectGroupValue(row, g);
+      const value = projectGroupValue(row, g, timezone);
       key[fieldName] = value;
       parts.push(`${fieldName}=${value}`);
     }
@@ -7199,11 +7070,11 @@ function applyInMemoryAggregation(rows, ast) {
   }
   return out;
 }
-function projectGroupValue(row, g) {
+function projectGroupValue(row, g, timezone) {
   const field = typeof g === "string" ? g : g.field;
   const v = row?.[field];
   if (typeof g !== "string" && g.dateGranularity) {
-    return bucketDateValue(v, g.dateGranularity);
+    return bucketDateValue(v, g.dateGranularity, timezone);
   }
   return v == null ? "(null)" : String(v);
 }
@@ -7281,12 +7152,11 @@ function toNumber(v) {
   const n = Number(v);
   return Number.isFinite(n) ? n : 0;
 }
-function bucketDateValue(value, granularity) {
+function bucketDateValue(value, granularity, timezone) {
   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;
+  const { year: y, month: m, day } = (0, import_core.calendarPartsInTzOrUtc)(d, timezone);
   switch (granularity) {
     case "year":
       return String(y);
@@ -7295,9 +7165,9 @@ function bucketDateValue(value, granularity) {
     case "month":
       return `${y}-${String(m).padStart(2, "0")}`;
     case "day":
-      return `${y}-${String(m).padStart(2, "0")}-${String(d.getUTCDate()).padStart(2, "0")}`;
+      return `${y}-${String(m).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
     case "week": {
-      const target = new Date(Date.UTC(y, d.getUTCMonth(), d.getUTCDate()));
+      const target = new Date(Date.UTC(y, m - 1, day));
       const dayNum = (target.getUTCDay() + 6) % 7;
       target.setUTCDate(target.getUTCDate() - dayNum + 3);
       const firstThursday = new Date(Date.UTC(target.getUTCFullYear(), 0, 4));
@@ -7340,12 +7210,16 @@ function planFormulaProjection(schema, requestedFields) {
   }
   return { plan };
 }
-function applyFormulaPlan(plan, records) {
+function applyFormulaPlan(plan, records, execCtx, nowSnapshot) {
   if (!plan.length) return;
+  const now = nowSnapshot ?? /* @__PURE__ */ new Date();
+  const timezone = execCtx?.timezone;
+  const user = execCtx?.userId ? { id: String(execCtx.userId), role: execCtx?.roles?.[0] } : void 0;
+  const org = execCtx?.tenantId ? { id: String(execCtx.tenantId) } : void 0;
   for (const rec of records) {
     if (rec == null) continue;
     for (const fp of plan) {
-      const r = import_formula4.ExpressionEngine.evaluate(fp.expression, { record: rec });
+      const r = import_formula4.ExpressionEngine.evaluate(fp.expression, { now, timezone, user, org, record: rec });
       rec[fp.name] = r.ok ? r.value : null;
     }
   }
@@ -7423,7 +7297,7 @@ var _ObjectQL = class _ObjectQL {
      *  parent objects that aggregate it. Invalidated when packages register. */
     this.summaryIndex = null;
     this.hostContext = hostContext;
-    this.logger = hostContext.logger || (0, import_core.createLogger)({ level: "info", format: "pretty" });
+    this.logger = hostContext.logger || (0, import_core2.createLogger)({ level: "info", format: "pretty" });
     if (process?.env?.OBJECTQL_STRICT_HOOKS === "1") {
       this._strictHookBinding = true;
     }
@@ -7777,6 +7651,7 @@ var _ObjectQL = class _ObjectQL {
       if (typeof dv === "object" && dv !== null && dv.dialect && typeof dv.source === "string") {
         const result = import_formula4.ExpressionEngine.evaluate(dv, {
           now,
+          timezone: execCtx?.timezone,
           user: execCtx?.userId ? { id: String(execCtx.userId), role: execCtx?.roles?.[0] } : void 0,
           org: execCtx?.tenantId ? { id: String(execCtx.tenantId) } : void 0,
           record: out,
@@ -8713,7 +8588,7 @@ var _ObjectQL = class _ObjectQL {
       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 (Array.isArray(result)) applyFormulaPlan(_findFormula.plan, result, opCtx.context);
         if (ast.expand && Object.keys(ast.expand).length > 0 && Array.isArray(result)) {
           result = await this.expandRelatedRecords(object, result, ast.expand, 0, opCtx.context);
         }
@@ -8757,7 +8632,7 @@ var _ObjectQL = class _ObjectQL {
     await this.executeWithMiddleware(opCtx, async () => {
       const findOneOpts = this.buildDriverOptions(opCtx.context);
       let result = await driver.findOne(objectName, opCtx.ast, findOneOpts);
-      if (result != null) applyFormulaPlan(_findOneFormula.plan, [result]);
+      if (result != null) applyFormulaPlan(_findOneFormula.plan, [result], opCtx.context);
       if (ast.expand && Object.keys(ast.expand).length > 0 && result != null) {
         const expanded = await this.expandRelatedRecords(objectName, [result], ast.expand, 0, opCtx.context);
         result = expanded[0];
@@ -8972,7 +8847,10 @@ var _ObjectQL = class _ObjectQL {
    *   - `set_null` → clear the foreign key,
    *   - `restrict` → refuse the delete when dependents exist.
    * `master_detail` defaults to `cascade` (the parent owns the child
-   * lifecycle); `lookup` defaults to `set_null`. Only runs for single-id
+   * lifecycle); `lookup` defaults to `set_null` — except a `set_null` default
+   * on a REQUIRED lookup escalates to `restrict` (you can't null a NOT NULL
+   * FK; restricting with a clear dependent-count message beats a misleading
+   * "<field> is required" 400 from the child). Only runs for single-id
    * deletes — multi/predicate deletes skip cascade (logged).
    */
   async cascadeDeleteRelations(object, id, context, depth = 0) {
@@ -8998,7 +8876,10 @@ var _ObjectQL = class _ObjectQL {
           resolvedRef = void 0;
         }
         if (ref !== object && resolvedRef !== object) continue;
-        const behavior = fdef.type === "master_detail" ? fdef.deleteBehavior === "restrict" ? "restrict" : "cascade" : fdef.deleteBehavior || "set_null";
+        let behavior = fdef.type === "master_detail" ? fdef.deleteBehavior === "restrict" ? "restrict" : "cascade" : fdef.deleteBehavior || "set_null";
+        if (behavior === "set_null" && fdef.required === true) {
+          behavior = "restrict";
+        }
         let dependents;
         try {
           dependents = await this.find(childName, { where: { [fieldName]: id }, context });
@@ -9007,9 +8888,16 @@ var _ObjectQL = class _ObjectQL {
         }
         if (!dependents || dependents.length === 0) continue;
         if (behavior === "restrict") {
-          throw new Error(
-            `Cannot delete ${object} (${id}): ${dependents.length} dependent ${childName} record(s) via ${fieldName}`
+          const reason = fdef.deleteBehavior !== "restrict" && fdef.required === true ? ` (${fieldName} is required, so it cannot be cleared)` : "";
+          const err = new Error(
+            `Cannot delete ${object} (${id}): ${dependents.length} dependent ${childName} record(s) reference it via ${fieldName}${reason}. Delete or reassign them first, or set deleteBehavior:'cascade' on ${childName}.${fieldName}.`
           );
+          err.code = "DELETE_RESTRICTED";
+          err.status = 409;
+          err.object = object;
+          err.dependentObject = childName;
+          err.dependentCount = dependents.length;
+          throw err;
         }
         for (const dep of dependents) {
           const depId = dep?.id;
@@ -9143,11 +9031,14 @@ var _ObjectQL = class _ObjectQL {
         if (!g?.dateGranularity) return true;
         return granularityCaps?.[g.dateGranularity] === true;
       });
-      if (typeof drv.aggregate === "function" && allStructuredSupported) {
+      const tz = query.timezone;
+      const hasDateBucket = structuredItems.some((g) => !!g?.dateGranularity);
+      const tzRequiresInMemory = !!tz && tz !== "UTC" && hasDateBucket;
+      if (typeof drv.aggregate === "function" && allStructuredSupported && !tzRequiresInMemory) {
         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 applyInMemoryAggregation(raw, ast, tz);
     });
     return opCtx.result;
   }
@@ -10354,9 +10245,9 @@ var ObjectQLPlugin = class {
 };
 
 // src/kernel-factory.ts
-var import_core2 = require("@objectstack/core");
+var import_core3 = require("@objectstack/core");
 async function createObjectQLKernel(options = {}) {
-  const kernel = new import_core2.ObjectKernel();
+  const kernel = new import_core3.ObjectKernel();
   await kernel.use(new ObjectQLPlugin());
   if (options.plugins) {
     for (const plugin of options.plugins) {