velocious 1.0.563 → 1.0.565

package/src/frontend-models/websocket-channel.js

@@ -4,6 +4,18 @@ import VelociousWebsocketChannel from "../http-server/websocket-channel.js"
 import Response from "../http-server/client/response.js"
 import {serializeFrontendModelTransportValue} from "./transport-serialization.js"
 
+/**
+ * Defines this typedef.
+ * @typedef {{action?: string, id?: string | number, matchedEventFilterKeys?: string[], record?: import("./query.js").FrontendModelTransportValue, [key: string]: import("./query.js").FrontendModelTransportValue | string[] | undefined}} FrontendModelLifecycleBroadcastBody
+ */
+/**
+ * Defines this typedef.
+ * @typedef {{headers?: () => Record<string, string | string[] | undefined>, remoteAddress?: () => string | undefined}} FrontendModelWebsocketUpgradeRequest
+ */
+/**
+ * Defines this typedef.
+ * @typedef {{headers: () => Record<string, string | string[] | undefined>, header: (name: string) => string | string[] | undefined, metadata: (key?: string) => Record<string, import("./query.js").FrontendModelTransportValue> | import("./query.js").FrontendModelTransportValue | undefined, path: () => string, httpMethod: () => string, remoteAddress: () => string | undefined, origin: () => string | string[] | undefined}} FrontendModelWebsocketSyntheticRequest
+ */
 const EVENT_FILTER_KEYS = new Set(["joins", "key", "searches", "where"])
 
 // Mirrors FRONTEND_MODELS_CHANNEL_NAME in ./websocket-publishers.js, duplicated here
@@ -21,19 +33,6 @@ function transportSerializationOptionsForConfiguration(configuration) {
   }
 }
 
-/**
- * Defines this typedef.
- * @typedef {{action?: string, id?: string | number, matchedEventFilterKeys?: string[], record?: import("./query.js").FrontendModelTransportValue, [key: string]: import("./query.js").FrontendModelTransportValue | string[] | undefined}} FrontendModelLifecycleBroadcastBody
- */
-/**
- * Defines this typedef.
- * @typedef {{headers?: () => Record<string, string | string[] | undefined>, remoteAddress?: () => string | undefined}} FrontendModelWebsocketUpgradeRequest
- */
-/**
- * Defines this typedef.
- * @typedef {{headers: () => Record<string, string | string[] | undefined>, header: (name: string) => string | string[] | undefined, metadata: (key?: string) => Record<string, import("./query.js").FrontendModelTransportValue> | import("./query.js").FrontendModelTransportValue | undefined, path: () => string, httpMethod: () => string, remoteAddress: () => string | undefined, origin: () => string | string[] | undefined}} FrontendModelWebsocketSyntheticRequest
- */
-
 /**
  * Per-session channel subscription for frontend-model lifecycle events.
  * Replaces the legacy `FrontendModelWebsocketChannel` (Phase 3).

package/src/http-server/client/websocket-session.js

@@ -9,6 +9,10 @@ import WebsocketRequest from "./websocket-request.js"
 import WebsocketChannel from "../websocket-channel.js"
 import {websocketEventLogStoreForConfiguration} from "../websocket-event-log-store.js"
 
+/**
+ * Defines this typedef.
+ * @typedef {{type: "subscribe", channel: string, lastEventId?: string, params?: Record<string, ?>} | {type: "metadata", data?: Record<string, ?>} | {type?: "request", body?: ?, headers?: Record<string, ?>, id?: string | number | null, method: string, path: string} | Record<string, ?>} WebsocketSessionMessage
+ */
 const WEBSOCKET_FINAL_FRAME = 0x80
 const WEBSOCKET_OPCODE_CONTINUATION = 0x0
 const WEBSOCKET_OPCODE_TEXT = 0x1
