velocious 1.0.641 → 1.0.643

package/README.md

@@ -47,7 +47,7 @@
 * 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))
-* Backend record attachments with filesystem, S3, native callback, and bounded Node path-input persistence (see [docs/attachments.md](docs/attachments.md))
+* Backend record attachments with filesystem, S3, native callback, bounded Node path-input persistence, and model-declared client sync policy (see [docs/attachments.md](docs/attachments.md))
 
 # Setup
 
@@ -701,6 +701,13 @@ For backend models, you can declare attachment helpers directly:
 Task.hasManyAttachments("files")
 Task.hasOneAttachment("descriptionFile")
 Task.hasOneAttachment("archivedPdf", {driver: "s3"})
+User.hasOneAttachment("profilePicture", {
+  sync: {
+    fetch: "eager",
+    offlineRequirement: "optional",
+    retention: "evictable"
+  }
+})
 ```
 
 `db:migrate` provisions the framework-owned attachment table before runtime
@@ -815,7 +822,9 @@ behavior. See
 [docs/attachments.md](docs/attachments.md#normalized-storage-driver-input) for
 the normalized input passed to custom drivers.
 
-For frontend models, configure `resourceConfig().attachments` and use:
+For a resource with a backing model, the model attachment declaration
+automatically generates `resourceConfig().attachments`; do not repeat it on the
+resource. Use the generated attachment handles normally:
 
 ```js
 await frontendTask.update({descriptionFile: file})
@@ -828,6 +837,11 @@ await frontendTask.attach(file)
 
 Frontend model attachment input does not support `{path: ...}`.
 Use `File`/`Blob`/bytes/`contentBase64` payloads instead.
