velocious 1.0.643 → 1.0.645

package/build/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/build/sync/sync-api-client.js

@@ -3,6 +3,7 @@
 import {optionalBoolean, optionalInteger} from "typanic"
 
 import recordChanges from "../database/record-changes.js"
+import {scalarModelPrimaryKeyValue} from "../utils/model-primary-key.js"
 import {applySyncReplayResultToLocalMutationLog} from "./conflict-strategy.js"
 
 /** @typedef {import("./sync-api-client-types.js").SyncChangeApplyResult} SyncChangeApplyResult */
@@ -35,7 +36,7 @@ export default class SyncApiClient {
    * @returns {Promise<import("./local-mutation-log.js").LocalMutationLogRecord>} Appended intent.
    */
   static async queueConflictTrackedSync({baseVersion, conflictTracking, data, operation, resource, resourceType, syncType}) {
-    const resourceId = String(resource.id())
+    const resourceId = String(scalarModelPrimaryKeyValue(resource.id(), `Conflict-tracked sync for ${resourceType}`))
     const records = await conflictTracking.mutationLog.records()
     const predecessor = records
       .filter((record) => record.mutation.model === resourceType && record.mutation.payload?.resourceId === resourceId)
@@ -675,7 +676,7 @@ export default class SyncApiClient {
    * @returns {Promise<ReturnType<typeof JSON.parse>>} Local sync row.
    */
   static async queueLocalSync(args) {
-    const resourceRecordId = args.resource.id()
+    const resourceRecordId = scalarModelPrimaryKeyValue(args.resource.id(), "Local sync queueing")
     const modelClass = args.resource.constructor
 
     if (typeof modelClass.getModelName !== "function") {

package/build/sync/sync-client.js

@@ -4,6 +4,7 @@ import Configuration from "../configuration.js"
 import {isBooleanColumnType} from "../database/column-types.js"
 import Logger from "../logger.js"
 import {captureRemoteRequestContext, mergeRemoteRequestContext} from "../remote-request-context.js"
+import {scalarModelPrimaryKey} from "../utils/model-primary-key.js"
 import restArgsError from "../utils/rest-args-error.js"
 import VelociousWebsocketClient from "../http-client/websocket-client.js"
 
@@ -1243,7 +1244,7 @@ function derivedSyncAttributes({modelClass, resourceType}) {
   const localOnlyAttributes = []
 
   if (modelClass.hasPrimaryKey()) {
-    const primaryKeyColumn = modelClass.primaryKey()
+    const primaryKeyColumn = scalarModelPrimaryKey(modelClass.primaryKey(), `Derived sync attributes for ${resourceType}`)
 
     localOnlyAttributes.push(columnNameToAttributeName[primaryKeyColumn] || primaryKeyColumn)
   }

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

@@ -11,6 +11,7 @@ import sha256Hex from "../utils/sha256-hex.js"
 import {decodeReplayPersistedData, serializeReplayPersistedData} from "./sync-replay-persisted-data.js"
 import {ValidationError} from "../database/record/index.js"
 import VelociousError from "../velocious-error.js"
+import {scalarModelPrimaryKey, scalarModelPrimaryKeyValue} from "../utils/model-primary-key.js"
 
 /**
  * Resolved routed-resource registration for one replay resource type.
@@ -800,7 +801,7 @@ export default class SyncEnvelopeReplayService {
     if (mutation.baseVersion === undefined || mutation.baseVersion === null) return null
 
     const ModelClass = resource.modelClass()
-    const primaryKey = ModelClass.primaryKey()
+    const primaryKey = scalarModelPrimaryKey(ModelClass.primaryKey(), `Offline sync conflict handling for ${ModelClass.name}`)
     const primaryKeyAttribute = ModelClass.resolveAttributeName(primaryKey)
     const versionAttribute = this.conflictStrategy.versionAttribute
     const versionAttributeName = ModelClass.resolveAttributeName(versionAttribute)
@@ -944,7 +945,7 @@ export default class SyncEnvelopeReplayService {
       if (columnName) allowedKeys.add(columnName)
     }
 
-    const primaryKey = ModelClass.primaryKey()
+    const primaryKey = scalarModelPrimaryKey(ModelClass.primaryKey(), `Offline sync attribute filtering for ${ModelClass.name}`)
     const primaryKeyAttribute = ModelClass.getColumnNameToAttributeNameMap()[primaryKey]
 
     /** @type {Record<string, ReturnType<typeof JSON.parse>>} */
@@ -981,7 +982,7 @@ export default class SyncEnvelopeReplayService {
    */
   async createRoutedReplayRecord({attributes, mutation, resource}) {
     const ModelClass = resource.modelClass()
-    const primaryKey = ModelClass.primaryKey()
+    const primaryKey = scalarModelPrimaryKey(ModelClass.primaryKey(), `Offline sync create for ${ModelClass.name}`)
     const conflictingIds = await ModelClass.where({[primaryKey]: mutation.resourceId}).pluck(primaryKey)
 
     if (conflictingIds.length > 0) {
@@ -1007,7 +1008,7 @@ export default class SyncEnvelopeReplayService {
       if (ability) {
         const memberIds = await ModelClass
           .accessibleFor(resource.syncAbilityAction("create"), ability)
-          .where({[primaryKey]: record.id()})
+          .where({[primaryKey]: scalarModelPrimaryKeyValue(record.id(), `Offline sync create authorization for ${ModelClass.name}`)})
           .pluck(primaryKey)
 
         if (memberIds.length === 0) {

package/build/sync/sync-publisher.js

@@ -2,6 +2,7 @@
 
 import Configuration from "../configuration.js"
 import Logger from "../logger.js"
+import {scalarModelPrimaryKeyValue} from "../utils/model-primary-key.js"
 import restArgsError from "../utils/rest-args-error.js"
 
 import {declaredSyncScopeAttributes} from "./sync-scope-attributes.js"
@@ -190,7 +191,7 @@ export default class SyncPublisher {
       if (isPublishingSuppressed(record)) return
 
       const data = await resourceConfig.serialize(record)
-      const resourceId = String(record.id())
+      const resourceId = String(scalarModelPrimaryKeyValue(record.id(), `Sync publishing for ${resourceConfig.resourceType}`))
       const syncType = operation === "destroy" ? "delete" : "update"
       const scopeValues = await this.publishedScopeValues({record, resourceConfig})
       /** @type {Record<string, ReturnType<typeof JSON.parse>>} */
@@ -259,7 +260,7 @@ export default class SyncPublisher {
       } else if (scopePlanEntry.recordAttribute) {
         rawValue = record.readAttribute(scopePlanEntry.recordAttribute)
       } else {
-        rawValue = record.id()
+        rawValue = scalarModelPrimaryKeyValue(record.id(), `Sync scope publishing for ${resourceConfig.resourceType}`)
       }
 
       const value = rawValue === undefined || rawValue === null ? null : String(rawValue)

package/build/testing/browser-frontend-model-event-hook-scenarios.js

@@ -15,10 +15,10 @@ import wait from "awaitery/build/wait.js"
  * @typedef {import("../frontend-models/base.js").FrontendModelResourceConfig} FrontendModelResourceConfig */
 /**
  * Defines this typedef.
- * @typedef {{id: string, model: FrontendModelBase}} FrontendModelHookTestCreateUpdatePayload */
+ * @typedef {{id: string | import("../utils/model-primary-key.js").CompositeModelPrimaryKeyValue, model: FrontendModelBase}} FrontendModelHookTestCreateUpdatePayload */
 /**
  * Defines this typedef.
- * @typedef {{id: string}} FrontendModelHookTestDestroyPayload */
+ * @typedef {{id: string | import("../utils/model-primary-key.js").CompositeModelPrimaryKeyValue}} FrontendModelHookTestDestroyPayload */
 /**
  * FakeSubscriptions type.
  * @typedef {object} FakeSubscriptions

package/build/testing/test-profiler.js

@@ -172,7 +172,7 @@ export default class TestProfiler {
     this._spans = []
     /** @type {Array<{id: string, parentId: string | undefined, file: string, line: number | undefined}>} */
     this._scopes = []
-    /** @type {WeakMap<import("./test-runner.js").TestsArgument, string>} */
+    /** @type {WeakMap<import("./test-runner.js").TestsArgument | import("@velocious/testing/runner").SuiteDeclaration, string>} */
     this._scopeIds = new WeakMap()
     /** @type {Set<string>} */
     this._customActivityNames = new Set()
@@ -243,7 +243,7 @@ export default class TestProfiler {
 
   /**
    * Registers and returns a deterministic scope identifier.
-   * @param {import("./test-runner.js").TestsArgument} scope - Scope object.
+   * @param {import("./test-runner.js").TestsArgument | import("@velocious/testing/runner").SuiteDeclaration} scope - Scope object.
    * @param {object} args - Scope metadata.
    * @param {string[]} args.descriptions - Scope description path.
    * @param {string | undefined} args.filePath - Scope source path.