velocious 1.0.577 → 1.0.579

package/src/sync/conflict-strategy.js

@@ -21,7 +21,7 @@ const CONFLICT_STRATEGIES = new Set(["optimisticVersion", "serverWins", "lastWri
  * Evaluates a replay mutation against server/base state using a sync conflict strategy.
  * @param {object} args - Arguments.
  * @param {SyncConflictRecord | null} [args.baseRecord] - Record state observed when the mutation was made.
- * @param {function(object): (SyncConflictResult | Promise<SyncConflictResult>)} [args.customHandler] - Resource-specific conflict hook.
+ * @param {(arg: object) => (SyncConflictResult | Promise<SyncConflictResult>)} [args.customHandler] - Resource-specific conflict hook.
  * @param {import("./device-identity.js").SyncMutation} args.mutation - Replayed mutation.
  * @param {SyncConflictRecord | null} [args.serverRecord] - Current authoritative server record.
  * @param {string} [args.strategy] - Conflict strategy.

package/src/sync/query-scope.js

@@ -9,7 +9,7 @@ import stableJsonStringify from "./stable-json.js"
  * expressible as `{resourceType, conditions}` so servers can match it against
  * their change feeds. Anything else (raw SQL, negations, joins, orders,
  * limits, offsets, groups) fails loudly.
- * @param {import("../database/query/model-class-query.js").default<?>} query - Model query declaring the sync scope.
+ * @param {import("../database/query/model-class-query.js").default<ReturnType<typeof JSON.parse>>} query - Model query declaring the sync scope.
  * @returns {import("./sync-client-types.js").SerializedSyncScope} Serialized sync scope.
  */
 export function serializedScopeFromQuery(query) {
@@ -20,12 +20,12 @@ export function serializedScopeFromQuery(query) {
   if (query.getGroups().length > 0) throw new Error("sync(query) does not support groups")
 
   const modelClass = query.getModelClass()
-  const conditions = /** @type {Record<string, ?>} */ ({})
+  const conditions = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ ({})
 
   for (const where of query.getWheres()) {
-    const whereHash = /** @type {{hash?: Record<string, ?>}} */ (where).hash
+    const whereHash = /** @type {{hash?: Record<string, ReturnType<typeof JSON.parse>>}} */ (where).hash
 
-    if (!whereHash || typeof whereHash !== "object" || Array.isArray(whereHash) || /** @type {{where?: ?}} */ (where).where) {
+    if (!whereHash || typeof whereHash !== "object" || Array.isArray(whereHash) || /** @type {{where?: ReturnType<typeof JSON.parse>}} */ (where).where) {
       throw new Error(`sync(query) only supports plain attribute conditions, got: ${where.constructor.name}`)
     }
 
@@ -67,8 +67,8 @@ export function scopeKey(scope) {
 /**
  * Validates one scope condition value as a scalar or array of scalars.
  * @param {string} attributeName - Condition attribute name for error messages.
- * @param {?} value - Condition value.
- * @returns {?} Validated condition value.
+ * @param {ReturnType<typeof JSON.parse>} value - Condition value.
+ * @returns {ReturnType<typeof JSON.parse>} Validated condition value.
  */
 function scalarConditionValue(attributeName, value) {
   if (Array.isArray(value)) {
@@ -85,7 +85,7 @@ function scalarConditionValue(attributeName, value) {
 /**
  * Validates one scalar condition value.
  * @param {string} attributeName - Condition attribute name for error messages.
- * @param {?} value - Condition value.
+ * @param {ReturnType<typeof JSON.parse>} value - Condition value.
  * @returns {void}
  */
 function validateScalar(attributeName, value) {

package/src/sync/server-change-feed.js

@@ -8,16 +8,16 @@ import stableJsonStringify from "./stable-json.js"
  * @typedef {object} ServerChangeFeedEntry
  * @property {string | null} actorDeviceId - Signed mutation actor device id when available.
  * @property {string | null} actorUserId - Signed mutation actor user id when available.
- * @property {Record<string, ?> | null} attributes - Serialized mutation attributes.
+ * @property {Record<string, ReturnType<typeof JSON.parse>> | null} attributes - Serialized mutation attributes.
  * @property {string} createdAt - Server change creation timestamp.
  * @property {string} id - Server change id.
  * @property {string | null} idempotencyKey - Mutation idempotency key when available.
  * @property {string} model - Frontend model name.
  * @property {string} operation - Mutation operation.
- * @property {Record<string, ?> | null} payload - Serialized mutation payload.
+ * @property {Record<string, ReturnType<typeof JSON.parse>> | null} payload - Serialized mutation payload.
  * @property {string | null} recordId - Changed record id when known.
- * @property {Record<string, ?> | null} response - Command response payload.
- * @property {Record<string, ?> | null} scope - Offline grant scope.
+ * @property {Record<string, ReturnType<typeof JSON.parse>> | null} response - Command response payload.
+ * @property {Record<string, ReturnType<typeof JSON.parse>> | null} scope - Offline grant scope.
  * @property {number} serverSequence - Monotonic server sequence.
  */
 /**
@@ -188,7 +188,7 @@ export default class ServerChangeFeedStore {
    * @param {number} args.afterSequence - Exclusive lower bound.
    * @param {number} [args.limit] - Maximum number of changes.
    * @param {number} [args.upToSequence] - Inclusive upper bound.
-   * @param {Record<string, ?>} [args.scope] - Caller sync scope.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} [args.scope] - Caller sync scope.
    * @returns {Promise<{changes: ServerChangeFeedEntry[], hasMore: boolean, nextSequence: number, oldestSequence: number | null, snapshotRequired: boolean, upToSequence: number}>} - Ordered page.
    */
   async changesAfter({afterSequence, limit = DEFAULT_PAGE_SIZE, scope, upToSequence}) {
@@ -424,7 +424,7 @@ export default class ServerChangeFeedStore {
    * @param {number} args.afterSequence - Exclusive lower bound.
    * @param {number} args.limit - Page size.
    * @param {number} [args.upToSequence] - Inclusive upper bound.
-   * @param {Record<string, ?>} [args.scope] - Caller sync scope.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} [args.scope] - Caller sync scope.
    * @returns {{changes: ServerChangeFeedEntry[], hasMore: boolean, nextSequence: number, oldestSequence: number | null, snapshotRequired: boolean, upToSequence: number}} - Ordered page.
    */
   _memoryChangesAfter({afterSequence, limit, scope, upToSequence}) {
@@ -448,8 +448,8 @@ export default class ServerChangeFeedStore {
 
   /**
    * Runs with db.
-   * @param {(db: import("../database/drivers/base.js").default) => Promise<?>} callback - Callback.
-   * @returns {Promise<?>} - Callback result.
+   * @param {(db: import("../database/drivers/base.js").default) => Promise<ReturnType<typeof JSON.parse>>} callback - Callback.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - Callback result.
    */
   async _withDb(callback) {
     return await this.configuration.ensureConnections({databaseIdentifiers: [this.databaseIdentifier], name: "Server change-feed store"}, async (dbs) => {
@@ -464,7 +464,7 @@ export default class ServerChangeFeedStore {
 
 /**
  * Normalizes page limit.
- * @param {?} limit - Requested limit.
+ * @param {ReturnType<typeof JSON.parse>} limit - Requested limit.
  * @returns {number} - Page size.
  */
 function normalizeLimit(limit) {
@@ -476,8 +476,8 @@ function normalizeLimit(limit) {
 
 /**
  * Parses JSON-ish values.
- * @param {?} value - JSON string.
- * @returns {?} - Parsed value.
+ * @param {ReturnType<typeof JSON.parse>} value - JSON string.
+ * @returns {ReturnType<typeof JSON.parse>} - Parsed value.
  */
 function parseJsonOrNull(value) {
   if (typeof value !== "string" || value.length < 1) return null
@@ -487,8 +487,8 @@ function parseJsonOrNull(value) {
 
 /**
  * Compares sync scopes by stable JSON representation.
- * @param {Record<string, ?> | null} changeScope - Persisted change scope.
- * @param {Record<string, ?> | undefined} requestedScope - Caller scope.
+ * @param {Record<string, ReturnType<typeof JSON.parse>> | null} changeScope - Persisted change scope.
+ * @param {Record<string, ReturnType<typeof JSON.parse>> | undefined} requestedScope - Caller scope.
  * @returns {boolean} - Whether the change is visible for the requested scope.
  */
 function scopesEqual(changeScope, requestedScope) {

package/src/sync/server-sequence-allocator.js

@@ -28,7 +28,7 @@ export default class ServerSequenceAllocator {
    * @param {object} [args] - Options.
    * @param {import("../configuration.js").default} [args.configuration] - Configuration owning the database. Defaults to the current configuration, resolved lazily per allocation.
    * @param {string} [args.databaseIdentifier] - Database identifier.
-   * @param {Record<string, ?>} [args.insertData] - Row payload inserted per allocation. Defaults to `{created_at: new Date()}` matching the auto-created table; pass `{}` for bare id-only tables.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} [args.insertData] - Row payload inserted per allocation. Defaults to `{created_at: new Date()}` matching the auto-created table; pass `{}` for bare id-only tables.
    * @param {string} [args.tableName] - Sequence table name.
    */
   constructor({configuration, databaseIdentifier = "default", insertData, tableName = "velocious_server_sequences"} = {}) {
@@ -158,7 +158,7 @@ export default class ServerSequenceAllocator {
 
   /**
    * Builds the row payload inserted per allocation.
-   * @returns {Record<string, ?>} Insert payload.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} Insert payload.
    */
   _insertPayload() {
     return this.insertData ?? {created_at: new Date()}
@@ -249,7 +249,7 @@ export function withServerSequence(ModelClass, {allocator, column = "serverSeque
   const setterMethodName = `set${upperColumn}`
 
   // Narrows the prototype to dynamic method access for the configured column name.
-  const prototype = /** @type {Record<string, ?>} */ (ModelClass.prototype)
+  const prototype = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (ModelClass.prototype)
 
   if (typeof prototype[setterMethodName] != "function" || typeof prototype[hasMethodName] != "function") {
     throw new Error(`withServerSequence requires generated ${setterMethodName} and ${hasMethodName} accessors on ${ModelClass.name}`)
@@ -258,7 +258,7 @@ export function withServerSequence(ModelClass, {allocator, column = "serverSeque
   if (typeof prototype[advanceMethodName] != "function") {
     /**
      * Assigns the next server-side sequence.
-     * @this {import("../database/record/index.js").default & Record<string, ?>}
+     * @this {import("../database/record/index.js").default & Record<string, ReturnType<typeof JSON.parse>>}
      * @returns {Promise<void>}
      */
     prototype[advanceMethodName] = async function advanceServerSequenceThroughAllocator() {
@@ -268,7 +268,7 @@ export function withServerSequence(ModelClass, {allocator, column = "serverSeque
 
   ModelClass.beforeCreate(async (record) => {
     // Narrows the record to dynamic method access for the configured column name.
-    const dynamicRecord = /** @type {Record<string, ?>} */ (/** @type {?} */ (record))
+    const dynamicRecord = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (/** @type {ReturnType<typeof JSON.parse>} */ (record))
 
     if (dynamicRecord[hasMethodName]()) return
 

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

@@ -35,8 +35,8 @@ export default class SignedSyncEnvelopeReplayService extends SyncEnvelopeReplayS
    * @param {import("./device-identity.js").SyncJsonWebKey} args.backendPublicKey - Backend public key used to verify device certificates.
    * @param {Array<import("./offline-grant.js").OfflineGrantSigningKey>} [args.offlineGrantSigningKeys] - Offline-grant verification keys.
    * @param {(userId: string) => Promise<{id: () => string} | null>} [args.actorLookup] - Optional lookup from grant user id to an actor object with an `id()` method. Defaults to a wrapper around the grant user id.
-   * @param {(args: {actor: ?, configuration: import("../configuration.js").default | null, grant: import("./offline-grant.js").OfflineGrant}) => Promise<import("../authorization/ability.js").default | null> | import("../authorization/ability.js").default | null} [args.abilityFactory] - Builds the actor/grant-scoped ability used to authorize routed resources. Required for routed signed replay; without it every routed sync fails closed.
-   * @param {Record<string, ?>} [args.rest] - Remaining arguments forwarded to {@link SyncEnvelopeReplayService}.
+   * @param {(args: {actor: ReturnType<typeof JSON.parse>, configuration: import("../configuration.js").default | null, grant: import("./offline-grant.js").OfflineGrant}) => Promise<import("../authorization/ability.js").default | null> | import("../authorization/ability.js").default | null} [args.abilityFactory] - Builds the actor/grant-scoped ability used to authorize routed resources. Required for routed signed replay; without it every routed sync fails closed.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} [args.rest] - Remaining arguments forwarded to {@link SyncEnvelopeReplayService}.
    */
   constructor({abilityFactory, backendPublicKey, offlineGrantSigningKeys, actorLookup, ...rest}) {
     super({
@@ -57,9 +57,9 @@ export default class SignedSyncEnvelopeReplayService extends SyncEnvelopeReplayS
    * derived sync envelopes. Verified actor, grant, and derived syncs are kept
    * in the request-local `requestState` object so concurrent replay calls on
    * one service instance cannot cross their authentication state.
-   * @param {Record<string, ?>} params - Request params.
-   * @param {Record<string, ?>} [requestState] - Request-local state shared with the base replay hooks.
-   * @returns {Promise<{syncs: Array<Record<string, ?>>}>} Replay response.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} params - Request params.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} [requestState] - Request-local state shared with the base replay hooks.
+   * @returns {Promise<{syncs: Array<Record<string, ReturnType<typeof JSON.parse>>>}>} Replay response.
    */
   async replay(params, requestState = {}) {
     const verified = await this.verifyAndTransformSignedReplay(params)
@@ -82,9 +82,9 @@ export default class SignedSyncEnvelopeReplayService extends SyncEnvelopeReplayS
 
   /**
    * Returns the verified actor prepared during {@link SignedSyncEnvelopeReplayService#replay}.
-   * @param {Record<string, ?>} _params - Request params.
-   * @param {Record<string, ?>} requestState - Request-local state.
-   * @returns {Promise<{authenticated: true, actor: ?} | {authenticated: false, errorCode: string, errorMessage: string}>} Auth result.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} _params - Request params.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} requestState - Request-local state.
+   * @returns {Promise<{authenticated: true, actor: ReturnType<typeof JSON.parse>} | {authenticated: false, errorCode: string, errorMessage: string}>} Auth result.
    */
   async authenticateReplay(_params, requestState) {
     const actor = requestState?.signedReplayActor
@@ -102,9 +102,9 @@ export default class SignedSyncEnvelopeReplayService extends SyncEnvelopeReplayS
 
   /**
    * Returns the sync envelopes derived from the verified signed mutations.
-   * @param {Record<string, ?>} _params - Request params.
-   * @param {Record<string, ?>} requestState - Request-local state.
-   * @returns {Array<Record<string, ?>>} Sync envelopes.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} _params - Request params.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} requestState - Request-local state.
+   * @returns {Array<Record<string, ReturnType<typeof JSON.parse>>>} Sync envelopes.
    */
   replaySyncs(_params, requestState) {
     return requestState?.signedReplaySyncs || []
@@ -114,8 +114,8 @@ export default class SignedSyncEnvelopeReplayService extends SyncEnvelopeReplayS
    * Builds the replay context carrying the verified signed actor and grant
    * (with its scopes) plus the offline runtime marker, so resource hooks and
    * ability factories authorize against the signer instead of the uploader.
-   * @param {{actor: ?, params: Record<string, ?>, requestState: Record<string, ?>}} args - Actor, request params, and request-local state.
-   * @returns {Promise<Record<string, ?>>} Replay context.
+   * @param {{actor: ReturnType<typeof JSON.parse>, params: Record<string, ReturnType<typeof JSON.parse>>, requestState: Record<string, ReturnType<typeof JSON.parse>>}} args - Actor, request params, and request-local state.
+   * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>>} Replay context.
    */
   async buildReplayContext({actor, requestState}) {
     const grant = /** @type {import("./offline-grant.js").OfflineGrant | undefined} */ (requestState?.signedReplayGrant)
@@ -133,8 +133,8 @@ export default class SignedSyncEnvelopeReplayService extends SyncEnvelopeReplayS
    * grant through the configured `abilityFactory`. The constructor-wide
    * uploader ability is never used for signed replay: without a factory (or a
    * factory result) every routed sync fails closed with a client-safe error.
-   * @param {{actor: ?, context: Record<string, ?>}} args - Verified actor and replay context.
-   * @returns {Promise<{ability: import("../authorization/ability.js").default, abilityContext: Record<string, ?>}>} Scoped ability and resource context.
+   * @param {{actor: ReturnType<typeof JSON.parse>, context: Record<string, ReturnType<typeof JSON.parse>>}} args - Verified actor and replay context.
+   * @returns {Promise<{ability: import("../authorization/ability.js").default, abilityContext: Record<string, ReturnType<typeof JSON.parse>>}>} Scoped ability and resource context.
    */
   async replayAbilityFor({actor, context}) {
     const grant = /** @type {import("./offline-grant.js").OfflineGrant} */ (context.offlineGrant)
@@ -153,8 +153,8 @@ export default class SignedSyncEnvelopeReplayService extends SyncEnvelopeReplayS
    * Verifies every signed mutation, its offline grant, and the actor/grant
    * consistency, then transforms the envelopes into the sync format the base
    * replay service understands.
-   * @param {Record<string, ?>} params - Request params.
-   * @returns {Promise<{actor: ?, grant: import("./offline-grant.js").OfflineGrant, syncs: Array<Record<string, ?>>}>} Verified actor, common grant, and derived syncs.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} params - Request params.
+   * @returns {Promise<{actor: ReturnType<typeof JSON.parse>, grant: import("./offline-grant.js").OfflineGrant, syncs: Array<Record<string, ReturnType<typeof JSON.parse>>>}>} Verified actor, common grant, and derived syncs.
    */
   async verifyAndTransformSignedReplay(params) {
     const rawEntries = Array.isArray(params.signedMutations) ? params.signedMutations : []
@@ -175,7 +175,7 @@ export default class SignedSyncEnvelopeReplayService extends SyncEnvelopeReplayS
     let grantId = null
     /** @type {import("./offline-grant.js").OfflineGrant | null} */
     let commonGrant = null
-    /** @type {Array<Record<string, ?>>} */
+    /** @type {Array<Record<string, ReturnType<typeof JSON.parse>>>} */
     const syncs = []
 
     for (const rawEntry of rawEntries) {
@@ -285,7 +285,7 @@ export default class SignedSyncEnvelopeReplayService extends SyncEnvelopeReplayS
    * @returns {void} Throws a client-safe error when the grant does not authorize the mutation.
    */
   validateGrantAgainstSyncPolicy({mutation, offlineGrant, syncManifest}) {
-    const grantResource = /** @type {Record<string, ?> | undefined} */ (offlineGrant.resources[mutation.model])
+    const grantResource = /** @type {Record<string, ReturnType<typeof JSON.parse>> | undefined} */ (offlineGrant.resources[mutation.model])
     const grantOperations = Array.isArray(grantResource?.operations) ? grantResource.operations : []
     const grantPolicyHash = grantResource?.policyHash
 
@@ -309,7 +309,7 @@ export default class SignedSyncEnvelopeReplayService extends SyncEnvelopeReplayS
   /**
    * Transforms a verified signed mutation into a generic sync envelope.
    * @param {{mutation: import("./device-identity.js").SyncMutation}} args - Transform args.
-   * @returns {Record<string, ?>} Sync envelope.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} Sync envelope.
    */
   syncFromSignedMutation({mutation}) {
     const operation = mutation.operation

package/src/sync/stable-json.js

@@ -4,7 +4,7 @@
  * Serializes a JSON-compatible value with recursively sorted object keys, so
  * equal values always produce byte-identical strings (used for sync scope and
  * change-feed identity comparisons).
- * @param {?} value - JSON-compatible value.
+ * @param {ReturnType<typeof JSON.parse>} value - JSON-compatible value.
  * @returns {string} - Stable JSON string.
  */
 export default function stableJsonStringify(value) {
@@ -13,8 +13,8 @@ export default function stableJsonStringify(value) {
 
 /**
  * Produces a recursively key-sorted JSON value.
- * @param {?} value - JSON-compatible value.
- * @returns {?} - Stable JSON-compatible value.
+ * @param {ReturnType<typeof JSON.parse>} value - JSON-compatible value.
+ * @returns {ReturnType<typeof JSON.parse>} - Stable JSON-compatible value.
  */
 function stableJsonValue(value) {
   if (Array.isArray(value)) return value.map((item) => stableJsonValue(item))
@@ -24,5 +24,5 @@ function stableJsonValue(value) {
     memo[key] = stableJsonValue(value[key])
 
     return memo
-  }, /** @type {Record<string, ?>} */ ({}))
+  }, /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ ({}))
 }

package/src/sync/sync-api-client-types.js

@@ -23,12 +23,12 @@
 
 /**
  * @typedef {object} SyncResourceConfig
- * @property {(args: {attributes: Record<string, unknown>, data: Record<string, unknown>, record: ?, sync: SyncChangeEnvelope}) => Promise<boolean | void> | boolean | void} [afterApply] - Optional post-save hook.
- * @property {(args: {data: Record<string, unknown>, record: ?, sync: SyncChangeEnvelope}) => Promise<Record<string, unknown>> | Record<string, unknown>} attributes - Allowed attributes builder.
+ * @property {(args: {attributes: Record<string, unknown>, data: Record<string, unknown>, record: ReturnType<typeof JSON.parse>, sync: SyncChangeEnvelope}) => Promise<boolean | void> | boolean | void} [afterApply] - Optional post-save hook.
+ * @property {(args: {data: Record<string, unknown>, record: ReturnType<typeof JSON.parse>, sync: SyncChangeEnvelope}) => Promise<Record<string, unknown>> | Record<string, unknown>} attributes - Allowed attributes builder.
  * @property {boolean} enabled - Whether this resource is sync-enabled.
- * @property {(args: {data: Record<string, unknown>, resourceId: unknown, sync: SyncChangeEnvelope}) => Promise<?> | ?} [findRecord] - Optional upsert finder.
- * @property {(args: {resourceId: unknown, sync: SyncChangeEnvelope}) => Promise<?> | ?} [findRecordForDelete] - Optional destroy finder.
- * @property {?} modelClass - Velocious model class.
+ * @property {(args: {data: Record<string, unknown>, resourceId: unknown, sync: SyncChangeEnvelope}) => Promise<ReturnType<typeof JSON.parse>> | ReturnType<typeof JSON.parse>} [findRecord] - Optional upsert finder.
+ * @property {(args: {resourceId: unknown, sync: SyncChangeEnvelope}) => Promise<ReturnType<typeof JSON.parse>> | ReturnType<typeof JSON.parse>} [findRecordForDelete] - Optional destroy finder.
+ * @property {ReturnType<typeof JSON.parse>} modelClass - Velocious model class.
  */
 
 /**
@@ -46,11 +46,11 @@
 /**
  * @typedef {object} SyncChangesResponse
  * @property {string} [errorMessage] - Error message.
- * @property {SyncCursor | Record<string, ?>} [nextCursor] - Next cursor.
+ * @property {SyncCursor | Record<string, ReturnType<typeof JSON.parse>>} [nextCursor] - Next cursor.
  * @property {string} [status] - Response status.
  * @property {Array<unknown>} [syncs] - Sync rows.
  * @property {number} [total] - Total pending change count for the scope from the request cursor (additive; absent on older servers).
- * @property {SyncCursor | Record<string, ?>} [upToCursor] - Snapshot upper-bound cursor.
+ * @property {SyncCursor | Record<string, ReturnType<typeof JSON.parse>>} [upToCursor] - Snapshot upper-bound cursor.
  */
 
 /**

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

@@ -52,7 +52,7 @@ export default class SyncApiClient {
    * @param {object} args - Pull args.
    * @param {string} args.authenticationToken - Auth token to send with change requests.
    * @param {number} [args.batchSize] - Max syncs per request.
-   * @param {?} args.cursorModel - Model that responds to findBy/findOrInitializeBy for cursor persistence.
+   * @param {ReturnType<typeof JSON.parse>} args.cursorModel - Model that responds to findBy/findOrInitializeBy for cursor persistence.
    * @param {string} args.cursorKey - Cursor option key.
    * @param {(payload: SyncChangesRequest) => Promise<SyncChangesResponse>} args.postChanges - Posts one changes request.
    * @param {Record<string, SyncResourceConfig>} args.resources - Resource policies.
@@ -73,7 +73,7 @@ export default class SyncApiClient {
 
   /**
    * Loads a persisted sync cursor from a model row with a value column.
-   * @param {{cursorKey: string, cursorModel: ?}} args - Cursor args.
+   * @param {{cursorKey: string, cursorModel: ReturnType<typeof JSON.parse>}} args - Cursor args.
    * @returns {Promise<string | null>} Persisted cursor payload.
    */
   static async loadSyncCursor({cursorKey, cursorModel}) {
@@ -84,7 +84,7 @@ export default class SyncApiClient {
 
   /**
    * Saves a persisted sync cursor to a model row with a value column.
-   * @param {{cursor: SyncCursor, cursorKey: string, cursorModel: ?}} args - Cursor args.
+   * @param {{cursor: SyncCursor, cursorKey: string, cursorModel: ReturnType<typeof JSON.parse>}} args - Cursor args.
    * @returns {Promise<void>}
    */
   static async saveSyncCursor({cursor, cursorKey, cursorModel}) {
@@ -232,7 +232,7 @@ export default class SyncApiClient {
 
   /**
    * Parses a persisted or response cursor payload.
-   * @param {SyncCursor | string | Record<string, ?> | null | undefined} payload - Cursor payload.
+   * @param {SyncCursor | string | Record<string, ReturnType<typeof JSON.parse>> | null | undefined} payload - Cursor payload.
    * @returns {SyncCursor} Parsed cursor.
    */
   static syncCursorFromPayload(payload) {
@@ -261,13 +261,13 @@ export default class SyncApiClient {
 
   /**
    * Builds a normalized sync row adapter.
-   * @param {?} payload - Raw sync payload.
+   * @param {ReturnType<typeof JSON.parse>} payload - Raw sync payload.
    * @returns {SyncChangeEnvelope} Sync row adapter.
    */
   static syncEnvelopeFromPayload(payload) {
     if (!payload || typeof payload !== "object" || Array.isArray(payload)) throw new Error("Sync changes entry must be an object")
 
-    const syncPayload = /** @type {Record<string, ?>} */ (payload)
+    const syncPayload = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (payload)
 
     return {
       data: () => syncPayload.data,
@@ -283,7 +283,7 @@ export default class SyncApiClient {
    * mechanics stay here; apps only declare which models/attributes/hooks are
    * allowed for each resource type.
    * @param {Record<string, SyncResourceConfig>} resources - Resource policy map.
-   * @param {(record: ?) => () => void} [onRecord] - Called with each record about to be written; returns a release callback invoked after the write (used for echo suppression).
+   * @param {(record: ReturnType<typeof JSON.parse>) => () => void} [onRecord] - Called with each record about to be written; returns a release callback invoked after the write (used for echo suppression).
    * @returns {(sync: SyncChangeEnvelope) => Promise<SyncChangeApplyResult>} Sync apply callback.
    */
   static resourceApplier(resources, onRecord) {
@@ -292,7 +292,7 @@ export default class SyncApiClient {
 
   /**
    * Applies one sync row using declarative resource policy.
-   * @param {{resources: Record<string, SyncResourceConfig>, sync: SyncChangeEnvelope, onRecord?: (record: ?) => () => void}} args - Apply args.
+   * @param {{resources: Record<string, SyncResourceConfig>, sync: SyncChangeEnvelope, onRecord?: (record: ReturnType<typeof JSON.parse>) => () => void}} args - Apply args.
    * @returns {Promise<SyncChangeApplyResult>} Apply result.
    */
   static async applyResourceSync({onRecord, resources, sync}) {
@@ -333,7 +333,7 @@ export default class SyncApiClient {
 
   /**
    * Destroys a synced resource via its declared model policy.
-   * @param {{resource: SyncResourceConfig, sync: SyncChangeEnvelope, onRecord?: (record: ?) => () => void}} args - Destroy args.
+   * @param {{resource: SyncResourceConfig, sync: SyncChangeEnvelope, onRecord?: (record: ReturnType<typeof JSON.parse>) => () => void}} args - Destroy args.
    * @returns {Promise<boolean>} Whether a local row was destroyed.
    */
   static async destroySyncedResource({onRecord, resource, sync}) {
@@ -373,8 +373,8 @@ export default class SyncApiClient {
    * @param {object} args - Replay args.
    * @param {string} args.authenticationToken - Auth token to send with replay requests.
    * @param {number} [args.batchSize] - Max syncs per request.
-   * @param {?} args.syncModel - Local Sync model class.
-   * @param {(payload: {authenticationToken: string, syncs: Array<Record<string, ?>>}) => Promise<SyncReplayResponse>} args.postReplay - Replay poster.
+   * @param {ReturnType<typeof JSON.parse>} args.syncModel - Local Sync model class.
+   * @param {(payload: {authenticationToken: string, syncs: Array<Record<string, ReturnType<typeof JSON.parse>>>}) => Promise<SyncReplayResponse>} args.postReplay - Replay poster.
    * @returns {Promise<void>}
    */
   static async replayLocalSyncs(args) {
@@ -409,7 +409,7 @@ export default class SyncApiClient {
 
   /**
    * Serializes the replay-relevant state of a local sync row for in-flight comparisons.
-   * @param {?} sync - Local sync row.
+   * @param {ReturnType<typeof JSON.parse>} sync - Local sync row.
    * @returns {string} Stable snapshot of the row's replayed payload.
    */
   static localSyncReplaySnapshot(sync) {
@@ -418,7 +418,7 @@ export default class SyncApiClient {
 
   /**
    * Builds one replay envelope from a local sync row.
-   * @param {?} sync - Local sync row.
+   * @param {ReturnType<typeof JSON.parse>} sync - Local sync row.
    * @returns {{clientUpdatedAt?: string, data: Record<string, unknown>, id: number, resourceId: string, resourceType: string, syncType: string}} Sync replay envelope.
    */
   static localSyncPayload(sync) {
@@ -436,7 +436,7 @@ export default class SyncApiClient {
 
   /**
    * Resolves one local sync row payload, falling back to preloaded resource attributes.
-   * @param {?} sync - Local sync row.
+   * @param {ReturnType<typeof JSON.parse>} sync - Local sync row.
    * @returns {Record<string, unknown>} Sync data.
    */
   static localSyncData(sync) {
@@ -462,14 +462,14 @@ export default class SyncApiClient {
   /**
    * Queues a local sync row for a Velocious model resource.
    * @param {object} args - Queue args.
-   * @param {?} args.resource - Resource being synced.
-   * @param {?} args.syncModel - Local Sync model class.
+   * @param {ReturnType<typeof JSON.parse>} args.resource - Resource being synced.
+   * @param {ReturnType<typeof JSON.parse>} args.syncModel - Local Sync model class.
    * @param {Record<string, unknown>} [args.data] - Explicit sync data.
    * @param {string} [args.syncType] - Sync operation type.
    * @param {string[]} [args.localOnlyAttributes] - Attributes to strip from queued payloads.
    * @param {string[]} [args.booleanAttributes] - Attributes to coerce through sync boolean parsing.
    * @param {(data: Record<string, unknown>) => Record<string, unknown>} [args.normalizeData] - App-specific data normalizer.
-   * @returns {Promise<?>} Local sync row.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} Local sync row.
    */
   static async queueLocalSync(args) {
     const resourceRecordId = args.resource.id()
@@ -512,7 +512,7 @@ export default class SyncApiClient {
    * (no explicit `data`) is the resource's attributes minus local-only attributes,
    * with booleans coerced and Date values serialized to ISO strings, so apps don't
    * need per-model tracked-payload builders.
-   * @param {{resource: ?, data?: Record<string, unknown>, localOnlyAttributes?: string[], booleanAttributes?: string[], normalizeData?: (data: Record<string, unknown>) => Record<string, unknown>}} args - Data args.
+   * @param {{resource: ReturnType<typeof JSON.parse>, data?: Record<string, unknown>, localOnlyAttributes?: string[], booleanAttributes?: string[], normalizeData?: (data: Record<string, unknown>) => Record<string, unknown>}} args - Data args.
    * @returns {Record<string, unknown>} Queued data.
    */
   static queuedSyncData(args) {
@@ -534,12 +534,12 @@ export default class SyncApiClient {
   /**
    * Builds a small app-facing local sync queue facade from declarative model config.
    * @param {object} args - Queue config.
-   * @param {?} args.syncModel - Local Sync model class.
+   * @param {ReturnType<typeof JSON.parse>} args.syncModel - Local Sync model class.
    * @param {string} args.singleFlightKey - Key used to serialize backend replay.
    * @param {() => Promise<void>} args.syncPending - Backend replay callback.
-   * @param {(resource: ?) => string[]} [args.localOnlyAttributes] - Resource-specific local-only attributes.
-   * @param {(resource: ?) => string[]} [args.booleanAttributes] - Resource-specific SQLite boolean attributes.
-   * @returns {{queue: (queueArgs: {resource: ?, data?: Record<string, unknown>, syncType?: string}) => Promise<?>, syncPending: () => Promise<void>}} Configured local sync queue.
+   * @param {(resource: ReturnType<typeof JSON.parse>) => string[]} [args.localOnlyAttributes] - Resource-specific local-only attributes.
+   * @param {(resource: ReturnType<typeof JSON.parse>) => string[]} [args.booleanAttributes] - Resource-specific SQLite boolean attributes.
+   * @returns {{queue: (queueArgs: {resource: ReturnType<typeof JSON.parse>, data?: Record<string, unknown>, syncType?: string}) => Promise<ReturnType<typeof JSON.parse>>, syncPending: () => Promise<void>}} Configured local sync queue.
    */
   static localSyncQueue(args) {
     return {
@@ -605,8 +605,8 @@ export default class SyncApiClient {
    * @param {number} [args.batchSize] - Max syncs per request. Defaults to 100.
    * @param {() => Promise<Array<unknown>>} args.pendingSyncs - Loads pending local sync rows in replay order.
    * @param {(sync: unknown) => string | number | null | undefined} args.syncId - Returns the local sync id.
-   * @param {(sync: unknown) => Record<string, ?>} args.syncPayload - Builds the API sync envelope.
-   * @param {(payload: {authenticationToken: string, syncs: Array<Record<string, ?>>}) => Promise<SyncReplayResponse>} args.postReplay - Posts one replay request.
+   * @param {(sync: unknown) => Record<string, ReturnType<typeof JSON.parse>>} args.syncPayload - Builds the API sync envelope.
+   * @param {(payload: {authenticationToken: string, syncs: Array<Record<string, ReturnType<typeof JSON.parse>>>}) => Promise<SyncReplayResponse>} args.postReplay - Posts one replay request.
    * @param {(sync: unknown, response: SyncReplayItem) => Promise<void>} args.markSuccessful - Marks one sync as successful locally.
    * @returns {Promise<void>} Resolves after all batches are replayed.
    */
@@ -625,8 +625,8 @@ export default class SyncApiClient {
    * @param {string} args.authenticationToken - Auth token.
    * @param {Array<unknown>} args.pendingSyncs - Batch syncs.
    * @param {(sync: unknown) => string | number | null | undefined} args.syncId - Sync id getter.
-   * @param {(sync: unknown) => Record<string, ?>} args.syncPayload - Payload builder.
-   * @param {(payload: {authenticationToken: string, syncs: Array<Record<string, ?>>}) => Promise<SyncReplayResponse>} args.postReplay - Replay poster.
+   * @param {(sync: unknown) => Record<string, ReturnType<typeof JSON.parse>>} args.syncPayload - Payload builder.
+   * @param {(payload: {authenticationToken: string, syncs: Array<Record<string, ReturnType<typeof JSON.parse>>>}) => Promise<SyncReplayResponse>} args.postReplay - Replay poster.
    * @param {(sync: unknown, response: SyncReplayItem) => Promise<void>} args.markSuccessful - Success hook.
    * @returns {Promise<void>} Resolves after the batch is acknowledged.
    */

package/src/sync/sync-change-fanout.js

@@ -5,11 +5,11 @@
  * replay service resolves it with replay args ({actor, applyResult, mutation,
  * ...}) and the sync publisher with publish args
  * ({@link import("./sync-publisher-types.js").SyncPublishBroadcastArgs}).
- * @template [Args=Record<string, ?>]
+ * @template [Args=Record<string, ReturnType<typeof JSON.parse>>]
  * @typedef {object} DeclaredBroadcast
  * @property {string | ((args: Args) => string)} channel - Channel name or resolver.
- * @property {(args: Args) => Record<string, ?>} broadcastParams - Channel routing params.
- * @property {(args: Args) => ?} body - Broadcast body.
+ * @property {(args: Args) => Record<string, ReturnType<typeof JSON.parse>>} broadcastParams - Channel routing params.
+ * @property {(args: Args) => ReturnType<typeof JSON.parse>} body - Broadcast body.
  * @property {(args: Args) => boolean} [when] - Optional gate; skipped when it returns false.
  */
 
@@ -21,8 +21,8 @@
  * (creates allocate their sequence through the model's own hooks). Shared by
  * the replay service's model-backed persistence and the server sync
  * publisher.
- * @param {{attributes: Record<string, ?>, existingSync: ?, syncModel: ?}} args - Row attributes, existing row for the resource identity, and the sync model.
- * @returns {Promise<?>} Upserted sync row.
+ * @param {{attributes: Record<string, ReturnType<typeof JSON.parse>>, existingSync: ReturnType<typeof JSON.parse>, syncModel: ReturnType<typeof JSON.parse>}} args - Row attributes, existing row for the resource identity, and the sync model.
+ * @returns {Promise<ReturnType<typeof JSON.parse>>} Upserted sync row.
  */
 export async function upsertSyncRow({attributes, existingSync, syncModel}) {
   if (existingSync) {
@@ -42,7 +42,7 @@ export async function upsertSyncRow({attributes, existingSync, syncModel}) {
  * from the caller's args. Shared by the replay service's default
  * afterReplayMutation and the server sync publisher.
  * @template Args
- * @param {{args: Args, broadcaster: (broadcast: {channel: string, params: Record<string, ?>, body: ?}) => Promise<void>, broadcasts: Array<DeclaredBroadcast<Args>>}} deliveryArgs - Broadcast resolver args, broadcaster, and declared broadcasts.
+ * @param {{args: Args, broadcaster: (broadcast: {channel: string, params: Record<string, ReturnType<typeof JSON.parse>>, body: ReturnType<typeof JSON.parse>}) => Promise<void>, broadcasts: Array<DeclaredBroadcast<Args>>}} deliveryArgs - Broadcast resolver args, broadcaster, and declared broadcasts.
  * @returns {Promise<void>}
  */
 export async function deliverDeclaredBroadcasts({args, broadcaster, broadcasts}) {

package/src/sync/sync-client-registry.js

@@ -7,12 +7,12 @@
  * delegate to a configured sync client without importing the sync stack.
  */
 
-/** @type {?} */
+/** @type {ReturnType<typeof JSON.parse>} */
 let currentClient = null
 
 /**
  * Registers the current sync client.
- * @param {?} client - Configured sync client (or null to clear).
+ * @param {ReturnType<typeof JSON.parse>} client - Configured sync client (or null to clear).
  * @returns {void}
  */
 export function setCurrentSyncClient(client) {
@@ -21,7 +21,7 @@ export function setCurrentSyncClient(client) {
 
 /**
  * Returns the current sync client.
- * @returns {?} Current sync client.
+ * @returns {ReturnType<typeof JSON.parse>} Current sync client.
  */
 export function currentSyncClient() {
   if (!currentClient) throw new Error("No sync client configured - create a SyncClient and call setCurrent() on it first")