velocious 1.0.642 → 1.0.644

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,11 +701,21 @@ 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
 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:
 
@@ -815,7 +825,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 +840,17 @@ 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. 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. 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:

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/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: {