@objectstack/objectql 9.9.1 → 9.11.0

package/dist/index.d.mts

@@ -141,6 +141,22 @@ interface SchemaRegistryOptions {
  *     timestamps; the `*_by` lookups are filled by the runtime when an
  *     authenticated session is present (NULL otherwise — e.g. seeded
  *     rows).
+ *   - `owner_id` — canonical, *reassignable* record owner (lookup to
+ *     `sys_user`). Auto-provisioned by DEFAULT on user-authored business
+ *     objects so ownership is correct-by-default for AI/human authors who
+ *     would otherwise forget to declare it (or reinvent a custom `owner`
+ *     lookup the platform can't see). Once present, the existing machinery
+ *     engages automatically: SecurityPlugin auto-stamps it to the acting
+ *     user on insert (step 3.5), owner-scoped RLS / "My" views / owner
+ *     reports key off it, and the first-admin bootstrap hands seeded rows
+ *     (owner_id NULL) to the promoted admin. Unlike `created_by` it is
+ *     editable (`readonly: false`) — ownership transfers; provenance does
+ *     not. Excluded for `managedBy` / `sys_*` tables and any object that
+ *     opts out via `ownership: 'org' | 'none'` (Dataverse-style: a
+ *     catalog/junction table that has no per-record owner). Forgetting the
+ *     opt-out is harmless (a spare nullable column), whereas forgetting to
+ *     ADD ownership — the failure mode we are eliminating — silently breaks
+ *     every owner-keyed feature.
  */
 declare function applySystemFields(schema: ServiceObject, opts: {
     multiTenant: boolean;
@@ -612,7 +628,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                 } | {
                     language: "js";
                     source: string;
-                    capabilities: ("log" | "api.read" | "api.write" | "crypto.uuid" | "crypto.hash")[];
+                    capabilities: ("log" | "api.read" | "api.write" | "api.transaction" | "crypto.uuid" | "crypto.hash")[];
                     timeoutMs?: number | undefined;
                     memoryMb?: number | undefined;
                 } | undefined;
@@ -2209,15 +2225,22 @@ declare class ObjectQL implements IDataEngine {
      * owns the value, not the client.
      *
      * In the fallback path the next value is `max(existing) + 1`, seeded once per
-     * `object.field` from the store then incremented in memory (monotonic within
-     * the process, resilient to deletions). `autonumberFormat` is honored, e.g.
-     * `CASE-{0000}` → `CASE-0042`. NOTE: this in-memory seeding is single-instance.
+     * `object.field.<scope>` from the store then incremented in memory (monotonic
+     * within the process, resilient to deletions). The shared `autonumberFormat`
+     * renderer is honored end-to-end, so date tokens (`AD{YYYYMMDD}{0000}`), field
+     * interpolation (`{island_zone}{000}`) and per-scope reset behave identically
+     * to the SQL driver's persistent sequence (#1603). NOTE: this in-memory seeding
+     * is single-instance.
      */
     private applyAutonumbers;
-    /** Seed the autonumber counter from the current max numeric value in store. */
+    /**
+     * Seed the autonumber counter from the current max in store, scoped to
+     * `prefix`. With a non-empty prefix (date/field formats) only rows in the
+     * same scope count, and the counter is the digit-run immediately after the
+     * prefix; with an empty prefix (legacy fixed-prefix formats) the last digit
+     * run of the whole value is used, preserving the original behaviour.
+     */
     private seedAutonumber;
-    /** Apply an autonumber format like `CASE-{0000}`; default to the bare number. */
-    private formatAutonumber;
     /**
      * Register contribution (Manifest)
      *
@@ -2664,6 +2687,38 @@ declare class ScopedContext {
      * does not support transactions.
      */
     transaction(callback: (trxCtx: ScopedContext) => Promise<any>): Promise<any>;
+    /**
+     * Resolve the default driver, if it exposes transaction primitives.
+     * Shared by {@link transaction} and the discrete begin/commit/rollback trio.
+     */
+    private txDriver;
+    /**
+     * Discrete transaction primitives — `begin` / `commit` / `rollback` as three
+     * separate calls, in contrast to {@link transaction}'s single-callback form.
+     *
+     * This trio exists for callers that cannot keep a JS closure on the stack for
+     * the lifetime of the transaction — chiefly the sandbox runner, where the
+     * hook/action body's `ctx.api.transaction(fn)` is driven across many host
+     * event-loop turns via deferred promises. Across those `setImmediate`
+     * boundaries the engine's ambient `txStore` (AsyncLocalStorage) does NOT
+     * survive, so the transaction handle is threaded **explicitly**: `begin`
+     * returns a child ScopedContext carrying `transaction: trx` in its execution
+     * context, and `resolveTx` honors that explicit handle ahead of the ambient
+     * store. Every `object(...)` op on the returned context therefore reuses the
+     * one connection without relying on ALS.
+     *
+     * Returns `null` when the driver has no transaction support — the caller then
+     * runs non-transactionally against `this` (same graceful degrade as
+     * {@link transaction}).
+     */
+    beginTransaction(): Promise<{
+        ctx: ScopedContext;
+        handle: unknown;
+    } | null>;
+    /** Commit a handle obtained from {@link beginTransaction}. */
+    commitTransaction(handle: unknown): Promise<void>;
+    /** Roll back a handle obtained from {@link beginTransaction}. */
+    rollbackTransaction(handle: unknown): Promise<void>;
     get userId(): string | undefined;
     get tenantId(): string | undefined;
     /** Alias for tenantId — matches ObjectQLContext.spaceId convention */

package/dist/index.d.ts

@@ -141,6 +141,22 @@ interface SchemaRegistryOptions {
  *     timestamps; the `*_by` lookups are filled by the runtime when an
  *     authenticated session is present (NULL otherwise — e.g. seeded
  *     rows).
+ *   - `owner_id` — canonical, *reassignable* record owner (lookup to
+ *     `sys_user`). Auto-provisioned by DEFAULT on user-authored business
+ *     objects so ownership is correct-by-default for AI/human authors who
+ *     would otherwise forget to declare it (or reinvent a custom `owner`
+ *     lookup the platform can't see). Once present, the existing machinery
+ *     engages automatically: SecurityPlugin auto-stamps it to the acting
+ *     user on insert (step 3.5), owner-scoped RLS / "My" views / owner
+ *     reports key off it, and the first-admin bootstrap hands seeded rows
+ *     (owner_id NULL) to the promoted admin. Unlike `created_by` it is
+ *     editable (`readonly: false`) — ownership transfers; provenance does
+ *     not. Excluded for `managedBy` / `sys_*` tables and any object that
+ *     opts out via `ownership: 'org' | 'none'` (Dataverse-style: a
+ *     catalog/junction table that has no per-record owner). Forgetting the
+ *     opt-out is harmless (a spare nullable column), whereas forgetting to
+ *     ADD ownership — the failure mode we are eliminating — silently breaks
+ *     every owner-keyed feature.
  */
 declare function applySystemFields(schema: ServiceObject, opts: {
     multiTenant: boolean;
@@ -612,7 +628,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                 } | {
                     language: "js";
                     source: string;
-                    capabilities: ("log" | "api.read" | "api.write" | "crypto.uuid" | "crypto.hash")[];
+                    capabilities: ("log" | "api.read" | "api.write" | "api.transaction" | "crypto.uuid" | "crypto.hash")[];
                     timeoutMs?: number | undefined;
                     memoryMb?: number | undefined;
                 } | undefined;
@@ -2209,15 +2225,22 @@ declare class ObjectQL implements IDataEngine {
      * owns the value, not the client.
      *
      * In the fallback path the next value is `max(existing) + 1`, seeded once per
-     * `object.field` from the store then incremented in memory (monotonic within
-     * the process, resilient to deletions). `autonumberFormat` is honored, e.g.
-     * `CASE-{0000}` → `CASE-0042`. NOTE: this in-memory seeding is single-instance.
+     * `object.field.<scope>` from the store then incremented in memory (monotonic
+     * within the process, resilient to deletions). The shared `autonumberFormat`
+     * renderer is honored end-to-end, so date tokens (`AD{YYYYMMDD}{0000}`), field
+     * interpolation (`{island_zone}{000}`) and per-scope reset behave identically
+     * to the SQL driver's persistent sequence (#1603). NOTE: this in-memory seeding
+     * is single-instance.
      */
     private applyAutonumbers;
-    /** Seed the autonumber counter from the current max numeric value in store. */
+    /**
+     * Seed the autonumber counter from the current max in store, scoped to
+     * `prefix`. With a non-empty prefix (date/field formats) only rows in the
+     * same scope count, and the counter is the digit-run immediately after the
+     * prefix; with an empty prefix (legacy fixed-prefix formats) the last digit
+     * run of the whole value is used, preserving the original behaviour.
+     */
     private seedAutonumber;
-    /** Apply an autonumber format like `CASE-{0000}`; default to the bare number. */
-    private formatAutonumber;
     /**
      * Register contribution (Manifest)
      *
@@ -2664,6 +2687,38 @@ declare class ScopedContext {
      * does not support transactions.
      */
     transaction(callback: (trxCtx: ScopedContext) => Promise<any>): Promise<any>;
+    /**
+     * Resolve the default driver, if it exposes transaction primitives.
+     * Shared by {@link transaction} and the discrete begin/commit/rollback trio.
+     */
+    private txDriver;
+    /**
+     * Discrete transaction primitives — `begin` / `commit` / `rollback` as three
+     * separate calls, in contrast to {@link transaction}'s single-callback form.
+     *
+     * This trio exists for callers that cannot keep a JS closure on the stack for
+     * the lifetime of the transaction — chiefly the sandbox runner, where the
+     * hook/action body's `ctx.api.transaction(fn)` is driven across many host
+     * event-loop turns via deferred promises. Across those `setImmediate`
+     * boundaries the engine's ambient `txStore` (AsyncLocalStorage) does NOT
+     * survive, so the transaction handle is threaded **explicitly**: `begin`
+     * returns a child ScopedContext carrying `transaction: trx` in its execution
+     * context, and `resolveTx` honors that explicit handle ahead of the ambient
+     * store. Every `object(...)` op on the returned context therefore reuses the
+     * one connection without relying on ALS.
+     *
+     * Returns `null` when the driver has no transaction support — the caller then
+     * runs non-transactionally against `this` (same graceful degrade as
+     * {@link transaction}).
+     */
+    beginTransaction(): Promise<{
+        ctx: ScopedContext;
+        handle: unknown;
+    } | null>;
+    /** Commit a handle obtained from {@link beginTransaction}. */
+    commitTransaction(handle: unknown): Promise<void>;
+    /** Roll back a handle obtained from {@link beginTransaction}. */
+    rollbackTransaction(handle: unknown): Promise<void>;
     get userId(): string | undefined;
     get tenantId(): string | undefined;
     /** Alias for tenantId — matches ObjectQLContext.spaceId convention */

package/dist/index.js

@@ -163,7 +163,10 @@ var init_seed_loader = __esm({
         const seedIdentity = config.identity;
         const baseEvalCtx = {
           now: seedNow,
-          user: seedIdentity?.user,
+          // `id: null` is a legitimate seed-time state (the owning admin does not
+          // exist yet) that the formula EvalContext's `user.id: string` type does
+          // not yet model — cast the fallback so `os.user.id` evaluates to null.
+          user: seedIdentity?.user ?? { id: null },
           // Fall back to the per-tenant organizationId so `os.org.id` resolves
           // during per-org replay even without an explicit identity.org.
           org: seedIdentity?.org ?? (config.organizationId ? { id: config.organizationId } : void 0),
@@ -183,7 +186,7 @@ var init_seed_loader = __esm({
               targetField: "(expression)",
               attemptedValue: dataset.records[i],
               recordIndex: i,
-              message: `Cannot resolve dynamic seed values for ${objectName} record #${i}: ${seedResult.error.message}. Records using cel\`os.user.id\` / cel\`os.org.id\` require a seed identity \u2014 ensure a system/admin user exists before seeding (see SeedLoaderConfig.identity).`
+              message: `Cannot resolve dynamic seed values for ${objectName} record #${i}: ${seedResult.error.message}. \`os.user.id\` resolves to null at seed time (the owning admin does not exist yet) and owner-style fields are assigned by the first-admin handoff \u2014 so a required, non-owner field must not depend on it. Provide a literal value or make the field optional.`
             };
             errors.push(error);
             allErrors.push(error);
@@ -904,6 +907,8 @@ function applySystemFields(schema, opts) {
   const tenancyDisabled = schema.tenancy?.enabled === false;
   const wantTenant = sf?.tenant !== false && !tenancyDisabled;
   const wantAudit = sf?.audit !== false;
+  const ownership = schema.ownership;
+  const wantOwner = ownership !== "org" && ownership !== "none" && !schema.managedBy && !schema.name.startsWith("sys_");
   const additions = {};
   if (wantTenant && !schema.fields?.organization_id) {
     additions.organization_id = {
@@ -962,6 +967,17 @@ function applySystemFields(schema, opts) {
       };
     }
   }
+  if (wantOwner && !schema.fields?.owner_id) {
+    additions.owner_id = {
+      type: "lookup",
+      reference: "sys_user",
+      label: "Owner",
+      required: false,
+      readonly: false,
+      system: true,
+      description: "Record owner (auto-stamped to the creating user on insert; reassignable). Drives owner-scoped views, reports and notifications."
+    };
+  }
   if (Object.keys(additions).length === 0) return schema;
   return {
     ...schema,
@@ -6176,6 +6192,7 @@ var ObjectStackProtocolImplementation = _ObjectStackProtocolImplementation;
 
 // src/engine.ts
 var import_node_async_hooks = require("async_hooks");
+var import_data4 = require("@objectstack/spec/data");
 var import_kernel6 = require("@objectstack/spec/kernel");
 var import_core2 = require("@objectstack/core");
 var import_system2 = require("@objectstack/spec/system");
@@ -7084,7 +7101,7 @@ function aggregateBucket(rows, aggregations) {
     const alias = agg.alias;
     const fn = agg.function;
     if (fn === "count") {
-      if (!agg.field) {
+      if (!agg.field || agg.field === "*") {
         out[alias] = rows.length;
       } else {
         out[alias] = rows.reduce(
@@ -7601,8 +7618,9 @@ var _ObjectQL = class _ObjectQL {
     const tx = execCtx?.transaction !== void 0 ? execCtx.transaction : this.txStore.getStore()?.transaction;
     const hasTx = tx !== void 0;
     const hasTenant = execCtx?.tenantId !== void 0;
+    const hasTz = execCtx?.timezone !== void 0;
     const isSystem = execCtx?.isSystem === true;
-    if (!hasTx && !hasTenant && !isSystem) return base;
+    if (!hasTx && !hasTenant && !isSystem && !hasTz) return base;
     const opts = base && typeof base === "object" ? { ...base } : {};
     if (hasTx && opts.transaction === void 0) {
       opts.transaction = tx;
@@ -7610,6 +7628,9 @@ var _ObjectQL = class _ObjectQL {
     if (hasTenant && opts.tenantId === void 0) {
       opts.tenantId = execCtx.tenantId;
     }
+    if (hasTz && opts.timezone === void 0) {
+      opts.timezone = execCtx.timezone;
+    }
     if (isSystem && opts.bypassTenantAudit === void 0) {
       opts.bypassTenantAudit = true;
     }
@@ -7683,29 +7704,48 @@ var _ObjectQL = class _ObjectQL {
    * owns the value, not the client.
    *
    * In the fallback path the next value is `max(existing) + 1`, seeded once per
-   * `object.field` from the store then incremented in memory (monotonic within
-   * the process, resilient to deletions). `autonumberFormat` is honored, e.g.
-   * `CASE-{0000}` → `CASE-0042`. NOTE: this in-memory seeding is single-instance.
+   * `object.field.<scope>` from the store then incremented in memory (monotonic
+   * within the process, resilient to deletions). The shared `autonumberFormat`
+   * renderer is honored end-to-end, so date tokens (`AD{YYYYMMDD}{0000}`), field
+   * interpolation (`{island_zone}{000}`) and per-scope reset behave identically
+   * to the SQL driver's persistent sequence (#1603). NOTE: this in-memory seeding
+   * is single-instance.
    */
   async applyAutonumbers(object, record, execCtx, driverOwnsAutonumber) {
     if (driverOwnsAutonumber) return;
     const fields = this.getSchema(object)?.fields;
     if (!fields || typeof fields !== "object" || Array.isArray(fields)) return;
+    const now = /* @__PURE__ */ new Date();
+    const timezone = execCtx?.timezone;
     for (const [name, def] of Object.entries(fields)) {
       if (def?.type !== "autonumber") continue;
       const current = record[name];
       if (current != null && current !== "") continue;
-      const key = `${object}.${name}`;
-      let next = this.autonumberCounters.get(key);
-      if (next == null) next = await this.seedAutonumber(object, name, execCtx);
-      next += 1;
-      this.autonumberCounters.set(key, next);
       const fmt = def.autonumberFormat ?? def.format;
-      record[name] = this.formatAutonumber(fmt, next);
+      const tokens = (0, import_data4.parseAutonumberFormat)(typeof fmt === "string" ? fmt : "");
+      const missing = (0, import_data4.missingFieldValues)(tokens, record);
+      if (missing.length > 0) {
+        throw new Error(
+          `Cannot generate autonumber "${object}.${name}" (format "${fmt}"): referenced field(s) [${missing.join(", ")}] are empty on the record. Fields interpolated into an autonumber format must be set before the record is created.`
+        );
+      }
+      const probe = (0, import_data4.renderAutonumber)({ tokens, seq: 0, record, now, timezone });
+      const counterKey = `${object}.${name}.${probe.scope}`;
+      let next = this.autonumberCounters.get(counterKey);
+      if (next == null) next = await this.seedAutonumber(object, name, probe.prefix, execCtx);
+      next += 1;
+      this.autonumberCounters.set(counterKey, next);
+      record[name] = (0, import_data4.renderAutonumber)({ tokens, seq: next, record, now, timezone }).value;
     }
   }
-  /** Seed the autonumber counter from the current max numeric value in store. */
-  async seedAutonumber(object, field, execCtx) {
+  /**
+   * Seed the autonumber counter from the current max in store, scoped to
+   * `prefix`. With a non-empty prefix (date/field formats) only rows in the
+   * same scope count, and the counter is the digit-run immediately after the
+   * prefix; with an empty prefix (legacy fixed-prefix formats) the last digit
+   * run of the whole value is used, preserving the original behaviour.
+   */
+  async seedAutonumber(object, field, prefix, execCtx) {
     try {
       const rows = await this.find(object, {
         select: ["id", field],
@@ -7716,22 +7756,24 @@ var _ObjectQL = class _ObjectQL {
       for (const r of rows || []) {
         const v = r?.[field];
         if (v == null) continue;
-        const m = String(v).match(/(\d+)(?!.*\d)/);
-        if (m) max = Math.max(max, parseInt(m[1], 10) || 0);
+        const s = String(v);
+        if (prefix && !s.startsWith(prefix)) continue;
+        const tail = prefix ? s.slice(prefix.length) : s;
+        let digits;
+        if (prefix) {
+          const head = tail.match(/^\d+/);
+          digits = head ? head[0] : void 0;
+        } else {
+          const runs = tail.match(/\d+/g);
+          digits = runs ? runs[runs.length - 1] : void 0;
+        }
+        if (digits) max = Math.max(max, parseInt(digits, 10) || 0);
       }
       return max;
     } catch {
       return 0;
     }
   }
-  /** Apply an autonumber format like `CASE-{0000}`; default to the bare number. */
-  formatAutonumber(format, value) {
-    if (!format) return String(value);
-    const m = format.match(/\{(0+)\}/);
-    if (!m) return format.includes("{0}") ? format.replace("{0}", String(value)) : `${format}${value}`;
-    const padded = String(value).padStart(m[1].length, "0");
-    return format.replace(m[0], padded);
-  }
   /**
    * Register contribution (Manifest)
    * 
@@ -9507,6 +9549,58 @@ var ScopedContext = class _ScopedContext {
       throw error;
     }
   }
+  /**
+   * Resolve the default driver, if it exposes transaction primitives.
+   * Shared by {@link transaction} and the discrete begin/commit/rollback trio.
+   */
+  txDriver() {
+    const engine = this.engine;
+    const driver = engine.defaultDriver ? engine.drivers?.get(engine.defaultDriver) : void 0;
+    return driver?.beginTransaction ? driver : void 0;
+  }
+  /**
+   * Discrete transaction primitives — `begin` / `commit` / `rollback` as three
+   * separate calls, in contrast to {@link transaction}'s single-callback form.
+   *
+   * This trio exists for callers that cannot keep a JS closure on the stack for
+   * the lifetime of the transaction — chiefly the sandbox runner, where the
+   * hook/action body's `ctx.api.transaction(fn)` is driven across many host
+   * event-loop turns via deferred promises. Across those `setImmediate`
+   * boundaries the engine's ambient `txStore` (AsyncLocalStorage) does NOT
+   * survive, so the transaction handle is threaded **explicitly**: `begin`
+   * returns a child ScopedContext carrying `transaction: trx` in its execution
+   * context, and `resolveTx` honors that explicit handle ahead of the ambient
+   * store. Every `object(...)` op on the returned context therefore reuses the
+   * one connection without relying on ALS.
+   *
+   * Returns `null` when the driver has no transaction support — the caller then
+   * runs non-transactionally against `this` (same graceful degrade as
+   * {@link transaction}).
+   */
+  async beginTransaction() {
+    const driver = this.txDriver();
+    if (!driver) return null;
+    const trx = await driver.beginTransaction();
+    const ctx = new _ScopedContext(
+      { ...this.executionContext, transaction: trx },
+      this.engine
+    );
+    return { ctx, handle: trx };
+  }
+  /** Commit a handle obtained from {@link beginTransaction}. */
+  async commitTransaction(handle) {
+    const driver = this.txDriver();
+    if (!driver) return;
+    if (driver.commit) await driver.commit(handle);
+    else if (driver.commitTransaction) await driver.commitTransaction(handle);
+  }
+  /** Roll back a handle obtained from {@link beginTransaction}. */
+  async rollbackTransaction(handle) {
+    const driver = this.txDriver();
+    if (!driver) return;
+    if (driver.rollback) await driver.rollback(handle);
+    else if (driver.rollbackTransaction) await driver.rollbackTransaction(handle);
+  }
   get userId() {
     return this.executionContext.userId;
   }