velocious 1.0.568 → 1.0.570

package/README.md

@@ -34,6 +34,7 @@
 * In-process driver schema metadata caching (see [docs/schema-metadata-cache.md](docs/schema-metadata-cache.md))
 * Planned local-first shared-resource sync architecture (see [docs/offline-sync.md](docs/offline-sync.md))
 * Selective named database connection checkouts, bounded pool waits, and debugging held connections (see [docs/database-connections.md](docs/database-connections.md))
+* Explicit singular-database operation transactions whose model scopes preserve ownership through records, relationships, lifecycle work, nested savepoints, pre-commit guards, and commit callbacks (see [docs/operation-scoped-transactions.md](docs/operation-scoped-transactions.md))
 * AbortSignal-driven MySQL/MariaDB query cancellation for raw, model, and cross-tenant aggregate queries (see [docs/database-query-cancellation.md](docs/database-query-cancellation.md))
 * Optional built-in debug endpoint for inspecting server and database connection state (see [docs/debug-endpoint.md](docs/debug-endpoint.md))
 * Optional built-in API manifest endpoint describing every registered frontend-model resource as human- and machine-readable JSON (see [docs/api-manifest-endpoint.md](docs/api-manifest-endpoint.md))
@@ -51,6 +52,35 @@ npx velocious init
 
 By default, Velocious looks for your configuration in `src/config/configuration.js`. If you keep the configuration elsewhere, make sure your app imports it early and calls `configuration.setCurrent()`.
 
+# Operation-scoped transactions
+
+Use `configuration.withTransaction` for an atomic unit of model work on one database:
+
+```js
+await configuration.withTransaction({databaseIdentifier: "default", name: "accept ticket"}, async (operation) => {
+  const ticket = await operation.forModel(Ticket).find(ticketId)
+
+  ticket.setAccepted(true)
+  await ticket.save()
+
+  await operation.beforeCommit(async ({operation: guardedOperation}) => {
+    const currentTicket = await guardedOperation
+      .forModel(Ticket)
+      .findByOrFail({id: ticketId})
+
+    if (!currentTicket.acceptanceStillOwnedBy(workerId)) {
+      throw new Error("Ticket acceptance ownership changed")
+    }
+  })
+
+  await operation.afterCommit(async () => {
+    await publishAcceptedTicket(ticket.id())
+  })
+})
+```
+
+Use operation-bound model scopes and their loaded records throughout the callback. `operation.beforeCommit` runs a final operation-owned guard after callback success but before outer commit or nested savepoint release; a rejection rolls back that frame. `operation.transaction` adds a nested savepoint, and `operation.connection()` is the deliberate escape hatch for owned raw SQL. Cross-database models, same-identifier tenant switches to another physical database, and operation handles used after the callback are rejected. On shared SQLite/SQL.js pools, unrelated work waits for the operation lease, while admission during an already-open ordinary transaction is rejected. See [operation-scoped transactions](docs/operation-scoped-transactions.md) for guard, pool, after-commit failure, and migration semantics.
+
 # Development
 
 When working on Velocious itself, npm scripts are cross-platform (Windows `cmd`/PowerShell and POSIX shells):

package/build/configuration.js

@@ -16,6 +16,7 @@ import {digg} from "diggerize"
 import gettextConfig from "gettext-universal/build/src/config.js"
 import translate from "gettext-universal/build/src/translate.js"
 import Ability from "./authorization/ability.js"
+import DatabaseOperation from "./database/operation.js"
 import {initializeAuditedModelRelationships} from "./database/record/auditing.js"
 import EventEmitter from "./utils/event-emitter.js"
 import VelociousWebsocketChannelSubscribers from "./http-server/websocket-channel-subscribers.js"
@@ -2896,6 +2897,41 @@ export default class VelociousConfiguration {
     })
   }
 
+  /**
+   * Runs explicit model work in a transaction pinned to one database connection.
+   * @template T
+   * @param {{databaseIdentifier: string, name?: string}} options - Operation options.
+   * @param {(operation: DatabaseOperation) => Promise<T>} callback - Operation callback.
+   * @returns {Promise<T>} - Resolves with the callback result.
+   */
+  async withTransaction({databaseIdentifier, name = "Configuration.withTransaction", ...restArgs}, callback) {
+    restArgsError(restArgs)
+
+    if (!databaseIdentifier) throw new Error("Configuration.withTransaction requires a databaseIdentifier")
+    if (typeof callback != "function") throw new Error("Configuration.withTransaction requires a callback")
+    if (!this.getDatabaseIdentifiers().includes(databaseIdentifier)) {
+      throw new Error(`Unknown or inactive database identifier: ${databaseIdentifier}`)
+    }
+
+    const pool = this.getDatabasePool(databaseIdentifier)
+
+    return await pool.withOperationConnection({name}, async (connection, owner) => {
+      const operation = new DatabaseOperation({
+        configuration: this,
+        configurationReuseKey: pool.getConnectionConfigurationReuseKey(connection),
+        connection,
+        databaseIdentifier,
+        owner
+      })
+
+      try {
+        return await operation.transaction(async () => await callback(operation))
+      } finally {
+        operation.complete()
+      }
+    })
+  }
+
   /**
    * Runs callback with database connections for the requested identifiers.
    * @template T