@@ -31,11 +35,6 @@ const WEBSOCKET_MAX_INBOUND_FRAME_BYTES_BIGINT = BigInt(WEBSOCKET_MAX_FINAL_FRAM
 /** Cap on fragment count for a single fragmented message. */
 const WEBSOCKET_MAX_FRAGMENTED_MESSAGE_FRAGMENTS = 1024
 
-/**
- * Defines this typedef.
- * @typedef {{type: "subscribe", channel: string, lastEventId?: string, params?: Record<string, ?>} | {type: "metadata", data?: Record<string, ?>} | {type?: "request", body?: ?, headers?: Record<string, ?>, id?: string | number | null, method: string, path: string} | Record<string, ?>} WebsocketSessionMessage
- */
-
 /**
  * Runs subscribe message.
  * @param {WebsocketSessionMessage} message - Raw websocket message.

package/src/http-server/client-delivery-queue.js

@@ -1,3 +1,10 @@
+/**
+ * @typedef {object} DeliveryTask
+ * @property {number} byteLength - Retained complete-buffer bytes.
+ * @property {boolean} countedFrame - Whether this task is an outbound frame.
+ * @property {() => Promise<void>} delivery - Delivery operation.
+ * @property {(error?: Error) => void} settle - Settles the enqueue promise.
+ */
 // @ts-check
 
 export class ClientDeliveryQueueOverflowError extends Error {
@@ -17,14 +24,6 @@ export class ClientDeliveryQueueOverflowError extends Error {
   }
 }
 
-/**
- * @typedef {object} DeliveryTask
- * @property {number} byteLength - Retained complete-buffer bytes.
- * @property {boolean} countedFrame - Whether this task is an outbound frame.
- * @property {() => Promise<void>} delivery - Delivery operation.
- * @property {(error?: Error) => void} settle - Settles the enqueue promise.
- */
-
 export default class ClientDeliveryQueue {
   /**
    * Builds a per-client delivery queue.

package/src/http-server/websocket-event-log-store.js

@@ -4,11 +4,6 @@ import {randomUUID} from "crypto"
 import TableData from "../database/table-data/index.js"
 import Logger from "../logger.js"
 
-const EVENTS_TABLE = "websocket_channel_events"
-const REPLAY_CHANNELS_TABLE = "websocket_replay_channels"
-const DEFAULT_RETENTION_MS = 10 * 60 * 1000
-const stores = new WeakMap()
-
 /**
  * WebsocketEventRow type.
  * @typedef {object} WebsocketEventRow
@@ -18,12 +13,15 @@ const stores = new WeakMap()
  * @property {string} payload_json - Serialized payload.
  * @property {number | string} sequence - Sequence number.
  */
-
 /**
  * WebsocketReplayChannelRow type.
  * @typedef {object} WebsocketReplayChannelRow
  * @property {string} channel - Channel name.
  */
+const EVENTS_TABLE = "websocket_channel_events"
+const REPLAY_CHANNELS_TABLE = "websocket_replay_channels"
+const DEFAULT_RETENTION_MS = 10 * 60 * 1000
+const stores = new WeakMap()
 
 /**
  * Runs the websocketEventLogStoreForConfiguration helper.

package/src/plugins/sqljs-wasm-route.js

@@ -2,23 +2,21 @@ import {createRequire} from "node:module"
 import path from "node:path"
 import SqlJsWasmRouteController from "./sqljs-wasm-route-controller.js"
 
-const require = createRequire(import.meta.url)
-const sqlJsEntryPath = require.resolve("sql.js")
-const sqlJsDistDirectory = path.dirname(sqlJsEntryPath)
-
 /**
  * InstallSqlJsWasmRouteArgs type.
  * @typedef {object} InstallSqlJsWasmRouteArgs
  * @property {import("../configuration.js").default} configuration - Velocious configuration instance.
  * @property {string} [routePrefix] - Route prefix used for sql.js asset serving.
  */
-
 /**
  * SqlJsLocateFileFromBackendArgs type.
  * @typedef {object} SqlJsLocateFileFromBackendArgs
  * @property {string} backendBaseUrl - Backend base URL (for example `https://api.example.com`).
  * @property {string} [routePrefix] - Route prefix used for sql.js asset serving.
  */
+const require = createRequire(import.meta.url)
+const sqlJsEntryPath = require.resolve("sql.js")
+const sqlJsDistDirectory = path.dirname(sqlJsEntryPath)
 
 /**
  * Runs normalize route prefix.

package/src/sync/conflict-strategy.js

@@ -1,17 +1,11 @@
-// @ts-check
-
-const CONFLICT_STRATEGIES = new Set(["optimisticVersion", "serverWins", "lastWriterWins", "fieldThreeWay", "appendOnly"])
-
 /**
  * @typedef {null | string | number | boolean | unknown[] | Record<string, unknown>} SyncJsonValue
  */
-
 /**
  * @typedef {object} SyncConflictRecord
  * @property {Record<string, SyncJsonValue>} attributes - Record attributes.
  * @property {string | number | boolean | null} [version] - Record version value.
  */
-
 /**
  * @typedef {object} SyncConflictResult
  * @property {Record<string, SyncJsonValue>} [attributes] - Attributes to apply when replay may continue.
@@ -19,6 +13,9 @@ const CONFLICT_STRATEGIES = new Set(["optimisticVersion", "serverWins", "lastWri
  * @property {"applied" | "conflict" | "rejected"} status - Conflict decision.
  * @property {string} strategy - Strategy that produced the decision.
  */
+// @ts-check
+
+const CONFLICT_STRATEGIES = new Set(["optimisticVersion", "serverWins", "lastWriterWins", "fieldThreeWay", "appendOnly"])
 
 /**
  * Evaluates a replay mutation against server/base state using a sync conflict strategy.

package/src/sync/device-identity.js

@@ -1,13 +1,7 @@
-// @ts-check
-
-const ECDSA_P256_SHA256_ALGORITHM = "ECDSA-P256-SHA256"
-const ECDSA_P256_SHA256_SIGNATURE_PREFIX = "ecdsa-p256-sha256-"
-
 /**
  * JSON Web Key used by the sync signing helpers.
  * @typedef {import("node:crypto").webcrypto.JsonWebKey} SyncJsonWebKey
  */
-
 /**
  * Backend-signed device certificate payload.
  * @typedef {object} DeviceCertificatePayload
@@ -18,7 +12,6 @@ const ECDSA_P256_SHA256_SIGNATURE_PREFIX = "ecdsa-p256-sha256-"
  * @property {string} expiresAt - ISO timestamp after which the certificate is invalid.
  * @property {string} issuedAt - ISO timestamp when the backend issued the certificate.
  */
-
 /**
  * Backend-signed device certificate envelope.
  * @typedef {object} DeviceCertificate
@@ -26,7 +19,6 @@ const ECDSA_P256_SHA256_SIGNATURE_PREFIX = "ecdsa-p256-sha256-"
  * @property {DeviceCertificatePayload} certificate - Certificate payload.
  * @property {string} signature - Backend signature over the certificate payload.
  */
-
 /**
  * Sync mutation payload signed by a device.
  * @typedef {object} SyncMutation
@@ -43,7 +35,6 @@ const ECDSA_P256_SHA256_SIGNATURE_PREFIX = "ecdsa-p256-sha256-"
  * @property {Record<string, import("../configuration-types.js").FrontendModelSyncJsonValue>} [payload] - Domain command payload.
  * @property {string} policyHash - Sync policy hash the mutation was checked against.
  */
-
 /**
  * Device-signed mutation envelope.
  * @typedef {object} SignedSyncMutation
@@ -52,6 +43,10 @@ const ECDSA_P256_SHA256_SIGNATURE_PREFIX = "ecdsa-p256-sha256-"
  * @property {SyncMutation} mutation - Mutation payload.
  * @property {string} signature - Device signature over the mutation envelope.
  */
+// @ts-check
+
+const ECDSA_P256_SHA256_ALGORITHM = "ECDSA-P256-SHA256"
+const ECDSA_P256_SHA256_SIGNATURE_PREFIX = "ecdsa-p256-sha256-"
 
 /**
  * Generates an ECDSA P-256 keypair exported as JWKs.

package/src/sync/local-mutation-log.js

@@ -1,19 +1,8 @@
-// @ts-check
-
-const DEFAULT_STORAGE_KEY = "velocious.sync.localMutationLog"
-const PENDING_STATUS_VALUES = /** @type {LocalMutationStatus[]} */ (["pending", "applied-locally", "peer-applied"])
-const PENDING_STATUSES = new Set(PENDING_STATUS_VALUES)
-const MUTATION_STATUSES = new Set([...PENDING_STATUSES, "conflict", "rejected", "synced"])
-const TERMINAL_STATUSES = new Set(["rejected", "synced"])
-/** @type {Map<string, Promise<unknown>>} */
-const STORAGE_KEY_LOCKS = new Map()
-
 /**
  * Local mutation log record query options.
  * @typedef {object} LocalMutationLogRecordsOptions
  * @property {LocalMutationStatus[]} [statuses] - Optional status filter.
  */
-
 /**
  * Local mutation log row-oriented storage adapter.
  *
@@ -28,19 +17,16 @@ const STORAGE_KEY_LOCKS = new Map()
  * @property {(storageKey: string, options?: LocalMutationLogRecordsOptions) => Promise<LocalMutationLogRecord[]> | LocalMutationLogRecord[]} records - Reads log records.
  * @property {(storageKey: string, record: LocalMutationLogRecord) => Promise<void> | void} updateRecord - Replaces one log record.
  */
-
 /**
  * Local sync mutation dependency metadata.
  * @typedef {object} LocalMutationDependency
  * @property {string} clientMutationId - Client mutation id this mutation depends on.
  * @property {string} model - Dependent model/resource name.
  */
-
 /**
  * Local mutation log status.
  * @typedef {"pending" | "applied-locally" | "peer-applied" | "conflict" | "rejected" | "synced"} LocalMutationStatus
  * */
-
 /**
  * Local mutation log record.
  * @typedef {object} LocalMutationLogRecord
@@ -53,6 +39,15 @@ const STORAGE_KEY_LOCKS = new Map()
  * @property {Record<string, import("../configuration-types.js").FrontendModelSyncJsonValue>} [syncResult] - Backend replay/result metadata.
  * @property {string} updatedAt - ISO timestamp when the record was last changed.
  */
+// @ts-check
+
+const DEFAULT_STORAGE_KEY = "velocious.sync.localMutationLog"
+const PENDING_STATUS_VALUES = /** @type {LocalMutationStatus[]} */ (["pending", "applied-locally", "peer-applied"])
+const PENDING_STATUSES = new Set(PENDING_STATUS_VALUES)
+const MUTATION_STATUSES = new Set([...PENDING_STATUSES, "conflict", "rejected", "synced"])
+const TERMINAL_STATUSES = new Set(["rejected", "synced"])
+/** @type {Map<string, Promise<unknown>>} */
+const STORAGE_KEY_LOCKS = new Map()
 
 /** Client-side append-only sync mutation log with pluggable persistent storage. */
 export default class LocalMutationLog {

package/src/sync/offline-grant.js

@@ -1,8 +1,3 @@
-// @ts-check
-
-const OFFLINE_GRANT_SIGNATURE_ALGORITHM = "HS256"
-const OFFLINE_GRANT_SIGNATURE_PREFIX = "hmac-sha256-"
-
 /**
  * Signed offline grant envelope.
  * @typedef {object} SignedOfflineGrant
@@ -11,7 +6,6 @@ const OFFLINE_GRANT_SIGNATURE_PREFIX = "hmac-sha256-"
  * @property {string} keyId - Signing key id.
  * @property {string} signature - Hex HMAC signature with a hmac-sha256 prefix.
  */
-
 /**
  * Backend-issued offline grant payload.
  * @typedef {object} OfflineGrant
@@ -23,7 +17,6 @@ const OFFLINE_GRANT_SIGNATURE_PREFIX = "hmac-sha256-"
  * @property {Record<string, import("../configuration-types.js").FrontendModelSyncJsonValue>} scopes - Materialized grant scopes.
  * @property {string} userId - Actor user id allowed to use the grant.
  */
-
 /**
  * Offline grant signing key.
  * @typedef {object} OfflineGrantSigningKey
@@ -31,6 +24,10 @@ const OFFLINE_GRANT_SIGNATURE_PREFIX = "hmac-sha256-"
  * @property {string} id - Public key id included in signed grant envelopes.
  * @property {string} secret - Private HMAC secret. Never expose this to clients.
  */
+// @ts-check
+
+const OFFLINE_GRANT_SIGNATURE_ALGORITHM = "HS256"
+const OFFLINE_GRANT_SIGNATURE_PREFIX = "hmac-sha256-"
 
 /**
  * Creates a signed offline grant envelope.

package/src/sync/peer-mutation-bundle.js

@@ -2,9 +2,6 @@
 
 import {createSignedMutation, mutationIdempotencyKey, verifySignedMutation} from "./device-identity.js"
 
-const PEER_MUTATION_BUNDLE_FORMAT = "velocious.sync.peer-mutation-bundle.v1"
-const EXPORTABLE_STATUSES = new Set(["pending", "applied-locally", "conflict"])
-
 /**
  * Peer mutation bundle exported by a device for offline/P2P transfer.
  * @typedef {object} PeerMutationBundle
@@ -12,7 +9,6 @@ const EXPORTABLE_STATUSES = new Set(["pending", "applied-locally", "conflict"])
  * @property {"velocious.sync.peer-mutation-bundle.v1"} format - Bundle format identifier.
  * @property {PeerMutationBundleEntry[]} mutations - Signed mutations in local sequence order.
  */
-
 /**
  * One peer mutation bundle entry.
  * @typedef {object} PeerMutationBundleEntry
@@ -20,6 +16,8 @@ const EXPORTABLE_STATUSES = new Set(["pending", "applied-locally", "conflict"])
  * @property {number} [localSequence] - Exporting device's local mutation sequence.
  * @property {import("./device-identity.js").SignedSyncMutation} signedMutation - Device-signed mutation envelope.
  */
+const PEER_MUTATION_BUNDLE_FORMAT = "velocious.sync.peer-mutation-bundle.v1"
+const EXPORTABLE_STATUSES = new Set(["pending", "applied-locally", "conflict"])
 
 /**
  * Exports local non-terminal mutations as a signed peer-transfer bundle.

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

@@ -4,6 +4,38 @@ import {randomUUID} from "crypto"
 import TableData from "../database/table-data/index.js"
 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 {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 {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 {number} serverSequence - Monotonic server sequence.
+ */
+/**
+ * @typedef {object} ServerChangeFeedRow
+ * @property {string | null} actor_device_id - Actor device id.
+ * @property {string | null} actor_user_id - Actor user id.
+ * @property {string | null} attributes_json - Attributes JSON.
+ * @property {Date | string} created_at - Creation time.
+ * @property {string} id - Entry id.
+ * @property {string | null} idempotency_key - Mutation idempotency key.
+ * @property {string} model - Frontend model name.
+ * @property {string} operation - Mutation operation.
+ * @property {string | null} payload_json - Mutation payload JSON.
+ * @property {string | null} record_id - Record id.
+ * @property {string | null} response_json - Response JSON.
+ * @property {string | null} scope_json - Scope JSON.
+ * @property {number | string} server_sequence - Server sequence.
+ */
 const DEFAULT_RETENTION_SIZE = 10000
 const DEFAULT_PAGE_SIZE = 100
 const MAX_PAGE_SIZE = 1000
@@ -464,37 +496,3 @@ function scopesEqual(changeScope, requestedScope) {
 
   return stableJsonStringify(changeScope || null) === stableJsonStringify(requestedScope)
 }
-
-/**
- * @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 {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 {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 {number} serverSequence - Monotonic server sequence.
- */
-
-/**
- * @typedef {object} ServerChangeFeedRow
- * @property {string | null} actor_device_id - Actor device id.
- * @property {string | null} actor_user_id - Actor user id.
- * @property {string | null} attributes_json - Attributes JSON.
- * @property {Date | string} created_at - Creation time.
- * @property {string} id - Entry id.
- * @property {string | null} idempotency_key - Mutation idempotency key.
- * @property {string} model - Frontend model name.
- * @property {string} operation - Mutation operation.
- * @property {string | null} payload_json - Mutation payload JSON.
- * @property {string | null} record_id - Record id.
- * @property {string | null} response_json - Response JSON.
- * @property {string | null} scope_json - Scope JSON.
- * @property {number | string} server_sequence - Server sequence.
- */

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

@@ -4,8 +4,6 @@ import {optionalBoolean, optionalInteger} from "typanic"
 
 import recordChanges from "../database/record-changes.js"
 
-const syncTaskPromises = new Map()
-
 /** @typedef {import("./sync-api-client-types.js").SyncChangeApplyResult} SyncChangeApplyResult */
 /** @typedef {import("./sync-api-client-types.js").SyncChangeEnvelope} SyncChangeEnvelope */
 /** @typedef {import("./sync-api-client-types.js").SyncChangesRequest} SyncChangesRequest */
@@ -15,6 +13,7 @@ const syncTaskPromises = new Map()
 /** @typedef {import("./sync-api-client-types.js").SyncReplayItem} SyncReplayItem */
 /** @typedef {import("./sync-api-client-types.js").SyncReplayResponse} SyncReplayResponse */
 /** @typedef {import("./sync-api-client-types.js").SyncResourceConfig} SyncResourceConfig */
+const syncTaskPromises = new Map()
 
 /**
  * Generic client-side helper for replaying pending sync envelopes through the

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

@@ -7,6 +7,23 @@ import SyncReplayUpsertApplier from "./sync-replay-upsert-applier.js"
 import {ValidationError} from "../database/record/index.js"
 import VelociousError from "../velocious-error.js"
 
+/**
+ * Resolved routed-resource registration for one replay resource type.
+ * @typedef {object} SyncReplayResourceRegistration
+ * @property {string} modelName - Effective frontend model name.
+ * @property {import("../configuration-types.js").FrontendModelResourceClassType} resourceClass - Routed resource class.
+ * @property {import("../configuration-types.js").NormalizedFrontendModelResourceConfiguration | null} resourceConfiguration - Normalized resource configuration when registry-resolved.
+ */
+/**
+ * @typedef {object} SyncReplayMutation
+ * @property {Date} clientUpdatedAt - Client-side mutation timestamp.
+ * @property {Record<string, ?>} data - Parsed mutation payload.
+ * @property {?} id - Client sync row id for per-sync responses.
+ * @property {string} resourceId - Resource id as a string.
+ * @property {string} resourceType - Resource/model name.
+ * @property {string} serializedData - JSON serialized mutation payload.
+ * @property {string} syncType - Sync operation type.
+ */
 /**
  * One declarative broadcast fanned out after a mutation applies.
  * @typedef {object} SyncReplayBroadcast
@@ -778,22 +795,3 @@ export default class SyncEnvelopeReplayService {
     await deliverDeclaredBroadcasts({args, broadcaster: this.broadcaster, broadcasts: this.broadcasts})
   }
 }
-
-/**
- * Resolved routed-resource registration for one replay resource type.
- * @typedef {object} SyncReplayResourceRegistration
- * @property {string} modelName - Effective frontend model name.
- * @property {import("../configuration-types.js").FrontendModelResourceClassType} resourceClass - Routed resource class.
- * @property {import("../configuration-types.js").NormalizedFrontendModelResourceConfiguration | null} resourceConfiguration - Normalized resource configuration when registry-resolved.
- */
-
-/**
- * @typedef {object} SyncReplayMutation
- * @property {Date} clientUpdatedAt - Client-side mutation timestamp.
- * @property {Record<string, ?>} data - Parsed mutation payload.
- * @property {?} id - Client sync row id for per-sync responses.
- * @property {string} resourceId - Resource id as a string.
- * @property {string} resourceType - Resource/model name.
- * @property {string} serializedData - JSON serialized mutation payload.
- * @property {string} syncType - Sync operation type.
- */

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

@@ -7,8 +7,6 @@ import SyncEnvelopeReplayService from "./sync-envelope-replay-service.js"
 import SyncModelChangeFeedService from "./sync-model-change-feed-service.js"
 import VelociousError from "../velocious-error.js"
 
-const QUICK_SEARCH_COLUMN = "quickSearch"
-
 /**
  * Optional client-declared sync scope carried on a changes request.
  * @typedef {object} SerializedChangesScope
@@ -16,6 +14,7 @@ const QUICK_SEARCH_COLUMN = "quickSearch"
  * @property {string | null} resourceType - Client resource/model name the scope was declared for, or null for the all-types (user) scope: one scope covering every resource type this resource authorizes for the caller, so a sync authorizes once however many types it serves.
  * @property {string[] | null} resourceTypes - For the all-types scope, the resource types the client can apply. A cheap delivery/type filter only - it narrows, never widens, what the app's authorization already allows. Null for a type-declared scope.
  */
+const QUICK_SEARCH_COLUMN = "quickSearch"
 
 /**
  * Base resource for Velocious sync endpoints.

package/src/sync/sync-scope-store.js

@@ -6,6 +6,15 @@ import UUID from "pure-uuid"
 import {scopeKey} from "./query-scope.js"
 import stableJsonStringify from "./stable-json.js"
 
+/**
+ * @typedef {object} SyncScopeRow
+ * @property {Record<string, ?>} conditions - Scope attribute conditions.
+ * @property {string | null} cursorPayload - Persisted cursor JSON payload.
+ * @property {string} id - Scope row id.
+ * @property {string | null} resourceType - Scope resource/model name, or null for the all-types (user) scope.
+ * @property {string} scopeDigest - Fixed-size deterministic digest of the canonical scope key.
+ * @property {string} state - Scope state ("active" or "removed").
+ */
 const TABLE_NAME = "velocious_sync_scopes"
 const SCOPE_DIGEST_PREFIX = "velocious-sync-scope:"
 
@@ -19,16 +28,6 @@ function scopeDigestForScope(scope) {
   return new UUID(5, "ns:URL", `${SCOPE_DIGEST_PREFIX}${scopeKey(scope)}`).format()
 }
 
-/**
- * @typedef {object} SyncScopeRow
- * @property {Record<string, ?>} conditions - Scope attribute conditions.
- * @property {string | null} cursorPayload - Persisted cursor JSON payload.
- * @property {string} id - Scope row id.
- * @property {string | null} resourceType - Scope resource/model name, or null for the all-types (user) scope.
- * @property {string} scopeDigest - Fixed-size deterministic digest of the canonical scope key.
- * @property {string} state - Scope state ("active" or "removed").
- */
-
 /**
  * Framework-owned local persistence for declared sync scopes and their cursors.
  *

package/src/testing/test-filter-parser.js

@@ -1,3 +1,13 @@
+/**
+ * ParseFiltersResult type.
+ * @typedef {object} ParseFiltersResult
+ * @property {string[]} includeTags - Tags to include.
+ * @property {string[]} excludeTags - Tags to exclude.
+ * @property {string[]} examplePatterns - Example name patterns.
+ * @property {string[]} filteredProcessArgs - Remaining process args with filter flags removed.
+ * @property {number | undefined} groups - Total number of groups for test splitting.
+ * @property {number | undefined} groupNumber - Which group to run (1-indexed).
+ */
 // @ts-check
 
 const INCLUDE_TAG_FLAGS = new Set(["--tag", "--include-tag", "-t"])
@@ -50,17 +60,6 @@ export function normalizeExamplePatterns(patterns) {
   return normalized
 }
 
-/**
- * ParseFiltersResult type.
- * @typedef {object} ParseFiltersResult
- * @property {string[]} includeTags - Tags to include.
- * @property {string[]} excludeTags - Tags to exclude.
- * @property {string[]} examplePatterns - Example name patterns.
- * @property {string[]} filteredProcessArgs - Remaining process args with filter flags removed.
- * @property {number | undefined} groups - Total number of groups for test splitting.
- * @property {number | undefined} groupNumber - Which group to run (1-indexed).
- */
-
 /**
  * Runs the parseFilters helper.
  * @param {string[]} processArgs - Process args.