+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`.
 
 When your frontend app calls a backend on another host/port (or under a path prefix), configure transport once:
@@ -2393,6 +2407,15 @@ supervisor that preserves old generation units and release pins, and a deploy
 coordinator that retires the old generation before activating the healthy
 candidate without waiting for retired work to finish.
 
+Candidate activation performs bounded durable concurrency reconciliation: it
+examines queue-derived keys and counters that are active or stale instead of
+running a job-table count query for every historical key. If recovery retires a
+candidate while that work is still in flight, the retirement fence wins and
+activation cannot later restore ownership or acknowledge success. The SQL store
+also repairs secondary indexes missed by older background-job add-column
+upgrades through a one-time internal migration, with conflict-safe SQLite index
+creation across generation processes.
+
 Jobs can opt into cross-worker durable concurrency limits by pairing a non-empty `concurrencyKey` with a positive-integer `maxConcurrency` in their background-job options, or by deriving the key in a hydrated job instance's non-static `concurrencyKey()` method. Explicit enqueue options win. The first cap registered for a key is stable; conflicting caps are rejected. See [durable concurrency limits](docs/background-jobs.md#durable-concurrency-limits).
 
 Production apps can listen for `background-job-failed` (or its `all-error` mirror) to report accepted failed attempts, including retry and terminal-state metadata. Process-level pooled-runner failures also carry one shared `context.runnerFailure` snapshot for every affected job, with active handoff identities, runner/worker lifecycle and PIDs, exit code/signal, termination reason, and an explicit nullable OOM verdict. Listen for `background-job-orphaned` to react to a specific job the main process reclaimed after its worker died mid-run — e.g. enqueue a targeted recovery for the work it left behind, instead of only polling for the aftermath. Orphan handlers run before the sweep waits for reclaimed jobs to be dispatched, so a stalled dispatcher does not delay application recovery. See [docs/background-jobs.md](docs/background-jobs.md#failure-events).

package/build/authorization/base-resource.js

@@ -1,10 +1,15 @@
 // @ts-check
 
+/**
+ * Model class supported by authorization and shared frontend-model resources.
+ * @typedef {{new (): import("../database/record/index.js").default | import("../frontend-models/base.js").default, getModelName: () => string}} AuthorizationResourceModelClass
+ */
+
 /** Base class for authorization resources defining abilities for a model. */
 export default class AuthorizationBaseResource {
   /**
    * Model class.
-   * @type {typeof import("../database/record/index.js").default | undefined} */
+   * @type {AuthorizationResourceModelClass | undefined} */
   static ModelClass = undefined
 
   /**
@@ -22,7 +27,9 @@ export default class AuthorizationBaseResource {
 
   /**
    * Runs model class.
-   * @returns {typeof import("../database/record/index.js").default} - Model class handled by this resource.
+   * @template {AuthorizationResourceModelClass} TModelClass
+   * @this {{ModelClass: TModelClass | undefined, name: string}}
+   * @returns {TModelClass} - Model class handled by this resource.
    */
   static modelClass() {
     if (!this.ModelClass) {
@@ -41,7 +48,10 @@ export default class AuthorizationBaseResource {
    */
   can(actions, conditions) {
     this.assertResourceConditionsSignature({conditions, methodName: "can"})
-    this.requiredAbility().can(actions, this.requiredModelClass(), /** @type {import("./ability.js").AbilityConditionsType<typeof import("../database/record/index.js").default> | undefined} */ (conditions))
+    // Authorization query rules are backend-only even when a shared resource is bound to a frontend model.
+    const modelClass = /** @type {typeof import("../database/record/index.js").default} */ (this.requiredModelClass())
+
+    this.requiredAbility().can(actions, modelClass, /** @type {import("./ability.js").AbilityConditionsType<typeof import("../database/record/index.js").default> | undefined} */ (conditions))
   }
 
   /**
@@ -53,7 +63,10 @@ export default class AuthorizationBaseResource {
    */
   cannot(actions, conditions) {
     this.assertResourceConditionsSignature({conditions, methodName: "cannot"})
-    this.requiredAbility().cannot(actions, this.requiredModelClass(), /** @type {import("./ability.js").AbilityConditionsType<typeof import("../database/record/index.js").default> | undefined} */ (conditions))
+    // Authorization query rules are backend-only even when a shared resource is bound to a frontend model.
+    const modelClass = /** @type {typeof import("../database/record/index.js").default} */ (this.requiredModelClass())
+
+    this.requiredAbility().cannot(actions, modelClass, /** @type {import("./ability.js").AbilityConditionsType<typeof import("../database/record/index.js").default> | undefined} */ (conditions))
   }
 
   /**
@@ -70,7 +83,7 @@ export default class AuthorizationBaseResource {
 
   /**
    * Runs required model class.
-   * @returns {typeof import("../database/record/index.js").default} - Model class handled by this resource.
+   * @returns {AuthorizationResourceModelClass} - Model class handled by this resource.
    */
   requiredModelClass() {
     const ResourceClass = /** @type {typeof AuthorizationBaseResource} */ (this.constructor)

package/build/background-jobs/main.js

@@ -325,7 +325,7 @@ export default class BackgroundJobsMain {
       }, this.workerLivenessSweepMs)
 
       if (this.lifecycleState === "active") {
-        await this._startActiveOwnership()
+        await this._startActiveOwnership("active")
       } else if (this.lifecycleState === "retired") {
         this._startGenerationRecoveryOwnership()
       }
@@ -519,17 +519,27 @@ export default class BackgroundJobsMain {
 
   /**
    * Acquires scheduling and dispatch ownership for an active generation.
-   * @returns {Promise<void>} - Resolves after active ownership is established.
+   * @param {"active" | "candidate"} expectedLifecycleState - State that still owns activation.
+   * @returns {Promise<boolean>} - Whether active ownership was established.
    */
-  async _startActiveOwnership() {
+  async _startActiveOwnership(expectedLifecycleState) {
     await this.store.reconcileQueueConcurrency()
+    if (this.lifecycleState !== expectedLifecycleState) return false
     this._setupDispatchTriggers()
     this._setupStartupHandoffReclaim()
     this._startOrphanSweep()
     await this._startScheduler()
+    if (this.lifecycleState !== expectedLifecycleState) {
+      if (this.scheduler) await this.scheduler.stop()
+      this.scheduler = undefined
+      this._clearDispatchTimers()
+      this._disconnectBeaconHandlers()
+      return false
+    }
     this._activeOwnershipReady = true
     this._creditReadyWorkers()
     await this._drain()
+    return this.lifecycleState === expectedLifecycleState
   }
 
   /** Starts exact recovery duties without acquiring global dispatch ownership. */
@@ -603,7 +613,10 @@ export default class BackgroundJobsMain {
    */
   async _activate() {
     this.logger.info(() => ["Background jobs generation activation starting", {generationId: this.generationId}])
-    await this._startActiveOwnership()
+    const ownershipStarted = await this._startActiveOwnership("candidate")
+    if (!ownershipStarted || this.lifecycleState !== "candidate") {
+      throw new Error("Background jobs generation retirement started before activation acquired ownership")
+    }
     this.lifecycleState = "active"
     this._creditReadyWorkers()
     this.logger.info(() => ["Background jobs generation activation acknowledged", {generationId: this.generationId}])
@@ -619,7 +632,8 @@ export default class BackgroundJobsMain {
   retire() {
     if (!this.generationId) throw new Error("Background jobs generation retirement requires generation mode")
     if (this.lifecycleState === "retiring" || this.lifecycleState === "retired") return Promise.resolve()
-    if (this.lifecycleState !== "active") throw new Error(`Cannot retire background jobs generation from ${this.lifecycleState}`)
+    const activationInProgress = this.lifecycleState === "candidate" && Boolean(this._activationPromise)
+    if (this.lifecycleState !== "active" && !activationInProgress) throw new Error(`Cannot retire background jobs generation from ${this.lifecycleState}`)
 
     this.lifecycleState = "retiring"
     this._activeOwnershipReady = false
@@ -638,7 +652,8 @@ export default class BackgroundJobsMain {
    * @returns {Promise<void>} - Retirement fence completion.
    */
   async _retire() {
-    await this.scheduler?.stop()
+    if (this._activationPromise) await Promise.allSettled([this._activationPromise])
+    if (this.scheduler) await this.scheduler.stop()
     this.scheduler = undefined
     if (this._drainPromise) await this._drainPromise
     if (this._stopped) return

package/build/background-jobs/store.js

@@ -66,12 +66,24 @@ const EXECUTION_MODE_BACKFILL_MIGRATION_VERSION = "20260607131010"
 // handoff-marker workaround), leaving `execution_mode` as the single source of
 // truth for a job's runtime.
 const DROP_FORKED_COLUMN_MIGRATION_VERSION = "20260719000000"
+const JOBS_INDEX_REPAIR_MIGRATION_VERSION = "20260903120000"
 // Legacy marker prefix used by rows written before this migration: pooled jobs
 // used to persist as `execution_mode = "forked"` plus a `velocious-pooled:*`
 // handoff id. Retained only to detect and convert those rows in the migration.
 const LEGACY_POOLED_HANDOFF_ID_PREFIX = "velocious-pooled:"
 const LEGACY_POOLED_QUEUED_HANDOFF_ID = `${LEGACY_POOLED_HANDOFF_ID_PREFIX}queued`
 const JOBS_TABLE = "background_jobs"
+const JOBS_INDEX_COLUMN_NAMES = [
+  "job_name",
+  "queue",
+  "status",
+  "scheduled_at_ms",
+  "created_at_ms",
+  "schedule_key",
+  "handed_off_at_ms",
+  "orphaned_at_ms",
+  "concurrency_key"
+]
 const IDEMPOTENCY_KEYS_TABLE = "background_job_idempotency_keys"
 const SCHEDULE_KEYS_TABLE = "background_job_schedule_keys"
 const CONCURRENCY_TABLE = "background_job_concurrency"
@@ -1838,6 +1850,50 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
     await this._ensureQueueColumn(db)
     await this._ensureScheduleKeyColumn(db)
     await this._ensureJobTimeoutColumn(db)
+    await this._ensureJobsTableIndexesOnce(db)
+  }
+
+  /**
+   * Repairs secondary indexes that older add-column upgrades declared but did
+   * not create on every SQL driver. The migration ledger keeps routine store
+   * readiness from repeatedly introspecting the full index set.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @returns {Promise<void>} - Resolves when all expected indexes exist.
+   */
+  async _ensureJobsTableIndexesOnce(db) {
+    const migrationVersion = JOBS_INDEX_REPAIR_MIGRATION_VERSION
+    const migrationKey = this._migrationKey(migrationVersion)
+
+    if (await this._hasMigration(db, migrationVersion)) return
+
+    const acquired = await db.acquireAdvisoryLock(migrationKey)
+
+    if (!acquired) throw new Error("Failed to acquire background jobs index repair lock")
+
+    try {
+      if (await this._hasMigration(db, migrationVersion)) return
+
+      db.clearSchemaCache()
+      const table = await db.getTableByNameOrFail(JOBS_TABLE)
+      const indexedColumnNames = new Set(
+        (await table.getIndexes())
+          .filter((index) => !index.isPrimaryKey() && index.getColumnNames().length === 1)
+          .map((index) => index.getColumnNames()[0])
+      )
+
+      for (const columnName of JOBS_INDEX_COLUMN_NAMES) {
+        if (indexedColumnNames.has(columnName)) continue
+
+        for (const sql of await db.createIndexSQLs({columns: [columnName], ifNotExists: db.getType() === "sqlite", tableName: JOBS_TABLE})) {
+          await db.query(sql)
+        }
+      }
+
+      db.clearSchemaCache()
+      await this._recordMigration(db, migrationVersion)
+    } finally {
+      await db.releaseAdvisoryLock(migrationKey)
+    }
   }
 
   /**
@@ -2711,13 +2767,61 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    */
   async _reconcileConcurrency(db) {
     if (!(await db.tableExists(CONCURRENCY_TABLE))) return
-    const concurrencyTable = db.quoteTable(CONCURRENCY_TABLE)
-    const jobsTable = db.quoteTable(JOBS_TABLE)
-    await db.query(
-      `UPDATE ${concurrencyTable} SET ${db.quoteColumn("active_count")} = (` +
-      `SELECT COUNT(*) FROM ${jobsTable} WHERE ${jobsTable}.${db.quoteColumn("status")} = ${db.quote("handed_off")} AND ` +
-      `${jobsTable}.${db.quoteColumn("concurrency_key")} = ${concurrencyTable}.${db.quoteColumn("concurrency_key")})`
+    const activeRows = await db
+      .newQuery()
+      .from(JOBS_TABLE)
+      .select("concurrency_key")
+      .where({status: "handed_off"})
+      .where(`${db.quoteColumn("concurrency_key")} IS NOT NULL`)
+      .group("concurrency_key")
+      .results()
+    const staleRows = await db
+      .newQuery()
+      .from(CONCURRENCY_TABLE)
+      .select("concurrency_key")
+      .where(`${db.quoteColumn("active_count")} != 0`)
+      .results()
+    const concurrencyKeys = new Set(
+      [...activeRows, ...staleRows].map((row) =>
+        String(/** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (row).concurrency_key)
+      )
     )
+
+    for (const concurrencyKey of [...concurrencyKeys].sort()) {
+      await this._transactionResult(db, async () => {
+        await this._reconcileConcurrencyKey(db, concurrencyKey)
+      })
+    }
+  }
+
+  /**
+   * Rebuilds one counter after locking it ahead of the job rows, matching the
+   * lock order used by handoff and completion transitions.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @param {string} concurrencyKey - Counter key.
+   * @returns {Promise<void>} - Resolves when reconciled.
+   */
+  async _reconcileConcurrencyKey(db, concurrencyKey) {
+    await this._lockConcurrencyRow(db, concurrencyKey)
+    const rows = await db
+      .newQuery()
+      .from(JOBS_TABLE)
+      .select("COUNT(*) AS active_count")
+      .where({concurrency_key: concurrencyKey, status: "handed_off"})
+      .results()
+    const activeCount = this._normalizeNumber(
+      /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (rows[0] || {}).active_count
+    )
+
+    if (activeCount === null || !Number.isSafeInteger(activeCount) || activeCount < 0) {
+      throw new Error(`Invalid reconciled background job concurrency count for ${concurrencyKey}: ${activeCount}`)
+    }
+
+    await db.update({
+      tableName: CONCURRENCY_TABLE,
+      data: {active_count: activeCount},
+      conditions: {concurrency_key: concurrencyKey}
+    })
   }
 
   /**
@@ -2768,7 +2872,12 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
       )
     }
 
-    const concurrencyRows = await db.newQuery().from(CONCURRENCY_TABLE).select("concurrency_key").results()
+    const concurrencyRows = await db
+      .newQuery()
+      .from(CONCURRENCY_TABLE)
+      .select("concurrency_key")
+      .where(`${db.quoteColumn("concurrency_key")} LIKE ${db.quote(`${QUEUE_CONCURRENCY_KEY_PREFIX}%`)}`)
+      .results()
 
     for (const row of concurrencyRows) {
       const concurrencyKey = String(/** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (row).concurrency_key)

package/build/configuration-types.js

@@ -375,6 +375,22 @@
  * @property {Record<string, ReturnType<typeof JSON.parse>>} [instance] - Optional custom attachment driver instance.
  */
 
+/**
+ * Client-safe synchronization policy declared with a model attachment.
+ * @typedef {object} AttachmentSyncConfiguration
+ * @property {"eager" | "on-demand"} fetch - Whether clients prefetch the attachment or wait until it is requested.
+ * @property {"optional" | "required"} offlineRequirement - Whether an offline-ready scope requires the attachment bytes.
+ * @property {"durable" | "evictable"} retention - Whether clients may evict the attachment under storage pressure.
+ */
+
+/**
+ * Model attachment declaration retained by the record class.
+ * @typedef {object} RecordAttachmentConfiguration
+ * @property {string | AttachmentDriverConstructor | Record<string, ReturnType<typeof JSON.parse>>} [driver] - Attachment driver name, class, or instance.
+ * @property {AttachmentSyncConfiguration} [sync] - Client-safe synchronized asset policy.
+ * @property {"hasOne" | "hasMany"} type - Attachment cardinality.
+ */
+
 /**
  * @typedef {object} AttachmentsConfiguration
  * @property {string} [defaultDriver] - Default attachment storage driver name.
@@ -418,6 +434,7 @@
 
 /**
  * @typedef {object} FrontendModelAttachmentConfiguration
+ * @property {AttachmentSyncConfiguration} [sync] - Client-side synchronized asset policy.
  * @property {"hasOne" | "hasMany"} type - Attachment cardinality.
  */
 
@@ -574,11 +591,26 @@
  */
 
 /**
- * @typedef {Omit<typeof import("./frontend-model-resource/base-resource.js").default, never> & {new (args: import("./frontend-model-resource/base-resource.js").FrontendModelResourceAbilityArgs | import("./frontend-model-resource/base-resource.js").FrontendModelResourceControllerArgs): import("./frontend-model-resource/base-resource.js").default<typeof import("./database/record/index.js").default>}} FrontendModelResourceClassType
+ * Unbound resource class used by model-agnostic registries.
+ * @typedef {Omit<typeof import("./frontend-model-resource/base-resource.js").default, "modelClass"> & {modelClass: () => typeof import("./database/record/index.js").default, new (args: never): import("./frontend-model-resource/base-resource.js").default<typeof import("./database/record/index.js").default>}} UnboundFrontendModelResourceClassType
+ */
+
+/**
+ * Resource class bound to a specific model class.
+ * @template {import("./frontend-model-resource/base-resource.js").FrontendModelResourceModelClass} TModelClass
+ * @template {typeof import("./database/record/index.js").default} TDatabaseModelClass
+ * @typedef {Omit<typeof import("./frontend-model-resource/base-resource.js").default, "ModelClass" | "modelClass"> & {ModelClass: TModelClass | undefined, modelClass: () => TModelClass, new (args: import("./frontend-model-resource/base-resource.js").FrontendModelResourceAbilityArgs<TModelClass> | import("./frontend-model-resource/base-resource.js").FrontendModelResourceControllerArgs<TDatabaseModelClass>): import("./frontend-model-resource/base-resource.js").default<TModelClass, TDatabaseModelClass>}} BoundFrontendModelResourceClassType
+ */
+
+/**
+ * @template {import("./frontend-model-resource/base-resource.js").FrontendModelResourceModelClass} [TModelClass=never]
+ * @template {typeof import("./database/record/index.js").default} [TDatabaseModelClass=Extract<TModelClass, typeof import("./database/record/index.js").default>]
+ * @typedef {[TModelClass] extends [never] ? UnboundFrontendModelResourceClassType : BoundFrontendModelResourceClassType<TModelClass, TDatabaseModelClass>} FrontendModelResourceClassType
  */
 
 /**
- * @typedef {FrontendModelResourceClassType} FrontendModelResourceDefinition
+ * @template {import("./frontend-model-resource/base-resource.js").FrontendModelResourceModelClass} [TModelClass=never]
+ * @typedef {FrontendModelResourceClassType<TModelClass>} FrontendModelResourceDefinition
  */
 
 /**

package/build/database/record/index.js

@@ -71,6 +71,8 @@ import UUID from "pure-uuid"
  * AttachmentDriverConstructor type.
  * @typedef {import("../../configuration-types.js").AttachmentDriverConstructor} AttachmentDriverConstructor
  */
+/** @typedef {import("../../configuration-types.js").AttachmentSyncConfiguration} AttachmentSyncConfiguration */
+/** @typedef {import("../../configuration-types.js").RecordAttachmentConfiguration} RecordAttachmentConfiguration */
 
 /** Stored values that a declared `"boolean"` cast reads back as `true`. */
 const declaredBooleanTruthyValues = new Set([1, true, "1"])
@@ -238,7 +240,7 @@ class VelociousDatabaseRecord {
   static _lifecycleCallbacks = undefined
   /** @type {Record<string, typeof import("./validators/base.js").default> | undefined} */
   static _validatorTypes = undefined
-  /** @type {Record<string, {driver?: string | AttachmentDriverConstructor | Record<string, ReturnType<typeof JSON.parse>>, type: "hasOne" | "hasMany"}> | undefined} */
+  /** @type {Record<string, RecordAttachmentConfiguration> | undefined} */
   static _attachmentsMap = undefined
   /** @type {Record<string, import("./relationships/base.js").default> | undefined} */
   static _relationships = undefined
@@ -494,13 +496,13 @@ class VelociousDatabaseRecord {
 
   /**
    * Runs get attachments map.
-   * @returns {Record<string, {driver?: string | AttachmentDriverConstructor | Record<string, ReturnType<typeof JSON.parse>>, type: "hasOne" | "hasMany"}>} - Attachment definitions keyed by name.
+   * @returns {Record<string, RecordAttachmentConfiguration>} - Attachment definitions keyed by name.
    */
   static getAttachmentsMap() {
     if (!this._attachmentsMap) {
       /**
        * Narrows the runtime value to the documented type.
-       * @type {Record<string, {driver?: string | AttachmentDriverConstructor | Record<string, ReturnType<typeof JSON.parse>>, type: "hasOne" | "hasMany"}>} */
+       * @type {Record<string, RecordAttachmentConfiguration>} */
       this._attachmentsMap = {}
     }
 
@@ -1165,16 +1167,25 @@ class VelociousDatabaseRecord {
 
   /**
    * Runs get attachments.
-   * @returns {Record<string, {driver?: string | AttachmentDriverConstructor | Record<string, ReturnType<typeof JSON.parse>>, type: "hasOne" | "hasMany"}>} - Attachment definitions.
+   * @returns {Record<string, RecordAttachmentConfiguration>} - Attachment definitions.
    */
   static getAttachments() {
     return this.getAttachmentsMap()
   }
 
+  /**
+   * Returns attachment definitions through the model contract shared with
+   * frontend model classes.
+   * @returns {Record<string, RecordAttachmentConfiguration>} - Attachment definitions.
+   */
+  static attachmentDefinitions() {
+    return this.getAttachmentsMap()
+  }
+
   /**
    * Runs get attachment by name.
    * @param {string} attachmentName - Attachment name.
-   * @returns {{driver?: string | AttachmentDriverConstructor | Record<string, ReturnType<typeof JSON.parse>>, type: "hasOne" | "hasMany"}} - Attachment definition.
+   * @returns {RecordAttachmentConfiguration} - Attachment definition.
    */
   static getAttachmentByName(attachmentName) {
     const definition = this.getAttachmentsMap()[attachmentName]
@@ -1443,14 +1454,34 @@ class VelociousDatabaseRecord {
    * @param {string} attachmentName - Attachment name.
    * @param {object} args - Attachment args.
    * @param {string | AttachmentDriverConstructor | Record<string, ReturnType<typeof JSON.parse>>} [args.driver] - Attachment driver name, class, or instance.
+   * @param {AttachmentSyncConfiguration} [args.sync] - Client-safe synchronized asset policy.
    * @param {"hasOne" | "hasMany"} args.type - Attachment type.
    * @returns {void} - No return value.
    */
-  static _defineAttachment(attachmentName, {driver, type}) {
+  static _defineAttachment(attachmentName, {driver, sync, type}) {
     if (!attachmentName || typeof attachmentName !== "string") throw new Error(`Invalid attachment name: ${attachmentName}`)
     if (attachmentName in this.getAttachmentsMap()) throw new Error(`Attachment ${attachmentName} already exists`)
 
-    this.getAttachmentsMap()[attachmentName] = {driver, type}
+    if (sync) {
+      const {fetch, offlineRequirement, retention, ...restSync} = sync
+
+      restArgsError(restSync)
+
+      if (fetch !== "eager" && fetch !== "on-demand") {
+        throw new Error(`Attachment ${attachmentName} sync fetch must be eager or on-demand`)
+      }
+      if (offlineRequirement !== "optional" && offlineRequirement !== "required") {
+        throw new Error(`Attachment ${attachmentName} offline requirement must be optional or required`)
+      }
+      if (retention !== "durable" && retention !== "evictable") {
+        throw new Error(`Attachment ${attachmentName} sync retention must be durable or evictable`)
+      }
+      if (offlineRequirement === "required" && retention !== "durable") {
+        throw new Error(`Attachment ${attachmentName} required offline assets must use durable retention`)
+      }
+    }
+
+    this.getAttachmentsMap()[attachmentName] = {driver, sync, type}
 
     const prototype = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (/** @type {ReturnType<typeof JSON.parse>} */ (this.prototype))
 
@@ -1467,21 +1498,21 @@ class VelociousDatabaseRecord {
   /**
    * Adds a single attachment helper to the model.
    * @param {string} attachmentName - Attachment name.
-   * @param {{driver?: string | AttachmentDriverConstructor | Record<string, ReturnType<typeof JSON.parse>>}} [args] - Attachment options.
+   * @param {{driver?: string | AttachmentDriverConstructor | Record<string, ReturnType<typeof JSON.parse>>, sync?: AttachmentSyncConfiguration}} [args] - Attachment options.
    * @returns {void} - No return value.
    */
   static hasOneAttachment(attachmentName, args = {}) {
-    this._defineAttachment(attachmentName, {driver: args.driver, type: "hasOne"})
+    this._defineAttachment(attachmentName, {driver: args.driver, sync: args.sync, type: "hasOne"})
   }
 
   /**
    * Adds a collection attachment helper to the model.
    * @param {string} attachmentName - Attachment name.
-   * @param {{driver?: string | AttachmentDriverConstructor | Record<string, ReturnType<typeof JSON.parse>>}} [args] - Attachment options.
+   * @param {{driver?: string | AttachmentDriverConstructor | Record<string, ReturnType<typeof JSON.parse>>, sync?: AttachmentSyncConfiguration}} [args] - Attachment options.
    * @returns {void} - No return value.
    */
   static hasManyAttachments(attachmentName, args = {}) {
-    this._defineAttachment(attachmentName, {driver: args.driver, type: "hasMany"})
+    this._defineAttachment(attachmentName, {driver: args.driver, sync: args.sync, type: "hasMany"})
   }
 
   /**

package/build/environment-handlers/node/cli/commands/generate/frontend-models.js

@@ -5,6 +5,7 @@ import path from "node:path"
 import * as inflection from "inflection"
 import {frontendModelResourceIsBuiltIn, frontendModelResourcesWithBuiltInsForBackendProject} from "../../../../../frontend-models/built-in-resources.js"
 import {frontendModelResourceClassFromDefinition, frontendModelResourceConfigurationFromDefinition} from "../../../../../frontend-models/resource-definition.js"
+import {frontendModelResourceInternalConstructor} from "../../../../../frontend-model-resource/base-resource.js"
 
 /**
  * Attribute metadata used for generated frontend-model JSDoc.
@@ -381,7 +382,18 @@ export default class DbGenerateFrontendModels extends BaseCommand {
           ? "hasMany"
           : "hasOne"
 
-        fileContent += `        ${attachmentName}: {type: ${JSON.stringify(attachmentType)}},\n`
+        if (attachmentConfig.sync) {
+          fileContent += `        ${attachmentName}: {\n`
+          fileContent += "          sync: {\n"
+          fileContent += `            fetch: ${JSON.stringify(attachmentConfig.sync.fetch)},\n`
+          fileContent += `            offlineRequirement: ${JSON.stringify(attachmentConfig.sync.offlineRequirement)},\n`
+          fileContent += `            retention: ${JSON.stringify(attachmentConfig.sync.retention)},\n`
+          fileContent += "          },\n"
+          fileContent += `          type: ${JSON.stringify(attachmentType)}\n`
+          fileContent += "        },\n"
+        } else {
+          fileContent += `        ${attachmentName}: {type: ${JSON.stringify(attachmentType)}},\n`
+        }
       }
       fileContent += "      },\n"
     }
@@ -857,7 +869,8 @@ export default class DbGenerateFrontendModels extends BaseCommand {
     try {
       const modelClass = resourceClass.modelClass()
 
-      const instance = new resourceClass({
+      const ResourceClass = frontendModelResourceInternalConstructor(resourceClass)
+      const instance = new ResourceClass({
         ability: undefined,
         context: {},
         locals: {},
@@ -894,7 +907,8 @@ export default class DbGenerateFrontendModels extends BaseCommand {
     try {
       const modelClass = resourceClass.modelClass()
 
-      const instance = new resourceClass({
+      const ResourceClass = frontendModelResourceInternalConstructor(resourceClass)
+      const instance = new ResourceClass({
         ability: undefined,
         context: {},
         locals: {},

package/build/frontend-model-controller.js

@@ -3,7 +3,7 @@
 import {randomUUID} from "node:crypto"
 import * as inflection from "inflection"
 import Controller from "./controller.js"
-import FrontendModelBaseResource from "./frontend-model-resource/base-resource.js"
+import FrontendModelBaseResource, {frontendModelResourceInternalConstructor} from "./frontend-model-resource/base-resource.js"
 import Response from "./http-server/client/response.js"
 import {frontendModelResourcesWithBuiltInsForBackendProject} from "./frontend-models/built-in-resources.js"
 import {frontendModelResourceClassFromDefinition, frontendModelResourceConfigurationFromDefinition, frontendModelResourcePath, frontendModelResourcesForBackendProject, frontendModelSyncManifestForBackendProjects} from "./frontend-models/resource-definition.js"
@@ -70,7 +70,7 @@ import {RansackQueryError, normalizeRansackGroup, parseRansackSort} from "./util
  * @typedef {object} FrontendModelIndexQueryOptions
  * @property {boolean} [includePagination] - Whether frontend-model pagination params should be applied.
  * @property {boolean} [includeSort] - Whether frontend-model sort params should be applied.
- * @property {import("./frontend-model-resource/base-resource.js").default} [resource] - Resource providing query hooks.
+ * @property {Pick<import("./frontend-model-resource/base-resource.js").default<import("./frontend-model-resource/base-resource.js").FrontendModelResourceModelClass>, "applyFrontendModelIndexPagination" | "applyFrontendModelIndexSearch" | "applyFrontendModelIndexSort">} [resource] - Resource providing query hooks.
  */
 /** @typedef {import("./database/query/model-class-query.js").default & Record<symbol, Set<string> | undefined>} FrontendModelQueryMetadata */
 /**
@@ -1040,7 +1040,9 @@ export default class FrontendModelController extends Controller {
       resourceConfiguration: frontendModelResource.resourceConfiguration
     }
 
-    return new frontendModelResource.resourceClass(resourceArgs)
+    const ResourceClass = frontendModelResourceInternalConstructor(frontendModelResource.resourceClass)
+
+    return new ResourceClass(resourceArgs)
   }
 
   /**
@@ -2908,7 +2910,9 @@ export default class FrontendModelController extends Controller {
         const resourceClass = resourceDefinition ? frontendModelResourceClassFromDefinition(resourceDefinition) : null
 
         if (resourceClass) {
-          resource = new resourceClass({
+          const ResourceClass = frontendModelResourceInternalConstructor(resourceClass)
+
+          resource = new ResourceClass({
             ability: this.currentAbility(),
             // Propagate the controller so a related/preloaded model's serialization
             // resource can use request context (e.g. `requestBaseUrl()` for signed
@@ -3985,7 +3989,8 @@ export default class FrontendModelController extends Controller {
 
     if (!frontendModelResource) throw frontendSyncReplaySafeError(`Sync replay model is not enabled: ${mutation.model}`)
 
-    const resource = new frontendModelResource.resourceClass({
+    const ResourceClass = frontendModelResourceInternalConstructor(frontendModelResource.resourceClass)
+    const resource = new ResourceClass({
       ability: this.currentAbility(),
       controller: this,
       context: {