velocious 1.0.643 → 1.0.645

package/README.md

@@ -3,7 +3,7 @@
 * Concurrent multi threadded web server
 * Database framework with familiar MVC concepts
 * Database models with migrations and validations
-* Database models that work almost the same in frontend and backend
+* Database models that work almost the same in frontend and backend, including online CRUD for [composite primary keys](docs/composite-primary-keys.md)
 * Connection-scoped advisory locks with automatic cleanup before pooled connections are reused or closed (see [docs/advisory-locks.md](docs/advisory-locks.md))
 * Built-in record auditing for model lifecycle changes (see [docs/auditing.md](docs/auditing.md))
 * Declarative state machines for models, with typed event methods generated into the base model (see [docs/state-machine.md](docs/state-machine.md))
@@ -178,10 +178,10 @@ Baselines are generated against a fresh checkout (no generated dummy `configurat
 # Testing
 
 Application tests may import the testing DSL from the independent public package.
-`@velocious/testing` `0.0.1` uses one compatible default registry across installed copies,
-and the framework runner discovers these declarations while retaining its database,
-request, retry, profiling, and cleanup behavior. The existing Velocious facade remains
-supported.
+`@velocious/testing` `0.0.9` is the declaration and execution engine. Compatible
+installed copies share one protocol-1/schema-3 default registry. Velocious adapts each
+package-owned attempt with its database, request, profiling, and cleanup behavior; the
+existing Velocious facade exports the same declaration DSL and remains supported.
 
 ```js
 import {describe, expect, it} from "@velocious/testing"
@@ -713,6 +713,9 @@ User.hasOneAttachment("profilePicture", {
 `db:migrate` provisions the framework-owned attachment table before runtime
 attachment work begins. See [Backend record attachments](docs/attachments.md)
 for the complete input, storage-driver, lifecycle, and path-security contracts.
+Offline-capable clients can apply synchronized attachment descriptors through
+the platform-neutral [Synchronized asset cache](docs/synchronized-assets.md),
+while Expo and web packages own their respective byte-storage adapters.
 
 You can also pass a driver class or instance directly on the attachment:
 
@@ -841,8 +844,14 @@ The optional model-level `sync` block is client-safe policy metadata for asset
 cache adapters. It distinguishes eager/on-demand fetching,
 durable/evictable retention, and optional/required offline availability.
 Required offline assets must be durable. Backend driver configuration never
-appears in generated frontend models or API manifests.
-Attachment metadata is exposed through the built-in `VelociousAttachment` frontend model with safe fields only: `id`, `recordType`, `recordId`, `name`, `position`, `filename`, `contentType`, `byteSize`, `createdAt`, and `updatedAt`. Storage internals such as `driver`, `storageKey`, and `contentBase64` remain hidden and non-queryable. Direct metadata queries require owner filters: `recordType`, `recordId`, and `name`.
+appears in generated frontend models or API manifests. A descriptor ID keeps
+its digest, byte size, and content type immutably. Cache descriptors that share
+a digest must agree on byte size and content type, and eager synchronization
+attempts each shared digest only once per reconciliation. On-demand resolution
+rechecks the backing blob after cleanup and returns `null` instead of a stale
+local URI when concurrent eviction removed it. Cleanup deferred by an active
+cached resolution runs again after that digest's final guard releases.
+Attachment metadata is exposed through the built-in `VelociousAttachment` frontend model with safe fields only: `id`, `recordType`, `recordId`, `name`, `position`, `filename`, `contentType`, `byteSize`, `createdAt`, and `updatedAt`. Storage internals such as `driver`, `storageKey`, and `contentBase64` remain hidden and non-queryable. Metadata collection queries require owner filters: `resourceName`, `recordType`, `recordId`, and `name`. Composite `recordId` values retain the complete canonical tuple without a 255-character limit, and key-changing saves rekey attachment ownership in the record transaction. `VelociousAttachment.find(id)` uses the member endpoint and authorizes against configured resource aliases backed by the attachment owner type.
 
 When your frontend app calls a backend on another host/port (or under a path prefix), configure transport once:
 
@@ -2237,8 +2246,10 @@ If you are using Velocious for an app, Velocious has a built-in testing framewor
 npx velocious test
 ```
 
-Test declarations can be imported from `@velocious/testing`; the legacy
-`velocious/build/src/testing/test.js` facade remains supported.
+Test declarations can be imported from `@velocious/testing`; the compatibility
+`velocious/build/src/testing/test.js` facade uses the same package registry and remains
+supported. Under Velocious, ordinary callbacks receive `testArgs`, while `it.each`
+callbacks receive their row arguments followed by `testArgs`.
 
 If you are developing on Velocious, you can run the tests with:
 
@@ -2790,7 +2801,7 @@ backgroundJobs: {
 }
 ```
 
-A job with no queue runs on `"default"`; a queue with no cap is unlimited. Caps are enforced through the durable per-key concurrency mechanism (the reserved `queue:<name>` key) and hold regardless of how many worker processes run. Changing a cap and rebuilding durable active counts happen only when `background-jobs-main` starts (serialized across processes with a database advisory lock and logged with database identifier/duration); `db:migrate`, `db:tenants:*`, and routine store/application initialization with an intact jobs table never adopt queued jobs or rebuild global concurrency counts. If schema repair must recreate a missing `background_jobs` table while the migration marker and concurrency table survive, it resets the now-orphaned active counts against that newly empty table. Scheduled jobs honor a job's `static queue` too.
+A job with no queue runs on `"default"`; a queue with no cap is unlimited. Caps are enforced through the durable per-key concurrency mechanism (the reserved `queue:<name>` key) and hold regardless of how many worker processes run. Queue-policy changes are adopted by queued backlog rows when `background-jobs-main` starts; already handed-off jobs drain under their original policy. If they return, reschedule, or retry, the reporting generation releases the original reservation without changing shared policy, and the active generation applies its current queue policy immediately before the next handoff and sends that committed policy to the worker; explicit concurrency remains unchanged. Handoff persistence is fenced against concurrent policy changes. Startup also rebuilds durable active counts under a database advisory lock. The active main then checks those counts every minute, performs no counter writes while they are exact, repairs only locked mismatches, logs a bounded structured repair summary, and immediately retries dispatch so stale capacity cannot require a restart. `db:migrate`, `db:tenants:*`, and routine store/application initialization with an intact jobs table never adopt queued jobs or rebuild global concurrency counts. If schema repair must recreate a missing `background_jobs` table while the migration marker and concurrency table survive, it resets the now-orphaned active counts against that newly empty table. Scheduled jobs honor a job's `static queue` too.
 
 Set `priority` (default `0`) to dispatch a queue ahead of lower-priority ones regardless of enqueue order, so a small time-critical queue is never starved by a flood of low-priority work sharing a worker pool. Unlike Sidekiq's strict queue ordering, priority composes with the caps: a higher-priority queue already at its `maxConcurrent` is skipped and dispatch falls through to the next eligible job. See [docs/background-jobs.md](docs/background-jobs.md#queues-per-queue-concurrency-caps).
 

package/build/authorization/ability.js

@@ -189,9 +189,10 @@ export default class VelociousAuthorizationAbility {
    * @param {string} args.action - Requested action.
    * @param {typeof import("../database/record/index.js").default} args.modelClass - Model class.
    * @param {import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>} args.query - Query.
+   * @param {() => import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>} [args.ruleQueryFactory] - Optional factory for the queries that evaluate individual conditional rules.
    * @returns {import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>} - Authorized query.
    */
-  applyToQuery({action, modelClass, query}) {
+  applyToQuery({action, modelClass, query, ruleQueryFactory}) {
     this.loadAbilitiesForModelClass(modelClass)
 
     const applicableRules = this.rulesFor({action, modelClass})
@@ -203,18 +204,18 @@ export default class VelociousAuthorizationAbility {
     }
 
     if (allowRules.some((rule) => !rule.conditions)) {
-      this.applyDenyRules({action, denyRules, modelClass, query})
+      this.applyDenyRules({action, denyRules, modelClass, query, ruleQueryFactory})
       return query
     }
 
-    const allowSqlParts = this.conditionSqlParts({action, modelClass, query, rules: allowRules})
+    const allowSqlParts = this.conditionSqlParts({action, modelClass, query, ruleQueryFactory, rules: allowRules})
 
     if (allowSqlParts.length === 0) {
       return query.where("1=0")
     }
 
     query.where(`(${allowSqlParts.join(" OR ")})`)
-    this.applyDenyRules({action, denyRules, modelClass, query})
+    this.applyDenyRules({action, denyRules, modelClass, query, ruleQueryFactory})
 
     return query
   }
@@ -240,19 +241,20 @@ export default class VelociousAuthorizationAbility {
    * @param {string} args.action - Action.
    * @param {typeof import("../database/record/index.js").default} args.modelClass - Model class.
    * @param {import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>} args.query - Base query.
+   * @param {() => import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>} [args.ruleQueryFactory] - Optional conditional-rule query factory.
    * @param {AbilityRuleType[]} args.rules - Rules.
    * @returns {string[]} - SQL condition parts.
    */
-  conditionSqlParts({action, modelClass, query, rules}) {
-    const pk = modelClass.primaryKey()
-    const quotedBaseTable = query.driver.quoteTable(modelClass.tableName())
-    const quotedPk = query.driver.quoteColumn(pk)
+  conditionSqlParts({action, modelClass, query, ruleQueryFactory, rules}) {
+    const primaryKey = modelClass.primaryKey()
+    const primaryKeyAttributes = Array.isArray(primaryKey) ? primaryKey : [primaryKey]
+    const quotedBaseTable = query.driver.quoteTable(query.getTableReferenceForJoin())
     const sqlParts = []
 
     for (const rule of rules) {
       if (!rule.conditions) continue
 
-      const scopedQuery = modelClass._newQuery()
+      const scopedQuery = ruleQueryFactory ? ruleQueryFactory() : modelClass._newQuery()
       const resultQuery = this.applyRuleCondition({
         action,
         conditions: rule.conditions,
@@ -260,7 +262,16 @@ export default class VelociousAuthorizationAbility {
         query: scopedQuery
       })
       const finalQuery = resultQuery || scopedQuery
-      const selectedPkSql = `${quotedBaseTable}.${quotedPk}`
+
+      if (ruleQueryFactory && finalQuery !== scopedQuery) {
+        const finalFroms = finalQuery.getFroms()
+
+        finalFroms.splice(0, finalFroms.length, ...scopedQuery.getFroms())
+      }
+
+      const quotedScopedTable = query.driver.quoteTable(finalQuery.getTableReferenceForJoin())
+      const primaryKeyColumns = primaryKeyAttributes.map((attributeName) => modelClass.getColumnNameForAttributeName(attributeName))
+      const selectedPkSql = primaryKeyColumns.map((columnName) => `${quotedScopedTable}.${query.driver.quoteColumn(columnName)}`)
 
       if (finalQuery._distinct) {
         query.distinct(true)
@@ -268,7 +279,18 @@ export default class VelociousAuthorizationAbility {
 
       finalQuery.select(selectedPkSql)
 
-      sqlParts.push(`${quotedBaseTable}.${quotedPk} IN (${finalQuery.toSql()})`)
+      if (Array.isArray(primaryKey)) {
+        const authorizedRowsAlias = query.driver.quoteTable("velocious_authorized_rows")
+        const identitySql = primaryKeyColumns.map((columnName) => {
+          const quotedColumn = query.driver.quoteColumn(columnName)
+
+          return `${authorizedRowsAlias}.${quotedColumn} = ${quotedBaseTable}.${quotedColumn}`
+        }).join(" AND ")
+
+        sqlParts.push(`EXISTS (SELECT 1 FROM (${finalQuery.toSql()}) AS ${authorizedRowsAlias} WHERE ${identitySql})`)
+      } else {
+        sqlParts.push(`${quotedBaseTable}.${query.driver.quoteColumn(primaryKeyColumns[0])} IN (${finalQuery.toSql()})`)
+      }
     }
 
     return sqlParts
@@ -281,9 +303,10 @@ export default class VelociousAuthorizationAbility {
    * @param {AbilityRuleType[]} args.denyRules - Deny rules.
    * @param {typeof import("../database/record/index.js").default} args.modelClass - Model class.
    * @param {import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>} args.query - Query.
+   * @param {() => import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>} [args.ruleQueryFactory] - Optional conditional-rule query factory.
    * @returns {void} - No return value.
    */
-  applyDenyRules({action, denyRules, modelClass, query}) {
+  applyDenyRules({action, denyRules, modelClass, query, ruleQueryFactory}) {
     if (denyRules.length === 0) return
 
     if (denyRules.some((rule) => !rule.conditions)) {
@@ -291,7 +314,7 @@ export default class VelociousAuthorizationAbility {
       return
     }
 
-    const denySqlParts = this.conditionSqlParts({action, modelClass, query, rules: denyRules})
+    const denySqlParts = this.conditionSqlParts({action, modelClass, query, ruleQueryFactory, rules: denyRules})
 
     if (denySqlParts.length > 0) {
       query.where(`NOT (${denySqlParts.join(" OR ")})`)

package/build/background-jobs/adapter.js

@@ -48,6 +48,15 @@ export default class BackgroundJobsAdapter {
    */
   async reconcileQueueConcurrency() { throw new Error("BackgroundJobsAdapter#reconcileQueueConcurrency is not implemented") }
 
+  /**
+   * Repairs drift in adapter-owned durable active concurrency counts. Adapters
+   * without duplicate active-count persistence can keep this no-op result.
+   * @returns {Promise<import("./types.js").BackgroundJobConcurrencyReconciliation>} - Repair summary.
+   */
+  async reconcileActiveConcurrency() {
+    return {candidateCount: 0, checkedCount: 0, repairedCount: 0, repairs: [], repairsTruncatedCount: 0}
+  }
+
   /**
    * Enqueues a job.
    * @param {{jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: import("./types.js").BackgroundJobOptions}} _args - Job request.

package/build/background-jobs/main.js

@@ -2063,23 +2063,25 @@ export default class BackgroundJobsMain {
       handoffs.set(job.id, handoff.handoffId)
 
       try {
+        const dispatchedJob = handoff.job || job
+
         worker.send({
           type: "job",
           payload: {
-            id: job.id,
-            jobName: job.jobName,
-            args: job.args,
+            id: dispatchedJob.id,
+            jobName: dispatchedJob.jobName,
+            args: dispatchedJob.args,
             handoffId: handoff.handoffId,
             workerId: worker.workerId,
             handedOffAtMs: handoff.handedOffAtMs,
             options: {
-              concurrencyKey: job.concurrencyKey || undefined,
-              executionMode: job.executionMode,
-              maxConcurrency: job.maxConcurrency ?? undefined,
-              maxRetries: job.maxRetries ?? undefined,
-              queue: job.queue,
-              scheduledAtMs: job.scheduledAtMs ?? undefined,
-              ...(job.timeoutMs === null ? {} : {timeoutMs: job.timeoutMs})
+              concurrencyKey: dispatchedJob.concurrencyKey || undefined,
+              executionMode: dispatchedJob.executionMode,
+              maxConcurrency: dispatchedJob.maxConcurrency ?? undefined,
+              maxRetries: dispatchedJob.maxRetries ?? undefined,
+              queue: dispatchedJob.queue,
+              scheduledAtMs: dispatchedJob.scheduledAtMs ?? undefined,
+              ...(dispatchedJob.timeoutMs === null ? {} : {timeoutMs: dispatchedJob.timeoutMs})
             }
           }
         })
@@ -2354,6 +2356,29 @@ export default class BackgroundJobsMain {
       errorEvents.emit("framework-error", payload)
       errorEvents.emit("all-error", {...payload, errorType: "framework-error"})
     }
+
+    if (this.lifecycleState === "active") await this._reconcileActiveConcurrency()
+  }
+
+  /**
+   * Repairs durable admission counters on the active main's maintenance cadence
+   * and immediately retries dispatch when capacity was recovered.
+   * @returns {Promise<void>} - Resolves after repair and any resulting drain.
+   */
+  async _reconcileActiveConcurrency() {
+    try {
+      const result = await this.store.reconcileActiveConcurrency()
+
+      if (result.repairedCount > 0) await this._drain()
+    } catch (error) {
+      const normalizedError = error instanceof Error ? error : new Error(String(error))
+      const payload = {context: {generationId: this.generationId, stage: "background-job-concurrency-reconciliation"}, error: normalizedError}
+      const errorEvents = this.configuration.getErrorEvents()
+
+      this.logger.error(() => ["Failed to reconcile background job active-concurrency counts:", normalizedError])
+      errorEvents.emit("framework-error", payload)
+      errorEvents.emit("all-error", {...payload, errorType: "framework-error"})
+    }
   }
 
   /**