velocious 1.0.642 → 1.0.644

package/src/sync/assets/types.js

@@ -0,0 +1,62 @@
+// @ts-check
+
+/**
+ * Immutable attachment descriptor synchronized separately from its bytes.
+ * @typedef {object} SynchronizedAssetCacheDescriptor
+ * @property {number} byteSize - Expected byte count.
+ * @property {string | null} contentType - Media type.
+ * @property {string} digest - Expected `sha256-<hex>` content digest.
+ * @property {"eager" | "on-demand"} fetch - Download timing policy.
+ * @property {string} filename - Original filename.
+ * @property {string} id - Immutable attachment id.
+ * @property {string} name - Attachment declaration name.
+ * @property {"optional" | "required"} offlineRequirement - Whether offline readiness requires the bytes.
+ * @property {string} recordId - Owner record id.
+ * @property {string} recordType - Owner model name.
+ * @property {"durable" | "evictable"} retention - Storage-pressure policy.
+ */
+
+/**
+ * Persisted state for one synchronized attachment descriptor.
+ * @typedef {object} SynchronizedAssetCacheEntry
+ * @property {number} attempts - Consecutive failed download count.
+ * @property {SynchronizedAssetCacheDescriptor} descriptor - Current immutable descriptor.
+ * @property {number} lastAccessedAt - Millisecond LRU timestamp.
+ * @property {number | null} nextRetryAt - Earliest automatic retry time.
+ * @property {string[]} scopeKeys - Synchronized scopes referencing the descriptor.
+ * @property {"cached" | "downloading" | "failed" | "missing"} status - Local byte state.
+ */
+
+/**
+ * Versioned persistent cache metadata owned by a platform adapter.
+ * @typedef {object} SynchronizedAssetCacheState
+ * @property {SynchronizedAssetCacheEntry[]} assets - Descriptor entries.
+ * @property {string[]} pendingDeletionDigests - Unreferenced blobs awaiting confirmed deletion.
+ * @property {1} version - State schema version.
+ */
+
+/**
+ * Platform storage adapter. `writeBlob` must make bytes visible atomically.
+ * @typedef {object} SynchronizedAssetCacheAdapter
+ * @property {(args: {accountId: string, digest: string}) => Promise<string | null>} blobUri - Resolves a locally stored blob URI.
+ * @property {(args: {accountId: string, digest: string}) => Promise<void>} deleteBlob - Deletes one local blob.
+ * @property {(args: {accountId: string}) => Promise<SynchronizedAssetCacheState | null>} loadState - Loads account-scoped metadata.
+ * @property {(args: {accountId: string, state: SynchronizedAssetCacheState}) => Promise<void>} saveState - Atomically saves account-scoped metadata.
+ * @property {(args: {accountId: string, bytes: Uint8Array, contentType: string | null, digest: string}) => Promise<string>} writeBlob - Atomically stores verified bytes.
+ */
+
+/**
+ * Failed asset result surfaced to the sync coordinator.
+ * @typedef {object} SynchronizedAssetCacheFailure
+ * @property {string} assetId - Descriptor id.
+ * @property {Error} error - Download or verification error.
+ */
+
+/**
+ * Descriptor reconciliation result.
+ * @typedef {object} SynchronizedAssetCacheSynchronizationResult
+ * @property {SynchronizedAssetCacheFailure[]} failures - Failed eligible eager downloads.
+ * @property {string[]} missingRequiredAssetIds - Required descriptors without cached bytes.
+ */
+
+export {}

package/src/sync/sync-api-controller.js

@@ -1,7 +1,7 @@
 // @ts-check
 
 import Controller from "../controller.js"
-import FrontendModelBaseResource from "../frontend-model-resource/base-resource.js"
+import FrontendModelBaseResource, {frontendModelResourceInternalConstructor} from "../frontend-model-resource/base-resource.js"
 
 /** Configurations whose sync.api routes have already been mounted. */
 const mountedConfigurations = new WeakSet()
@@ -41,9 +41,10 @@ export default class SyncApiController extends Controller {
    */
   syncResource(params) {
     const ResourceClass = this.syncResourceClass()
+    const ResourceConstructor = frontendModelResourceInternalConstructor(ResourceClass)
     const ability = this.currentAbility()
 
-    return new ResourceClass({
+    return new ResourceConstructor({
       ability,
       controller: /** @type {import("../frontend-model-resource/base-resource.js").FrontendModelResourceController} */ (/** @type {unknown} */ (this)),
       context: {
@@ -137,7 +138,7 @@ export default class SyncApiController extends Controller {
    * @returns {import("../configuration-types.js").FrontendModelResourceClassType} Sync resource class.
    */
   missingSyncResourceClass() {
-    return /** @type {typeof FrontendModelBaseResource} */ (/** @type {unknown} */ (this.raiseMissingSyncResourceClass()))
+    return /** @type {import("../configuration-types.js").FrontendModelResourceClassType} */ (/** @type {unknown} */ (this.raiseMissingSyncResourceClass()))
   }
 
   /** Raises a configuration error for subclasses that do not provide a resource. */
@@ -155,7 +156,7 @@ export default class SyncApiController extends Controller {
 
     if (!modelClass) throw new Error("Sync resource class must define static ModelClass")
 
-    return modelClass
+    return /** @type {typeof import("../database/record/index.js").default} */ (/** @type {unknown} */ (modelClass))
   }
 
   /**
@@ -178,4 +179,3 @@ export default class SyncApiController extends Controller {
     })
   }
 }
-

package/src/sync/sync-envelope-replay-service.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import {deliverDeclaredBroadcasts, upsertSyncRow} from "./sync-change-fanout.js"
+import {frontendModelResourceInternalConstructor} from "../frontend-model-resource/base-resource.js"
 import {markServerApply} from "./sync-publish-suppression.js"
 import {resolveFrontendModelResourceClass} from "../frontend-models/resource-definition.js"
 import {resolveSyncConflict} from "./conflict-strategy.js"
@@ -567,7 +568,7 @@ export default class SyncEnvelopeReplayService {
    * @returns {Promise<import("../frontend-model-resource/base-resource.js").default>} Routed resource instance.
    */
   async buildReplayResource({actor, context, mutation, registration}) {
-    const ResourceClass = registration.resourceClass
+    const ResourceClass = frontendModelResourceInternalConstructor(registration.resourceClass)
     const {ability, abilityContext} = await this.replayAbilityFor({actor, context})
 
     return new ResourceClass({

package/src/sync/sync-resource-base.js

@@ -38,6 +38,9 @@ const QUICK_SEARCH_COLUMN = "quickSearch"
  * @augments {FrontendModelBaseResource<TModelClass>}
  */
 export default class SyncResourceBase extends FrontendModelBaseResource {
+  /** @type {typeof import("../database/record/index.js").default | undefined} */
+  static ModelClass = undefined
+
   /**
    * Replay service class handling replay mutations for this resource,
    * declared instead of overriding {@link SyncResourceBase#replayServiceClass}.