@objectstack/driver-sql 4.0.4 → 4.1.0

package/dist/index.mjs

@@ -1,13 +1,66 @@
 // src/sql-driver.ts
+import { StorageNameMapping } from "@objectstack/spec/system";
 import knex from "knex";
 import { nanoid } from "nanoid";
 var DEFAULT_ID_LENGTH = 16;
+var SEQUENCES_TABLE = "_objectstack_sequences";
+var GLOBAL_TENANT = "__global__";
 var SqlDriver = class {
   constructor(config) {
     // IDataDriver metadata
     this.name = "com.objectstack.driver.sql";
     this.version = "1.0.0";
-    this.supports = {
+    this.jsonFields = {};
+    this.booleanFields = {};
+    this.tablesWithTimestamps = /* @__PURE__ */ new Set();
+    /**
+     * Autonumber field configs per table, captured during initObjects.
+     *
+     * Each entry records:
+     *   - `prefix` + `padWidth`: how to render the next value (`CTR-0007`)
+     *   - `tenantField`: the column to scope the sequence by (defaults to
+     *     `organization_id` if the object has that field, otherwise null →
+     *     sequence is shared globally for that field)
+     *
+     * Numbering is backed by the `_objectstack_sequences` row keyed by
+     * `(object, tenant_id, field)`, not by scanning the data table on each
+     * insert. The sequence row is bootstrapped from the existing MAX on
+     * first use so legacy data is respected.
+     */
+    this.autoNumberFields = {};
+    /** Whether the sequences table has been ensured this process. */
+    this.sequencesTableReady = false;
+    /** In-flight ensure promise; deduplicates concurrent first calls. */
+    this.sequencesTableEnsurePromise = null;
+    /**
+     * Per-table tenant-isolation column. Populated during `initObjects` by
+     * detecting an `organization_id` field. When set and the caller passes
+     * `DriverOptions.tenantId`, the driver automatically:
+     *
+     *   - scopes reads/updates/deletes/aggregates to that tenant
+     *   - injects `organization_id` on inserts that omit it
+     *
+     * If `tenantId` is absent (admin / seed / system path) no scope is
+     * applied — preserves backward compatibility for tools that legitimately
+     * need cross-tenant access. Tenant enforcement is therefore opt-in by
+     * the caller, not by the driver.
+     */
+    this.tenantFieldByTable = {};
+    /** Throttle table for missing-tenantId warnings ({object}:{op}). */
+    this.tenantAuditWarned = /* @__PURE__ */ new Set();
+    /**
+     * Optional logger sink for security-audit warnings. Tests inject a spy;
+     * production callers wire in their preferred logger. Defaults to
+     * `console.warn` so warnings surface even without setup.
+     */
+    this.logger = {
+      warn: (msg, meta) => console.warn(msg, meta ?? "")
+    };
+    this.config = config;
+    this.knex = knex(config);
+  }
+  get supports() {
+    return {
       // Basic CRUD Operations
       create: true,
       read: true,
@@ -23,6 +76,12 @@ var SqlDriver = class {
       // Query Operations
       queryFilters: true,
       queryAggregations: true,
+      /**
+       * Per-granularity native date bucket support. Granularities marked
+       * `false` (or absent) fall back to in-memory `bucketDateValue()` via
+       * `engine.findData` — see `buildDateBucketExpr()` for the SQL emitted.
+       */
+      queryDateGranularity: this.dateGranularityCapabilities,
       querySorting: true,
       queryPagination: true,
       queryWindowFunctions: true,
@@ -47,11 +106,6 @@ var SqlDriver = class {
       preparedStatements: true,
       queryCache: false
     };
-    this.jsonFields = {};
-    this.booleanFields = {};
-    this.tablesWithTimestamps = /* @__PURE__ */ new Set();
-    this.config = config;
-    this.knex = knex(config);
   }
   /** Whether the underlying database is a SQLite variant (sqlite3 or better-sqlite3). */
   get isSqlite() {
@@ -68,6 +122,86 @@ var SqlDriver = class {
     const c = this.config.client;
     return c === "mysql" || c === "mysql2";
   }
+  /**
+   * Per-granularity native SQL bucket support, computed from dialect.
+   *
+   * Must match `bucketDateValue()` in @objectstack/objectql exactly:
+   *   year    → 'YYYY'
+   *   month   → 'YYYY-MM'
+   *   day     → 'YYYY-MM-DD'
+   *   quarter → 'YYYY-Q[1-4]'
+   *   week    → 'YYYY-W[01-53]' (ISO-8601)
+   *
+   * Granularities not listed (or set to false) fall back to in-memory bucketing
+   * via engine.findData → applyInMemoryAggregation.
+   */
+  get dateGranularityCapabilities() {
+    if (this.isPostgres) {
+      return { day: true, month: true, quarter: true, year: true, week: true };
+    }
+    if (this.isMysql) {
+      return { day: true, month: true, quarter: true, year: true, week: true };
+    }
+    if (this.isSqlite) {
+      return { day: true, month: true, quarter: true, year: true, week: false };
+    }
+    return {};
+  }
+  /**
+   * Build SQL fragment + bindings for a date bucket expression.
+   * Returns `null` when the current dialect does not support the requested
+   * granularity — callers must fall back to in-memory bucketing.
+   *
+   * Exposed as `{sql, bindings}` (not `Knex.Raw`) so callers can both
+   * `groupByRaw()` and embed the same expression inside a `select() as alias`
+   * with correctly forwarded identifier bindings.
+   */
+  buildDateBucketExpr(field, granularity) {
+    if (!this.dateGranularityCapabilities[granularity]) return null;
+    if (this.isPostgres) {
+      switch (granularity) {
+        case "year":
+          return { sql: `to_char((??)::timestamptz AT TIME ZONE 'UTC', 'YYYY')`, bindings: [field] };
+        case "month":
+          return { sql: `to_char((??)::timestamptz AT TIME ZONE 'UTC', 'YYYY-MM')`, bindings: [field] };
+        case "day":
+          return { sql: `to_char((??)::timestamptz AT TIME ZONE 'UTC', 'YYYY-MM-DD')`, bindings: [field] };
+        case "quarter":
+          return { sql: `to_char((??)::timestamptz AT TIME ZONE 'UTC', 'YYYY"-Q"Q')`, bindings: [field] };
+        case "week":
+          return { sql: `to_char((??)::timestamptz AT TIME ZONE 'UTC', 'IYYY"-W"IW')`, bindings: [field] };
+      }
+    }
+    if (this.isMysql) {
+      switch (granularity) {
+        case "year":
+          return { sql: `date_format(convert_tz(??, @@session.time_zone, '+00:00'), '%Y')`, bindings: [field] };
+        case "month":
+          return { sql: `date_format(convert_tz(??, @@session.time_zone, '+00:00'), '%Y-%m')`, bindings: [field] };
+        case "day":
+          return { sql: `date_format(convert_tz(??, @@session.time_zone, '+00:00'), '%Y-%m-%d')`, bindings: [field] };
+        case "quarter":
+          return { sql: `concat(date_format(convert_tz(??, @@session.time_zone, '+00:00'), '%Y'), '-Q', quarter(convert_tz(??, @@session.time_zone, '+00:00')))`, bindings: [field, field] };
+        case "week":
+          return { sql: `date_format(convert_tz(??, @@session.time_zone, '+00:00'), '%x-W%v')`, bindings: [field] };
+      }
+    }
+    if (this.isSqlite) {
+      switch (granularity) {
+        case "year":
+          return { sql: `strftime('%Y', ??)`, bindings: [field] };
+        case "month":
+          return { sql: `strftime('%Y-%m', ??)`, bindings: [field] };
+        case "day":
+          return { sql: `strftime('%Y-%m-%d', ??)`, bindings: [field] };
+        case "quarter":
+          return { sql: `(strftime('%Y', ??) || '-Q' || ((cast(strftime('%m', ??) as integer) - 1) / 3 + 1))`, bindings: [field, field] };
+        case "week":
+          return null;
+      }
+    }
+    return null;
+  }
   // ===================================
   // Lifecycle
   // ===================================
@@ -90,6 +224,7 @@ var SqlDriver = class {
   // ===================================
   async find(object, query, options) {
     const builder = this.getBuilder(object, options);
+    this.applyTenantScope(builder, object, options);
     if (query.fields) {
       builder.select(query.fields.map((f) => this.mapSortField(f)));
     } else {
@@ -128,7 +263,9 @@ var SqlDriver = class {
   }
   async findOne(object, query, options) {
     if (typeof query === "string" || typeof query === "number") {
-      const res = await this.getBuilder(object, options).where("id", query).first();
+      const builder = this.getBuilder(object, options).where("id", query);
+      this.applyTenantScope(builder, object, options);
+      const res = await builder.first();
       return this.formatOutput(object, res) || null;
     }
     if (query && typeof query === "object") {
@@ -156,13 +293,153 @@ var SqlDriver = class {
     } else if (toInsert.id === void 0) {
       toInsert.id = nanoid(DEFAULT_ID_LENGTH);
     }
+    this.auditMissingTenant(object, "create", options);
+    this.injectTenantOnInsert(object, toInsert, options);
+    await this.fillAutoNumberFields(object, toInsert, options);
     const builder = this.getBuilder(object, options);
     const formatted = this.formatInput(object, toInsert);
     const result = await builder.insert(formatted).returning("*");
     return this.formatOutput(object, result[0]);
   }
+  /**
+   * Ensure the sequence-counter table exists. Idempotent and cheap after
+   * the first call (cached via `sequencesTableReady`).
+   */
+  async ensureSequencesTable() {
+    if (this.sequencesTableReady) return;
+    if (this.sequencesTableEnsurePromise) {
+      await this.sequencesTableEnsurePromise;
+      return;
+    }
+    this.sequencesTableEnsurePromise = (async () => {
+      const exists = await this.knex.schema.hasTable(SEQUENCES_TABLE);
+      if (!exists) {
+        try {
+          await this.knex.schema.createTable(SEQUENCES_TABLE, (t) => {
+            t.string("object").notNullable();
+            t.string("tenant_id").notNullable();
+            t.string("field").notNullable();
+            t.bigInteger("last_value").notNullable().defaultTo(0);
+            t.timestamp("updated_at").defaultTo(this.knex.fn.now());
+            t.primary(["object", "tenant_id", "field"]);
+          });
+        } catch (err) {
+          const stillMissing = !await this.knex.schema.hasTable(SEQUENCES_TABLE);
+          if (stillMissing) throw err;
+        }
+      }
+      this.sequencesTableReady = true;
+    })();
+    try {
+      await this.sequencesTableEnsurePromise;
+    } finally {
+      this.sequencesTableEnsurePromise = null;
+    }
+  }
+  /**
+   * Bootstrap helper: scan the data table for the highest numeric suffix
+   * matching `prefix` (optionally scoped to a tenant). Used the first time
+   * a sequence row is created so legacy/seeded data continues monotonically.
+   */
+  async scanMaxNumericTail(queryRunner, tableName, field, prefix, tenantField, tenantId) {
+    const escapedPrefix = prefix.replace(/([\\%_])/g, "\\$1");
+    let builder = queryRunner(tableName).select(field).where(field, "like", `${escapedPrefix}%`).whereNotNull(field);
+    if (tenantField && tenantId !== null) {
+      builder = builder.where(tenantField, tenantId);
+    }
+    const rows = await builder;
+    let maxN = 0;
+    for (const r of rows) {
+      const v = r[field];
+      if (typeof v !== "string") continue;
+      const tail = v.slice(prefix.length);
+      const n = parseInt(tail.replace(/[^0-9]/g, ""), 10);
+      if (Number.isFinite(n) && n > maxN) maxN = n;
+    }
+    return maxN;
+  }
+  /**
+   * Atomically reserve and return the next sequence value for
+   * `(object, tenantId, field)`. Bootstraps from the data-table MAX on
+   * first call so existing seeded records continue monotonically.
+   *
+   * Concurrency:
+   *   - SQLite: a write transaction (`BEGIN IMMEDIATE` via knex) serializes
+   *     all writers; safe in-process. Cross-process SQLite is out of scope.
+   *   - Postgres/MySQL: `SELECT … FOR UPDATE` row lock ensures only one
+   *     transaction reads-modifies-writes at a time. A PK-violation race on
+   *     first insert is retried as an UPDATE.
+   *
+   * Gaps are tolerated by design — a rolled-back insert "burns" a number,
+   * matching standard sequence semantics.
+   */
+  async getNextSequenceValue(object, tableName, field, prefix, tenantField, tenantId, parentTrx) {
+    await this.ensureSequencesTable();
+    const resolvedTenantId = tenantField && tenantId ? String(tenantId) : GLOBAL_TENANT;
+    const key = { object: tableName, tenant_id: resolvedTenantId, field };
+    const runner = parentTrx ?? this.knex;
+    return runner.transaction(async (trx) => {
+      let existing;
+      try {
+        existing = await trx(SEQUENCES_TABLE).where(key).forUpdate().first();
+      } catch {
+        existing = await trx(SEQUENCES_TABLE).where(key).first();
+      }
+      if (!existing) {
+        const seedMax = await this.scanMaxNumericTail(
+          trx,
+          tableName,
+          field,
+          prefix,
+          tenantField,
+          resolvedTenantId === GLOBAL_TENANT ? null : resolvedTenantId
+        );
+        const initial = seedMax + 1;
+        try {
+          await trx(SEQUENCES_TABLE).insert({ ...key, last_value: initial });
+          return initial;
+        } catch (err) {
+          existing = await trx(SEQUENCES_TABLE).where(key).forUpdate().first();
+          if (!existing) throw err;
+        }
+      }
+      const next = Number(existing.last_value) + 1;
+      await trx(SEQUENCES_TABLE).where(key).update({ last_value: next, updated_at: this.knex.fn.now() });
+      return next;
+    });
+  }
+  /**
+   * For each `auto_number` field on the object that the caller did not
+   * provide a value for, reserve the next sequence value scoped to the
+   * record's tenant (or globally if the object has no tenant field) and
+   * render `prefix + zero-padded(value)`.
+   */
+  async fillAutoNumberFields(object, row, options) {
+    const tableName = StorageNameMapping.resolveTableName({ name: object });
+    const cfgs = this.autoNumberFields[tableName] || this.autoNumberFields[object];
+    if (!cfgs || cfgs.length === 0) return;
+    const parentTrx = options?.transaction;
+    for (const cfg of cfgs) {
+      if (row[cfg.name] !== void 0 && row[cfg.name] !== null && row[cfg.name] !== "") continue;
+      const rowTenant = cfg.tenantField ? row[cfg.tenantField] : void 0;
+      const optTenant = options?.tenantId;
+      const tenantId = rowTenant != null && rowTenant !== "" ? String(rowTenant) : optTenant != null && optTenant !== "" ? String(optTenant) : null;
+      const next = await this.getNextSequenceValue(
+        object,
+        tableName,
+        cfg.name,
+        cfg.prefix,
+        cfg.tenantField,
+        tenantId,
+        parentTrx
+      );
+      row[cfg.name] = `${cfg.prefix}${String(next).padStart(cfg.padWidth, "0")}`;
+    }
+  }
   async update(object, id, data, options) {
-    const builder = this.getBuilder(object, options);
+    this.auditMissingTenant(object, "update", options);
+    const builder = this.getBuilder(object, options).where("id", id);
+    this.applyTenantScope(builder, object, options);
     const formatted = this.formatInput(object, data);
     if (this.tablesWithTimestamps.has(object)) {
       if (this.isSqlite) {
@@ -172,8 +449,10 @@ var SqlDriver = class {
         formatted.updated_at = this.knex.fn.now();
       }
     }
-    await builder.where("id", id).update(formatted);
-    const updated = await this.getBuilder(object, options).where("id", id).first();
+    await builder.update(formatted);
+    const readback = this.getBuilder(object, options).where("id", id);
+    this.applyTenantScope(readback, object, options);
+    const updated = await readback.first();
     return this.formatOutput(object, updated) || null;
   }
   async upsert(object, data, conflictKeys, options) {
@@ -184,22 +463,33 @@ var SqlDriver = class {
     } else if (toUpsert.id === void 0) {
       toUpsert.id = nanoid(DEFAULT_ID_LENGTH);
     }
+    this.auditMissingTenant(object, "upsert", options);
+    this.injectTenantOnInsert(object, toUpsert, options);
+    await this.fillAutoNumberFields(object, toUpsert, options);
     const formatted = this.formatInput(object, toUpsert);
     const mergeKeys = conflictKeys && conflictKeys.length > 0 ? conflictKeys : ["id"];
     const builder = this.getBuilder(object, options);
     await builder.insert(formatted).onConflict(mergeKeys).merge();
-    const result = await this.getBuilder(object, options).where("id", toUpsert.id).first();
+    const readback = this.getBuilder(object, options).where("id", toUpsert.id);
+    this.applyTenantScope(readback, object, options);
+    const result = await readback.first();
     return this.formatOutput(object, result) || toUpsert;
   }
   async delete(object, id, options) {
-    const builder = this.getBuilder(object, options);
-    const count = await builder.where("id", id).delete();
+    this.auditMissingTenant(object, "delete", options);
+    const builder = this.getBuilder(object, options).where("id", id);
+    this.applyTenantScope(builder, object, options);
+    const count = await builder.delete();
     return count > 0;
   }
   // ===================================
   // Bulk & Batch Operations
   // ===================================
   async bulkCreate(object, data, options) {
+    this.auditMissingTenant(object, "bulkCreate", options);
+    for (const row of data) {
+      if (row && typeof row === "object") this.injectTenantOnInsert(object, row, options);
+    }
     const builder = this.getBuilder(object, options);
     return await builder.insert(data).returning("*");
   }
@@ -217,23 +507,30 @@ var SqlDriver = class {
     return results;
   }
   async bulkDelete(object, ids, options) {
-    const builder = this.getBuilder(object, options);
-    await builder.whereIn("id", ids).delete();
+    this.auditMissingTenant(object, "bulkDelete", options);
+    const builder = this.getBuilder(object, options).whereIn("id", ids);
+    this.applyTenantScope(builder, object, options);
+    await builder.delete();
   }
   async updateMany(object, query, data, options) {
+    this.auditMissingTenant(object, "updateMany", options);
     const builder = this.getBuilder(object, options);
+    this.applyTenantScope(builder, object, options);
     if (query.where) this.applyFilters(builder, query.where);
     const count = await builder.update(data);
     return count || 0;
   }
   async deleteMany(object, query, options) {
+    this.auditMissingTenant(object, "deleteMany", options);
     const builder = this.getBuilder(object, options);
+    this.applyTenantScope(builder, object, options);
     if (query.where) this.applyFilters(builder, query.where);
     const count = await builder.delete();
     return count || 0;
   }
   async count(object, query, options) {
     const builder = this.getBuilder(object, options);
+    this.applyTenantScope(builder, object, options);
     if (query?.where) {
       this.applyFilters(builder, query.where);
     }
@@ -247,6 +544,22 @@ var SqlDriver = class {
   // ===================================
   // Raw Execution
   // ===================================
+  /**
+   * Run a raw SQL string or knex builder through the underlying knex
+   * connection.
+   *
+   * ⚠️ **Tenant isolation bypass.** Unlike `find`/`update`/`delete` etc.,
+   * raw `execute()` does NOT inject the `organization_id` predicate. The
+   * caller is responsible for either:
+   *   - inlining the tenant filter into the SQL (`WHERE organization_id = ?`),
+   *   - or restricting `execute()` to genuinely global queries
+   *     (schema introspection, sys_* tables that opt out of tenancy).
+   *
+   * Prefer the typed CRUD APIs whenever the operation can be expressed
+   * through them — they handle tenancy, soft-delete, and audit warnings
+   * automatically. See `README.md > Tenant Isolation` for the full bypass
+   * matrix.
+   */
   async execute(command, params, options) {
     if (typeof command !== "string") {
       return command;
@@ -281,13 +594,30 @@ var SqlDriver = class {
   // ===================================
   async aggregate(object, query, options) {
     const builder = this.getBuilder(object, options);
+    this.applyTenantScope(builder, object, options);
     if (query.where) {
       this.applyFilters(builder, query.where);
     }
     if (query.groupBy) {
-      builder.groupBy(query.groupBy);
-      for (const field of query.groupBy) {
-        builder.select(field);
+      for (const g of query.groupBy) {
+        if (typeof g === "string") {
+          builder.groupBy(g);
+          builder.select(g);
+        } else if (g && typeof g === "object" && g.field) {
+          if (g.dateGranularity) {
+            const bucket = this.buildDateBucketExpr(g.field, g.dateGranularity);
+            if (!bucket) {
+              throw new Error(
+                `SqlDriver: dateGranularity '${g.dateGranularity}' not supported on dialect '${this.config.client}'. Engine must fall back to in-memory bucketing.`
+              );
+            }
+            builder.groupByRaw(bucket.sql, bucket.bindings);
+            builder.select(this.knex.raw(`${bucket.sql} as ??`, [...bucket.bindings, g.field]));
+          } else {
+            builder.groupBy(g.field);
+            builder.select(g.field);
+          }
+        }
       }
     }
     const aggregates = query.aggregations || query.aggregate;
@@ -295,10 +625,19 @@ var SqlDriver = class {
       for (const agg of aggregates) {
         const funcName = agg.function || agg.func;
         const rawFunc = this.mapAggregateFunc(funcName);
+        const fieldExpr = agg.field ?? "*";
         if (agg.alias) {
-          builder.select(this.knex.raw(`${rawFunc}(??) as ??`, [agg.field, agg.alias]));
+          if (fieldExpr === "*") {
+            builder.select(this.knex.raw(`${rawFunc}(*) as ??`, [agg.alias]));
+          } else {
+            builder.select(this.knex.raw(`${rawFunc}(??) as ??`, [fieldExpr, agg.alias]));
+          }
         } else {
-          builder.select(this.knex.raw(`${rawFunc}(??)`, [agg.field]));
+          if (fieldExpr === "*") {
+            builder.select(this.knex.raw(`${rawFunc}(*)`));
+          } else {
+            builder.select(this.knex.raw(`${rawFunc}(??)`, [fieldExpr]));
+          }
         }
       }
     }
@@ -409,9 +748,22 @@ var SqlDriver = class {
   async initObjects(objects) {
     await this.ensureDatabaseExists();
     for (const obj of objects) {
-      const tableName = obj.tableName || obj.name;
+      const tableName = StorageNameMapping.resolveTableName(obj);
       const jsonCols = [];
       const booleanCols = [];
+      const autoNumberCols = [];
+      const tenancyDecl = obj?.tenancy;
+      let tenantField = null;
+      if (tenancyDecl && tenancyDecl.enabled !== false && tenancyDecl.tenantField) {
+        const declared = String(tenancyDecl.tenantField);
+        if (obj.fields && Object.prototype.hasOwnProperty.call(obj.fields, declared)) {
+          tenantField = declared;
+        }
+      }
+      if (!tenantField) {
+        const hasOrgField = !!(obj.fields && Object.prototype.hasOwnProperty.call(obj.fields, "organization_id"));
+        tenantField = hasOrgField ? "organization_id" : null;
+      }
       if (obj.fields) {
         for (const [name, field] of Object.entries(obj.fields)) {
           const type = field.type || "string";
@@ -421,10 +773,19 @@ var SqlDriver = class {
           if (type === "boolean") {
             booleanCols.push(name);
           }
+          if (type === "auto_number" || type === "autonumber") {
+            const fmt = typeof field.format === "string" && field.format ? field.format : "{0000}";
+            const m = fmt.match(/\{(0+)\}/);
+            const padWidth = m ? m[1].length : 4;
+            const prefix = m ? fmt.slice(0, m.index ?? 0) : fmt;
+            autoNumberCols.push({ name, format: fmt, prefix, padWidth, tenantField });
+          }
         }
       }
       this.jsonFields[tableName] = jsonCols;
       this.booleanFields[tableName] = booleanCols;
+      this.autoNumberFields[tableName] = autoNumberCols;
+      this.tenantFieldByTable[tableName] = tenantField;
       let exists = await this.knex.schema.hasTable(tableName);
       if (exists) {
         const columnInfo = await this.knex(tableName).columnInfo();
@@ -524,6 +885,80 @@ var SqlDriver = class {
     }
     return builder;
   }
+  /**
+   * Resolve the tenant column for the given object, if any.
+   *
+   * Lookup falls back to both the storage-mapped table name and the raw
+   * object name so callers that pass either form get the same answer.
+   * Returns `null` when the object has no tenant-isolation field.
+   */
+  resolveTenantField(object) {
+    const tableName = StorageNameMapping.resolveTableName({ name: object });
+    const cached = this.tenantFieldByTable[tableName] ?? this.tenantFieldByTable[object];
+    return cached ?? null;
+  }
+  /**
+   * Apply a `WHERE tenant_field = ?` clause to the given query builder
+   * when:
+   *   1. `options.tenantId` is provided by the caller, AND
+   *   2. the object actually has a tenant-isolation field
+   *      (`organization_id` by convention).
+   *
+   * Without a tenantId the call is treated as an unscoped/admin path —
+   * keeps legacy callers, seed scripts, and cross-org tooling working.
+   * This is the single chokepoint for read-side tenant isolation in the
+   * SQL driver; every CRUD method routes through it.
+   */
+  applyTenantScope(builder, object, options) {
+    const tenantId = options?.tenantId;
+    if (tenantId === void 0 || tenantId === null || tenantId === "") return builder;
+    const field = this.resolveTenantField(object);
+    if (!field) return builder;
+    return builder.where(field, String(tenantId));
+  }
+  /**
+   * Auto-inject the tenant column on insert rows when:
+   *   1. `options.tenantId` is provided, AND
+   *   2. the object has a tenant-isolation field, AND
+   *   3. the row does not already set that field.
+   *
+   * Explicit values are never overwritten — admins writing to a specific
+   * tenant via raw row data keep that authority.
+   */
+  injectTenantOnInsert(object, row, options) {
+    const tenantId = options?.tenantId;
+    if (tenantId === void 0 || tenantId === null || tenantId === "") return;
+    const field = this.resolveTenantField(object);
+    if (!field) return;
+    if (row[field] === void 0 || row[field] === null || row[field] === "") {
+      row[field] = String(tenantId);
+    }
+  }
+  /**
+   * Surface writes that target a tenant-scoped object but don't carry a
+   * `tenantId`. These are almost always system / seed / admin paths that
+   * forgot to thread the active session context — easy to miss in code
+   * review and impossible to find after a breach.
+   *
+   * Throttled to one warning per `${object}:${op}` so background workers
+   * don't spam the log. Set `options.bypassTenantAudit = true` (or env
+   * `OS_TENANT_AUDIT=0`) to silence intentionally.
+   */
+  auditMissingTenant(object, op, options) {
+    if (process.env.OS_TENANT_AUDIT === "0") return;
+    if (options?.bypassTenantAudit === true) return;
+    const tenantId = options?.tenantId;
+    if (tenantId !== void 0 && tenantId !== null && tenantId !== "") return;
+    const field = this.resolveTenantField(object);
+    if (!field) return;
+    const key = `${object}:${op}`;
+    if (this.tenantAuditWarned.has(key)) return;
+    this.tenantAuditWarned.add(key);
+    this.logger.warn(
+      `[tenant-audit] ${op} on tenant-scoped object "${object}" without options.tenantId \u2014 writes will not be tenant-isolated. Pass tenantId via ExecutionContext or set bypassTenantAudit:true to silence.`,
+      { object, op, tenantField: field }
+    );
+  }
   // ── Filter helpers ──────────────────────────────────────────────────────────
   applyFilters(builder, filters) {
     if (!filters) return;
@@ -762,6 +1197,7 @@ var SqlDriver = class {
         col = table.float(name);
         break;
       case "auto_number":
+      case "autonumber":
         col = table.string(name);
         break;
       case "formula":
@@ -773,6 +1209,16 @@ var SqlDriver = class {
     if (col) {
       if (field.unique) col.unique();
       if (field.required) col.notNullable();
+      if ((type === "datetime" || type === "date" || type === "time") && typeof field.defaultValue === "string" && /^now\(\)$/i.test(field.defaultValue.trim())) {
+        col.defaultTo(this.knex.fn.now());
+      } else if (field.defaultValue !== void 0 && field.defaultValue !== null) {
+        const dv = field.defaultValue;
+        if (typeof dv === "string" && /^now\(\)$/i.test(dv.trim())) {
+          col.defaultTo(this.knex.fn.now());
+        } else if (typeof dv !== "object") {
+          col.defaultTo(dv);
+        }
+      }
     }
   }
   // ── Database helpers ────────────────────────────────────────────────────────
@@ -846,10 +1292,28 @@ var SqlDriver = class {
   }
   // ── SQLite serialisation ────────────────────────────────────────────────────
   formatInput(object, data) {
-    if (!this.isSqlite) return data;
+    let copy = data;
+    let copied = false;
+    if (data && typeof data === "object") {
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      for (const key of Object.keys(data)) {
+        const v = data[key];
+        if (typeof v === "string" && /^now\(\)$/i.test(v.trim())) {
+          if (!copied) {
+            copy = { ...data };
+            copied = true;
+          }
+          copy[key] = now;
+        }
+      }
+    }
+    if (!this.isSqlite) return copy;
     const fields = this.jsonFields[object];
-    if (!fields || fields.length === 0) return data;
-    const copy = { ...data };
+    if (!fields || fields.length === 0) return copy;
+    if (!copied) {
+      copy = { ...copy };
+      copied = true;
+    }
     for (const field of fields) {
       if (copy[field] !== void 0 && typeof copy[field] === "object" && copy[field] !== null) {
         copy[field] = JSON.stringify(copy[field]);