@objectstack/objectql 9.9.1 → 9.10.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;
@@ -2664,6 +2680,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;
@@ -2664,6 +2680,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,
@@ -7084,7 +7100,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(
@@ -9507,6 +9523,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;
   }